Allows finding places (i.e. addresses of businesses and services) near a given position.
Input
The places by position endpoint considers the following input fields:
| Input Field | Description |
|---|---|
| latitude and longitude | Latitude and longitude values of the requested position (WGS84), given as path parameters. |
| category filter | A list of category ids used to narrow the search to certain types of places (e.g. fueling stations). A list of possible category ids can be obtained by the Places Categories endpoint. |
| radius | The maximum distance in meters that results are allowed to have to the requested position. |
| limit | This value limits the length of the result list. |
This endpoint also supports requesting a different language.
Output
If the request succeeds, the response is a list of records. The list is empty if no matching record is found. Each record contains name and address of the place, its geographical position(s), its category IDs, and the distance to the requested position.
Name and Address:
Each returned record has an associated name (like "Inter-Tours Sarl"), and an address consisting of the following (possibly empty) fields:
- country name
- state
- province
- postal code
- city
- district
- subdistrict
- street
- house number
"address": {
"countryName": "Schweiz",
"state": "Vaud",
"province": "Lausanne",
"postalCode": "1006",
"city": "Lausanne",
"district": "",
"subdistrict": "",
"street": "Avenue du Rond-Point",
"houseNumber": "1"
},
"formattedAddress": "Twist & Trout Design - Avenue du Rond-Point 1, 1006 Lausanne",
"name": "Twist & Trout Design"
The formattedAddress is a single string which is suitable to display the record, e.g. in a list.
The returned address fields will be in the language spoken in that country or region, unless otherwise requested by the language parameter.
Geographical Positions:
Each returned record has one or two geographical positions:
- reference position: the actual geographic position of the place
- road access position (optional): the position where you would start driving
"referencePosition": {
"latitude": 46.51520919799805,
"longitude": 6.6285600662231445
},
"roadAccessPosition": {
"latitude": 46.5153694152832,
"longitude": 6.628580093383789
}Categories:
A place belongs to one or more categories, like e.g. "Fuel Station". Categories can be identified by their category ID strings. A list of possible category ids can be obtained by the Places Categories endpoint. Each returned place contains a list of its associated categories, represented by their category IDs:
"categoryIds": [
"navteq-lcms:700-7200-0252",
"navteq-lcms:700-7200-0000"
]Distance:
The value is given in meters from the requested position to either the reference position or the road access position (whichever is closer). The distance is also used to sort the result list.
"quality": {
"distance": 4
}
Errors:
The search is limited by an internal timeout: If a request takes very long, it will be aborted. This may typically happen if the server is very busy. In that case, an error response will be returned:
{
"description": "The request could not be processed due to an internal error.",
"errorCode": "GENERAL_INTERNAL_SERVER_ERROR",
"traceId": "e0f3b45a721e4f2d8b3f0ca5ebfb2166",
"errorId": "fdf1e24b-e180-4205-8a22-21e5d5336187"
}
If a parameter in the request has an unacceptable value, the error response will specify the erroneous parameter and its expected range.
{
"description": "The validation of the request failed. Details can be found in the property 'causes'. ",
"errorCode": "GENERAL_VALIDATION_ERROR",
"traceId": "332abf3834c94effa4ec86eb07c6da6f",
"causes": [
{
"description": "The minimum value restriction is violated.",
"errorCode": "GENERAL_MINIMUM_VALUE_VIOLATED",
"parameter": "longitude",
"details": {
"minimumValue": "-180"
}
}
]
}