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=1000 for Places API compressedRoute parameter
  • BF05xgKuy2xCx9B7vU;w=1000 for GS7 route parameter

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

results matching ""

    No results matching ""