Constructing a request
A request to the HERE Geocoding and Search includes the basic elements shown in the following table and, in addition, may contain resource-specific parameters.
GET requests
Info
Most HERE Geocoding and Search endpoints are called with a GET method.
| Element | Value/Example | Description |
|---|---|---|
| Method | GET | |
| Scheme | https | |
| Base URL | [service].search.hereapi.com | Base URL for the [service]. Note that endpoints are named after their related service. For instance the Discover service is served by the endpoint /discover.So that the base url for the Discover service is discover.search.hereapi.com |
| Version | v1 | |
| Endpoint | /discover | Find places or locations using a free-form text query |
/autosuggest | Get suggestions to build up search queries | |
/geocode | Search for an address and return the corresponding geo-coordinates | |
/autocomplete | Get completion of the entered keystrokes to the valid addresses | |
/revgeocode | Find the nearest address to specific geo-coordinates | |
/browse | Find places data using names or category ids | |
/lookup | Find a place or other location objects using its identifier | |
| Parameters | [key]=[value]&... | Endpoint specific parameters. Note that the repetition of the same parameter keys throws a 400.Check the API Reference for more details. |
for instance the following URI
https://discover.search.hereapi.com/v1/discover?at=52.5228,13.4124&q=petrol+station&limit=5
is used to reach the service/endpoint Discover with the following parameters:
atset to the latitude52.5228and longitude13.4124qset to "petrol station"limitset to 5
POST requests
Request headers
Important context information is passed to the API using optional HTTP request headers. Wherever applicable the service relies on established and standardized headers, complementing these with some additional private headers. Some of these directly affect the results, while others help to optimize search results.
The following table describes the http request header.
| Header name | Description |
|---|---|
| Accept | Specifies which media types are acceptable for the response Accept header specification. The only value supported is application/json resulting in a standard JSON response. This value is also the default one. |
| Date | The user's local time, for example, "Mon, 08 Aug 2011 11:58:17 GMT" (see Date header specification). |
| User-Agent | A string identifying the client user agent (see User-Agent header specification, used for statistical purposes. If HERE Geocoding and Search is accessed from within a web browser, the browser should send this information automatically. For other applications, it may need to be explicitly set by the application. |
| Accept-Encoding | Allows clients to enable compressed transfer of responses. The only supported value is gzip-compression. Clients are strongly encouraged to make use of that option, as it can have a major impact on the responsiveness and performance of the client application (see Accept-Encoding header specification. |
| X-Request-ID | Allows a client to specify a different identifier for each query sent to HERE Geocoding and Search and get that {ID back in the response header. This is useful for customers own data mining and logging analysis about the correlation of responses to requests and to communicate with HERE about potential issues. |
Response customization
HERE Geocoding and Search allows the customization of the response through the query parameter. Check the dedicated chapter for details.