- Products ProductsLocation Services
Solve complex location problems from geofencing to custom routing
PlatformCloud environments for location-centric solution development, data exchange and visualization
Tracking & PositioningFast and accurate tracking and positioning of people and devices, indoors or outdoors
APIs & SDKsEasy to use, scaleable and flexible tools to get going quickly
Developer EcosystemsAccess Location Services on your favorite developer platform ecosystem
- Documentation DocumentationOverview OverviewServices ServicesApplications ApplicationsDevelopment Enablers Development EnablersContent ContentHERE Studio HERE StudioHERE Workspace HERE WorkspaceHERE Marketplace HERE MarketplacePlatform Foundation and Policy Documents Platform Foundation and Policy Documents
- Pricing
- Resources ResourcesTutorials TutorialsExamples ExamplesBlog & Release Announcements Blog & Release AnnouncementsChangelog ChangelogDeveloper Newsletter Developer NewsletterKnowledge Base Knowledge BaseFeature List Feature ListSupport Plans Support PlansSystem Status System StatusLocation Services Coverage Information Location Services Coverage InformationSample Map Data for Students Sample Map Data for Students
- Help
Location Contexts
Both Places API and GS7 share the concept of location contexts to which search results are relevant. Query location contexts are typically materialized through a search center and/or a circle or a bounding box.
Geo positions are in both products expressed with a pair of decimal values (WGS 84 coordinate system) separated by a comma: latitude,longitude. For instance: 52.53044,13.41112 . Note that unlike Places API, GS7 does not yet support for geo-positions the optional third altitude dimension, the position uncertainty, nor the map, gps, sgps projection variants.
Search center
Most Places API and GS7 queries expect a search center. Search centers are provided through the query URL at parameter:
| product | at format | example |
|---|---|---|
| Places API | latitude,longitude[;cgen=(map|gps|sgps)][;u=\d+] | 52.5304417,13.4111201,100;cgen=gps;u=100 |
| GS7 | latitude,longitude | 52.5304417,13.4111201 |
Note that GS7 only supports explicit search centers. Applications using the Geolocation header on a Places API endpoint must set the at parameter to the very same value on the related GS7 endpoint.
For instance a request to Places API Autosuggest entrypoint with a Geolocation: 52.5304417,13.4111201 header needs to become a request to GS7 Autosuggest service with the URL parameter at=52.5304417,13.4111201.
Impacted Places API entrypoints: Autosuggest, Search, Browse, Explore, By-Corridor, Here, Around
Explicit bounding box and circle
The location context can be given though a geographical constraint, in form of a circle or a bounding rectangle. Both Places API and GS7 are supporting these constraints through the query URL in parameter.
| product | in circle format | example |
|---|---|---|
| Places API | latitude,longitude;r=\d+(.\d+)?[;cgen=(map|gps|sgps)][;u=\d+] | 53.12,10.15,100;cgen=gps;u=100;r=10500.63 |
| GS7 | circle:latitude,longitude;r=\d+ | circle:53.12,10.15;r=10501 |
The radius r is specified in meters.
| product | in bounding box format | example |
|---|---|---|
| Places API | west_longitude,south_latitude,east_longitude,north_latitude | 13.125,52.362,13.661,52.693 |
| GS7 | bbox:west_longitude,south_latitude,east_longitude,north_latitude | bbox:13.125,52.362,13.661,52.693 |
Note that GS7 only supports explicit bounding boxes, insuring the strict inclusion of the search results. Places API X-Map-Viewport header values must be ported to a in=bbox URL parameter. For instance a request to Places API Browse entrypoint with the header X-Map-Viewport: 13.125,52.362,13.661,52.693 needs to become a request to GS7 service with a URL parameter in=bbox: 13.125,52.362,13.661,52.693. The result items returned by GS7 will then always be within that bounding rectangle.
Impacted Places API entrypoints: Autosuggest, Search, Browse, Explore, Around
Route and compressed route
Routes are expressed as corridors in both Places API and GS7 products: a sequence of geo-positions and a width in meters. Search along the route is described in GS7 developer guide.
While Places API supports both a compressed and an uncompressed format, GS7 opted to only cover the compressed format to reduce URL length.
The compressions used in Places API and GS7 are very similar. GS7 uses the "HERE flexible-polyline" encoding, a generalization of the "HERE polyline encoding", itself a variant of the "Encoded Polyline algorythm Format". So that on both products, compressed values comply to the schema: [a-zA-Z0-9_-]+(;w=\d+)?[a-zA-Z0-9._-]+.
For the same list of points, the HERE flexible polyline is equal to the HERE polyline with no third dimension, prepended by the header BF. For example the very simple route of 1000 meters width between both points 52.5199356,13.3866272 and 52.5100899,13.2816896 is compressed as:
-
05xgKuy2xCx9B7vU;w=1000for Places APIcompressedRouteparameter -
BF05xgKuy2xCx9B7vU;w=1000for GS7routeparameter
GS7 currently does not support the urgency for search along a route: The urgency is always 1.0. Variable widths (CW, HW, DW) are also currently not supported. Corridors width on GS7 are of fixed width, through the w sub-parameter (per default 1000m).
Developers can check the here-polyline-converter package to transform strings from HERE Polyline to HERE flexible-polyline.
Impacted Places API entrypoints: Autosuggest, Search, Browse, By-Corridor
