README

Milk SDK PHP 是一个 (流式) 开源 PHP 库，它使您的 PHP 应用程序轻松集成到以下位置服务中：

此处路由 API V8 和 V7：计算起点到终点的路线；
HERE 天气目的地 API：获取天气预报；
HERE 地理编码 API：将地址转换为地理坐标；
HERE 反向地理编码 API：将坐标转换为地址；
HERE 等高线 API：计算驾驶员（或骑自行车者或步行者）在给定时间或距离内可以到达的区域；
HERE 发现 API：搜索地址、地点和位置；
HERE 地图图像 API：创建地图的静态图像；
HERE 数据中心 API;
... 更多即将推出 ...

入门

安装 SDK

在您的 PHP 项目中，使用 Composer 安装软件包

composer require hi-folks/milk-sdk-php

获取 HERE API 密钥

要使用 HERE 位置服务，您需要一个 API 密钥。API 密钥是用于验证与您的项目相关的 API 请求的唯一标识符。有关获取 API 密钥的官方教程：https://developer.here.com/tutorials/getting-here-credentials/

天气 API

使用 Weather API 类，您可以获取特定位置的天气预报、观测或警报。

您可以通过调用以下方法获取相应的天气信息：

productObservation()：从指定位置最近的八个位置获取当前天气条件。
productAlerts()：获取未来 24 小时的天气预报警报。
productForecast7days()：获取未来七天的早上、下午、晚上和夜间天气预报。
productForecast7daysSimple()：获取未来七天的每日天气预报。
productForecastAstronomy()：获取未来七天太阳和月亮升起和落下的时间以及月亮的相位信息。
productForecastHourly()：获取未来七天的每小时天气预报。
productNwsAlerts()：获取美国和加拿大的所有活跃的观察和警告。

例如，要检索柏林的天气预报：

$jsonWeather = Weather::instance()
    ->setAppIdAppCode($hereAppId, $hereAppCode)
    ->productForecast7days()
    ->name("Berlin")
    ->get();
var_dump($jsonWeather->getData());
var_dump($jsonWeather->isError());
var_dump($jsonWeather->getErrorMessage());
var_dump($jsonWeather->getDataAsJsonString());

路由 API (v7)

检索最快的步行路线

$r = (new RoutingV7())
    ->setApiKey($hereApiKey)
    ->byFoot()
    ->typeFastest()
    ->startingPoint(52.5160, 13.3779)
    ->destination(52.5185, 13.4283)
    ->get();
var_dump($r->getData());
var_dump($r->isError());
var_dump($r->getErrorMessage());
var_dump($r->getDataAsJsonString());

您可以使用 getManeuverInstructions() 方法代替 get()

$r = (new RoutingV7())
    ->setApiKey($hereApiKey)
    ->byFoot()
    ->typeFastest()
    ->startingPoint(52.5160, 13.3779)
    ->destination(52.5185, 13.4283)
    ->getManeuverInstructions();

var_dump($r);

路由 API (v8)

检索最快的驾车路线

$routingActions = RoutingV8::instance()
    ->setApiKey($hereApiKey)
    ->byCar()
    ->routingModeFast()
    ->startingPoint(52.5160, 13.3779)
    ->destination(52.5185, 13.4283)
    ->returnInstructions()
    ->langIta()
    ->getDefaultActions();

foreach ($routingActions as $key => $action) {
    echo " - ".$action->instruction . PHP_EOL;
}

地理编码 API

为了检索已知地址或地点的地理坐标（纬度，经度）。

use HiFolks\Milk\Here\RestApi\Geocode;
$hereApiKey = "Your API KEY";
$r = Geocode::instance()
    ->setApiKey($hereApiKey)
    ->country("Italia")
    ->q("Colosseo")
    ->langIta()
    ->get();
var_dump($r->getData());
var_dump($r->isError());
var_dump($r->getErrorMessage());
var_dump($r->getDataAsJsonString());

反向地理编码 API

为了找到特定地理坐标最近的地址。

use HiFolks\Milk\Here\RestApi\ReverseGeocode;
$hereApiKey = "Your API KEY";
$r = ReverseGeocode::instance()
    ->setApiKey($hereApiKey)
    ->at(41.88946,12.49239)
    ->limit(5)
    ->lang("en_US")
    ->get();
