Allows finding places (i.e. addresses of businesses and services) in a given area.
Input
The places by area endpoint considers the following input fields:
| Input Field | Description |
| area | The area which is searched for places. It is given as JSON in the body of the request (payload). Its only inner property is: |
| area.geometry | A string defining the area as GeoJSON geometry. The endpoint supports geometry types Polygon and MultiPolygon. Geometries that cause too long processing times will be rejected. In this case an error response is returned that explains the reason. |
| categoryFilter | A list of category ids used to narrow the search to certain types of places (e.g. fueling stations), given as a query parameter in the request URL. A list of possible category ids can be obtained by the Places Categories endpoint. |
This endpoint also supports requesting a different language.
{
"area": {
"geometry": "{ \"type\":\"Polygon\", \"coordinates\":[ [ [6.1281, 49.6121], [6.1297, 49.612], [6.1297, 49.6115], [6.1281, 49.6114], [6.1281, 49.6121]]]}"
}
}
Output
If the request succeeds, the response is a list of records. The list is limited to a maximum of 100 records. When this limit is reached then a corresponding warning is issued in the response. The list is empty if no matching record is found. Each record contains name and address of the place, its geographical position(s) and its category IDs.
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"
]
Quality:
Because there is no quality characteristic for a place inside an area, the quality element remains empty.
"quality": {}
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"
}
}
]
}