{"id":22344220,"url":"https://github.com/hi-folks/milk-sdk-php","last_synced_at":"2025-10-07T14:45:14.406Z","repository":{"id":46506287,"uuid":"299679107","full_name":"Hi-Folks/milk-sdk-php","owner":"Hi-Folks","description":"Milk SDK PHP is a (fluent) open-source PHP library that makes it easy to integrate your PHP application with location services like Geocode, Route, Isoline, Search Places and Address, location data ...","archived":false,"fork":false,"pushed_at":"2022-10-07T02:52:01.000Z","size":391,"stargazers_count":8,"open_issues_count":1,"forks_count":11,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-30T03:54:14.603Z","etag":null,"topics":["geocoder-api","geolocation","hacktoberfest","hacktoberfest2021","location-data","location-services","php"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/hi-folks/milk-sdk-php","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hi-Folks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-29T16:45:04.000Z","updated_at":"2024-12-20T11:37:10.000Z","dependencies_parsed_at":"2022-07-19T22:03:52.731Z","dependency_job_id":null,"html_url":"https://github.com/Hi-Folks/milk-sdk-php","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Hi-Folks/milk-sdk-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hi-Folks%2Fmilk-sdk-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hi-Folks%2Fmilk-sdk-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hi-Folks%2Fmilk-sdk-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hi-Folks%2Fmilk-sdk-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hi-Folks","download_url":"https://codeload.github.com/Hi-Folks/milk-sdk-php/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hi-Folks%2Fmilk-sdk-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278794122,"owners_count":26046968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geocoder-api","geolocation","hacktoberfest","hacktoberfest2021","location-data","location-services","php"],"created_at":"2024-12-04T09:09:05.602Z","updated_at":"2025-10-07T14:45:14.350Z","avatar_url":"https://github.com/Hi-Folks.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Milk SDK PHP\n\n[![Actions Status](https://github.com/hi-folks/milk-sdk-php/workflows/PHP%20check%20test/badge.svg)](https://github.com/hi-folks/milk-sdk-php/actions)\n[![GitHub license](https://img.shields.io/github/license/hi-folks/milk-sdk-php)](https://github.com/hi-folks/milk-sdk-php/blob/master/LICENSE.md)\n\n![Milk SDK PHP](milk-sdk-php.png \"Milk SDK PHP\")\n\nMilk SDK PHP is a (fluent) open-source PHP library that makes it easy to integrate your PHP application with location services like:\n- [HERE **Routing** API **V8**](#routing-api-v8) and [**V7**](#routing-api-v7): for calculate routes from a starting point to destination;\n- [HERE **Weather** Destination API](#weather-api): for getting weather forecasts;\n- [HERE **Geocoding** API](#geocoding-api): for converting addresses into geographic coordinates;\n- [HERE **Reverse Geocoding** API](#reverse-geocoding-api): for converting coordinates into addresses;\n- [HERE **Isoline** API](#isoline-api): for calculating the area that a driver (or a biker or a walker) can reach within a given time or distance;\n- [HERE **Discover** API](#discover-api): for searching addresses, places and locations;\n- [HERE **Map Image** API](#map-image-api): for creating static image of a map;\n- [HERE **Data Hub** API](#use-here-data-hub);\n- ... other coming soon ...\n\n\n## Getting Started\n\n### Install the SDK\n\nIn your PHP project install package via Composer:\n\n```sh\ncomposer require hi-folks/milk-sdk-php\n```\n## Obtain HERE API Key\nTo use HERE Location Services you will need an API key. The API key is a unique identifier that is used to authenticate API requests associated with your project.\nThere is a official tutorial for retrieving the API Key:\nhttps://developer.here.com/tutorials/getting-here-credentials/\n\n## Weather API\n\nWith Weather API class you can get weather forecasts, observation, or alerts for a specific location.\n\nYou can call the following methods to get the corresponding weather information:\n\n- *productObservation()*: Get current weather conditions from the eight closest locations to the specified location.\n- *productAlerts()*: Get forecasted weather alerts for the next 24 hours.\n- *productForecast7days()*: Get morning, afternoon, evening and night weather forecasts for the next seven days.\n- *productForecast7daysSimple()*: Get daily weather forecasts for the next seven days.\n- *productForecastAstronomy()*: Get information on when the sun and moon rise and set, and on the phase of the moon for the next seven days.\n- *productForecastHourly()*: Get hourly weather forecasts for the next seven days.\n- *productNwsAlerts()*: Get all active watches and warnings for the US and Canada.\n\nFor example, to retrieve weather forecasts in Berlin:\n\n```php\n$jsonWeather = Weather::instance()\n    -\u003esetAppIdAppCode($hereAppId, $hereAppCode)\n    -\u003eproductForecast7days()\n    -\u003ename(\"Berlin\")\n    -\u003eget();\nvar_dump($jsonWeather-\u003egetData());\nvar_dump($jsonWeather-\u003eisError());\nvar_dump($jsonWeather-\u003egetErrorMessage());\nvar_dump($jsonWeather-\u003egetDataAsJsonString());\n```\n\n## Routing API (v7)\nTo retrieve the fastest route by foot\n\n```php\n$r = (new RoutingV7())\n    -\u003esetApiKey($hereApiKey)\n    -\u003ebyFoot()\n    -\u003etypeFastest()\n    -\u003estartingPoint(52.5160, 13.3779)\n    -\u003edestination(52.5185, 13.4283)\n    -\u003eget();\nvar_dump($r-\u003egetData());\nvar_dump($r-\u003eisError());\nvar_dump($r-\u003egetErrorMessage());\nvar_dump($r-\u003egetDataAsJsonString());\n```\n\nInstead of using get(), you could use _getManeuverInstructions()_ method:\n\n```php\n$r = (new RoutingV7())\n    -\u003esetApiKey($hereApiKey)\n    -\u003ebyFoot()\n    -\u003etypeFastest()\n    -\u003estartingPoint(52.5160, 13.3779)\n    -\u003edestination(52.5185, 13.4283)\n    -\u003egetManeuverInstructions();\n\nvar_dump($r);\n```\n\n## Routing API (v8)\nTo retrieve the fastest route by car\n\n```php\n$routingActions = RoutingV8::instance()\n    -\u003esetApiKey($hereApiKey)\n    -\u003ebyCar()\n    -\u003eroutingModeFast()\n    -\u003estartingPoint(52.5160, 13.3779)\n    -\u003edestination(52.5185, 13.4283)\n    -\u003ereturnInstructions()\n    -\u003elangIta()\n    -\u003egetDefaultActions();\n\nforeach ($routingActions as $key =\u003e $action) {\n    echo \" - \".$action-\u003einstruction . PHP_EOL;\n}\n```\n\n## Geocoding API\nIn order to retrieve geo-coordinates (latitude, longitude) of a known address or place.\n\n```php\nuse HiFolks\\Milk\\Here\\RestApi\\Geocode;\n$hereApiKey = \"Your API KEY\";\n$r = Geocode::instance()\n    -\u003esetApiKey($hereApiKey)\n    -\u003ecountry(\"Italia\")\n    -\u003eq(\"Colosseo\")\n    -\u003elangIta()\n    -\u003eget();\nvar_dump($r-\u003egetData());\nvar_dump($r-\u003eisError());\nvar_dump($r-\u003egetErrorMessage());\nvar_dump($r-\u003egetDataAsJsonString());\n```\n\n## Reverse Geocoding API\nIn order to find the nearest address to specific geo-coordinates:\n\n```php\nuse HiFolks\\Milk\\Here\\RestApi\\ReverseGeocode;\n$hereApiKey = \"Your API KEY\";\n$r = ReverseGeocode::instance()\n    -\u003esetApiKey($hereApiKey)\n    -\u003eat(41.88946,12.49239)\n    -\u003elimit(5)\n    -\u003elang(\"en_US\")\n    -\u003eget();\nvar_dump($r-\u003egetData());\nvar_dump($r-\u003eisError());\nvar_dump($r-\u003egetErrorMessage());\nvar_dump($r-\u003egetDataAsJsonString());\n\nif ($r-\u003eisError()) {\n    echo \"Error: \". $r-\u003egetErrorMessage();\n} else {\n    $items = $r-\u003egetData()-\u003eitems;\n    foreach ($items as $key =\u003e $item) {\n        echo \" - \" .$item-\u003etitle.\n            \" : ( \".$item-\u003eposition-\u003elat . \",\" . $item-\u003eposition-\u003elng .\n            \" ) , distance:\" . $item-\u003edistance . \" , type: \" . $item-\u003eresultType . PHP_EOL;\n    }\n}\n```\n\n## Isoline API\n```php\nuse HiFolks\\Milk\\Here\\RestApi\\Isoline;\n$hereApiKey = \"yourapikey\";\n$isoline = Isoline::instance()\n    -\u003esetApiKey($hereApiKey)\n    -\u003eoriginPoint(41.890251, 12.492373)\n    -\u003ebyFoot()\n    -\u003erangeByTime(600) // 10 minutes\n    -\u003eget();\n\n```\n## Map Image Api\nWith MapImage class you can create static image of a map.\nFor the map you can define:\n- *center()*: the center of the map;\n- *addPoi()*: add a point in the map;\n- *zoom()*: set the zoom level;\n- *height()*: set the height of image (in pixel);\n- *width()*: set the width of the image (in pixel).\n```php\nuse Hifolks\\milk\\here\\RestApi\\MapImage;\n$hereApiKey = \"yourapikey\";\n$imageUrl = MapImage::instance($hereApiKey)\n    -\u003ecenter(45.548, 11.54947)\n    -\u003eaddPoi(45, 12, \"ff0000\")\n    -\u003eaddPoi(45.1, 12.1, \"00ff00\")\n    -\u003eaddPoi(45.2, 12.2, \"0000ff\", \"\", \"12\", \"Test 3\")\n    -\u003ezoom(12)\n    -\u003eheight(2048)\n    -\u003ewidth(2048 / 1.4)\n    -\u003egetUrl();\n```\n\nYou can use also the Geocoding functionality with *centerAddress()* method.\n```php\n$image = MapImage::instance($hereApiKey)\n    -\u003ecenterAddress(\"Venezia\")\n    -\u003ezoom(12)\n    -\u003eheight(2048)\n    -\u003ewidth(intval(2048 / 1.4));\n$imageUrl = $image-\u003egetUrl();\n```\n\n## Discover API\nIf you need to  search an address or a place and you need to validate it and obtain some other information about the location, you can use *Discover API* endpoint via Discover class.\n```php\n$address = \"Basilica San Marco,  venezia\";\n// instance the class\n$discover = Discover::instance($hereApiKey)\n// define the address\n    -\u003eq($address)\n// define a center point (for example Rome)\n    -\u003eat(41.902782, 12.496366)\n// define where to limit the search, in this case ITA is the country code for Italy\n    -\u003einCountry(\"ITA\")\n    -\u003eget();\n```\n\nIf you need to search an address in Italy, you can use inItaly() method:\n```php\n$address = \"Basilica San Marco,  venezia\";\n$discover = Discover::instance($hereApiKey)\n    -\u003eq($address)\n    -\u003einItaly()\n    -\u003eget();\n```\n\n\n## Use HERE Data Hub\n### Configuring XYZ HUB\n\nWith this SDK you can consume DataHub (XYZ) API.\nYou have 2 options:\n- use your own instance of XYZ HUB\nor\n- use Data Hub Cloud https://developer.here.com/documentation/studio/map_customization_suite_hlp/dev_guide/index.html\n\n#### Configure SDK with your own instance of XYZ HUB\n\nRunning your own instance of XYZ HUB means that you already have your instance of https://github.com/heremaps/xyz-hub.\nA tutorial about how to set up XYZ Hub locally (on localhost): https://dev.to/robertobutti/restful-web-service-for-geospatial-data-12ii\n\nCreate a _.env_ file.\nFill it with:\n\n```\nXYZ_ACCESS_TOKEN=\"\"\nXYZ_API_HOSTNAME=\"http://localhost:8080\"\n```\n\n#### Configure SDK with XYZ HUB Cloud service\n\nUsing XYZ HUB Cloud Service means that you are using this host https://xyz.api.here.com.\n\nTo use this service you need to sign in as developer on https://developer.here.com/ and create your plan (for example Freemium) and obtain your Access Token.\n\nOnce you have your access token, create a _.env_ file. You can start from a sample file (_.env.dist_):\n\n```sh\ncp .env.dist .env\n```\n\nThen, you need to fill your XYZ_ACCESS_TOKEN in .env file with your access token.\n\n## Quick Examples\n\nIn order to use the Milk SDK, you need to:\n\n- create a PHP file\n- include the autoload.php file\n- declare all imports via _use_\n- load environment configuration (via _Dotenv_)\n- get your token\n- get your XYZ Spaces\n- display your result\n\n```php\n\u003c?php\n// include the autoload.php file\nrequire \"./vendor/autoload.php\";\n// declare all imports via \"use\"\nuse HiFolks\\Milk\\Here\\Xyz\\Space\\XyzSpace;\n// set your token\n$xyzToken = \"your xyz space token\";\n// Get your XYZ Spaces (XyzResponse class)\n$s = XyzSpace::instance($xyzToken)-\u003eget();\n// display your result\nvar_dump($s-\u003egetData());\n```\n\n### Retrieve your XYZ Spaces\n\nTo get your XYZ Spaces:\n\n```php\n$s = XyzSpace::instance($xyzToken)-\u003eget();\n```\n\nTo get XYZ Spaces by everybody (not only your own XYZ Spaces):\n\n```php\n$s =  XyzSpace::instance($xyzToken)-\u003eownerAll()-\u003eget();\n```\n\n### Delete Space\n\nTo delete a XYZ Space:\n\n```php\n$xyzSpaceDeleted = XyzSpace::instance($xyzToken)-\u003edelete($spaceId);\n```\n\n### Create Space\n\nTo create a new XYZ Space:\n\n```php\n$xyzSpaceCreated = XyzSpace::instance($xyzToken)-\u003ecreate(\"My Space\", \"Description\");\n```\n\n### Update Space\n\nTo update the XYZ Space with space id == \\$spaceId:\n\n```php\n$obj = new \\stdClass;\n$obj-\u003etitle = \"Edited Title\";\n$obj-\u003edescription = \"Edited Description\";\n$retVal = $space-\u003eupdate($spaceId, $obj);\n```\n\n### Statistics\n\nThe get statistics from XYZ Space:\n\n```php\n$statistics =  XyzSpaceStatistics::instance($xyzToken)-\u003espaceId($spaceId)-\u003eget();\n```\n\n### Features\n\nIterate features\n\n```php\n/** XyzSpaceFeature $xyzSpaceFeature */\n$xyzSpaceFeature = new XyzSpaceFeature::instance($xyzToken);\n$result = $xyzSpaceFeature-\u003eiterate($spaceId)-\u003eget();\n```\n\n### Retrieve 1 Feature\n\nYou need to use feature() method with $featureId and $spaceId\n\n```php\n$xyzSpaceFeature = XyzSpaceFeature::instance($xyzToken);\n$result = $xyzSpaceFeature-\u003efeature($featureId, $spaceId)-\u003eget();\n```\n\n### Create or Edit 1 Feature\n\nTo create or edit a Feature you can use saveOne() method.\n\n\n```php\n$spaceId = \"yourspaceid\";\n$featureId = \"yourfeatureid\";\n$geoJson = new GeoJson();\n$properties = [\n    \"name\" =\u003e \"Berlin\",\n    \"op\" =\u003e \"Put\"\n];\n$geoJson-\u003eaddPoint(52.5165, 13.37809, $properties, $featureId);\n$feature = XyzSpaceFeatureEditor::instance($xyzToken);\n$result = $feature-\u003efeature($geoJson-\u003eget())-\u003esaveOne($spaceId, $featureId);\n$feature-\u003edebug();\n```\n\n### Create multiple features from a geojson file\n\nIf you have a Geojson File, you can upload it into a space.\n\n```php\n$spaceId = \"yourspaceid\";\n$file = \"https://data.cityofnewyork.us/api/geospatial/arq3-7z49?method=export\u0026format=GeoJSON\";\n$response = XyzSpaceFeatureEditor::instance($xyzToken)\n    -\u003eaddTags([\"file\"])\n    -\u003egeojson($file)\n    -\u003ecreate($spaceId);\n```\n\n### Search features by property\n\nTo search features by properties you can use *addSearchParams* to add serach params, in the example below, you are searching features with *name* property equals \"Colosseo\".\n\n```php\n$spaceId = \"yourspaceid\";\n$xyzSpaceFeature = XyzSpaceFeature::instance($xyzToken)-\u003eaddSearchParams(\"p.name\", \"Colosseo\");\n$result = $xyzSpaceFeature-\u003esearch($spaceId)-\u003eget();\n```\n### Search features by proximity\n\nTo search feature close to latitude=41.890251 and longitude=12.492373 with a radius less than 1000 meters (close to Colosseum):\n\n```php\n$spaceId = \"yourspaceid\";\n$result = XyzSpaceFeature::instance($xyzToken)-\u003espatial($spaceId,  41.890251, 12.492373,  1000)-\u003eget();\n```\n\n\n## Useful reference\n\n### Data Hub API\n\n- ReDoc API documentation: https://xyz.api.here.com/hub/static/redoc/\n- Open API documentation: https://xyz.api.here.com/hub/static/swagger/\n\n### HERE Destination Weather API\n\n- Overview: https://developer.here.com/documentation/destination-weather/dev_guide/topics/overview.html\n- API Reference: https://developer.here.com/documentation/destination-weather/dev_guide/topics/api-reference.html\n\n### HERE Rest Routing V8 API\n\n- Overview: https://developer.here.com/documentation/routing-api/8.9.1/dev_guide/topics/use-cases/calculate-route.html\n- API Reference: https://developer.here.com/documentation/routing-api/8.9.1/api-reference-swagger.html\n\n### HERE Rest Geocoding API\n\n- Overview: https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-geocode-brief.html\n\n### HERE Rest Reverse Geocoding API\n\n- Overview: https://developer.here.com/documentation/geocoding-search-api/dev_guide/topics/endpoint-reverse-geocode-brief.html\n\n### HERE Rest Isoline API\n\n- Overview: https://developer.here.com/documentation/isoline-routing-api/dev_guide/index.html\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhi-folks%2Fmilk-sdk-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhi-folks%2Fmilk-sdk-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhi-folks%2Fmilk-sdk-php/lists"}