var_dump($r->getData());
var_dump($r->isError());
var_dump($r->getErrorMessage());
var_dump($r->getDataAsJsonString());

if ($r->isError()) {
    echo "Error: ". $r->getErrorMessage();
} else {
    $items = $r->getData()->items;
    foreach ($items as $key => $item) {
        echo " - " .$item->title.
            " : ( ".$item->position->lat . "," . $item->position->lng .
            " ) , distance:" . $item->distance . " , type: " . $item->resultType . PHP_EOL;
    }
}

等高线 API

use HiFolks\Milk\Here\RestApi\Isoline;
$hereApiKey = "yourapikey";
$isoline = Isoline::instance()
    ->setApiKey($hereApiKey)
    ->originPoint(41.890251, 12.492373)
    ->byFoot()
    ->rangeByTime(600) // 10 minutes
    ->get();

地图图像 API

使用 MapImage 类，您可以创建地图的静态图像。对于地图，您可以定义以下属性：

center()：地图的中心；
addPoi()：在地图上添加一个点；
zoom()：设置缩放级别；
height()：设置图像的高度（以像素为单位）；
width()：设置图像的宽度（以像素为单位）。

use Hifolks\milk\here\RestApi\MapImage;
$hereApiKey = "yourapikey";
$imageUrl = MapImage::instance($hereApiKey)
    ->center(45.548, 11.54947)
    ->addPoi(45, 12, "ff0000")
    ->addPoi(45.1, 12.1, "00ff00")
    ->addPoi(45.2, 12.2, "0000ff", "", "12", "Test 3")
    ->zoom(12)
    ->height(2048)
    ->width(2048 / 1.4)
    ->getUrl();

您还可以使用 centerAddress() 方法使用地理编码功能。

$image = MapImage::instance($hereApiKey)
    ->centerAddress("Venezia")
    ->zoom(12)
    ->height(2048)
    ->width(intval(2048 / 1.4));
$imageUrl = $image->getUrl();

发现 API

如果您需要搜索地址或地点，并且需要验证它并获取有关位置的一些其他信息，您可以通过 Discover 类使用 Discover API 端点。

$address = "Basilica San Marco,  venezia";
// instance the class
$discover = Discover::instance($hereApiKey)
// define the address
    ->q($address)
// define a center point (for example Rome)
    ->at(41.902782, 12.496366)
// define where to limit the search, in this case ITA is the country code for Italy
    ->inCountry("ITA")
    ->get();

如果您需要搜索意大利的地址，可以使用 inItaly() 方法。

$address = "Basilica San Marco,  venezia";
$discover = Discover::instance($hereApiKey)
    ->q($address)
    ->inItaly()
    ->get();

使用 HERE 数据中心

配置 XYZ HUB

使用此 SDK，您可以消费 DataHub (XYZ) API。您有两种选择：

使用自己的 XYZ HUB 实例，或者
使用数据中心云服务 https://developer.here.com/documentation/studio/map_customization_suite_hlp/dev_guide/index.html

使用自己的 XYZ HUB 实例配置 SDK

运行自己的 XYZ HUB 实例意味着您已经有了 https://github.com/heremaps/xyz-hub 的实例。有关如何在本地设置 XYZ Hub（在 localhost 上）的教程： https://dev.to/robertobutti/restful-web-service-for-geospatial-data-12ii

创建一个 .env 文件。填写以下内容：

XYZ_ACCESS_TOKEN=""
XYZ_API_HOSTNAME="https://:8080"

使用 XYZ HUB 云服务配置 SDK

使用 XYZ HUB 云服务意味着您正在使用此主机 https://xyz.api.here.com。

要使用此服务，您需要在 https://developer.here.com/ 上以开发者的身份登录并创建您的计划（例如，Freemium）并获取您的访问令牌。

一旦您有了访问令牌，创建一个 .env 文件。您可以从样本文件（.env.dist）开始。

cp .env.dist .env

然后，您需要将您的 XYZ_ACCESS_TOKEN 填充到 .env 文件中，使用您的访问令牌。

快速示例

为了使用 Milk SDK，您需要：

创建一个 PHP 文件
包含 autoload.php 文件
通过 use 声明所有导入
加载环境配置（通过 Dotenv）
获取您的令牌
获取您的 XYZ Spaces
显示您的结果

<?php
// include the autoload.php file
require "./vendor/autoload.php";
// declare all imports via "use"
use HiFolks\Milk\Here\Xyz\Space\XyzSpace;
// set your token
$xyzToken = "your xyz space token";
// Get your XYZ Spaces (XyzResponse class)
$s = XyzSpace::instance($xyzToken)->get();
// display your result
var_dump($s->getData());

检索您的 XYZ Spaces

要获取您的 XYZ Spaces

$s = XyzSpace::instance($xyzToken)->get();

要获取所有人的 XYZ Spaces（而不仅仅是您自己的 XYZ Spaces）

$s =  XyzSpace::instance($xyzToken)->ownerAll()->get();

删除空间

要删除一个 XYZ Space

$xyzSpaceDeleted = XyzSpace::instance($xyzToken)->delete($spaceId);

创建空间

要创建一个新的 XYZ Space

$xyzSpaceCreated = XyzSpace::instance($xyzToken)->create("My Space", "Description");

更新空间

要更新空间 id == $spaceId 的 XYZ Space

$obj = new \stdClass;
$obj->title = "Edited Title";
$obj->description = "Edited Description";
$retVal = $space->update($spaceId, $obj);

统计信息

从 XYZ Space 获取统计信息

$statistics =  XyzSpaceStatistics::instance($xyzToken)->spaceId($spaceId)->get();

功能

迭代功能

/** XyzSpaceFeature $xyzSpaceFeature */
$xyzSpaceFeature = new XyzSpaceFeature::instance($xyzToken);
$result = $xyzSpaceFeature->iterate($spaceId)->get();

检索 1 个功能

您需要使用 feature() 方法与 $featureId 和 $spaceId

$xyzSpaceFeature = XyzSpaceFeature::instance($xyzToken);
$result = $xyzSpaceFeature->feature($featureId, $spaceId)->get();

创建或编辑 1 个功能

要创建或编辑一个功能，您可以使用 saveOne() 方法。

$spaceId = "yourspaceid";
$featureId = "yourfeatureid";
$geoJson = new GeoJson();
$properties = [
    "name" => "Berlin",
    "op" => "Put"
];
$geoJson->addPoint(52.5165, 13.37809, $properties, $featureId);
$feature = XyzSpaceFeatureEditor::instance($xyzToken);
$result = $feature->feature($geoJson->get())->saveOne($spaceId, $featureId);
$feature->debug();

从 Geojson 文件创建多个功能

如果您有一个 Geojson 文件，您可以将它上传到空间中。

$spaceId = "yourspaceid";
$file = "https://data.cityofnewyork.us/api/geospatial/arq3-7z49?method=export&format=GeoJSON";
$response = XyzSpaceFeatureEditor::instance($xyzToken)
    ->addTags(["file"])
    ->geojson($file)
    ->create($spaceId);

按属性搜索功能

要按属性搜索功能，您可以使用 addSearchParams 添加搜索参数，在下面的示例中，您正在搜索具有 name 属性等于 "Colosseo" 的功能。

$spaceId = "yourspaceid";
$xyzSpaceFeature = XyzSpaceFeature::instance($xyzToken)->addSearchParams("p.name", "Colosseo");
$result = $xyzSpaceFeature->search($spaceId)->get();

按邻近性搜索功能

要搜索接近纬度=41.890251 和经度=12.492373 且半径小于 1000 米的功能（靠近罗马斗兽场）

$spaceId = "yourspaceid";
$result = XyzSpaceFeature::instance($xyzToken)->spatial($spaceId,  41.890251, 12.492373,  1000)->get();

有用参考

数据中心 API

ReDoc API 文档： https://xyz.api.here.com/hub/static/redoc/
开放API文档：https://xyz.api.here.com/hub/static/swagger/

HERE目的地天气API

HERE Rest路由V8 API

hi-folks / milk-sdk-php

维护者

详细信息