Allows searching for places (i.e. addresses of businesses and services) matching a name given by a single text field.
Input
The places by text endpoint considers the following input fields:
| Input Field | Description |
| searchText (required) | A free-form text field to match the name of the places. |
| categoryFilter (optional) | 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. |
| countryFilter (optional) | A list of country codes to reduce the search space, which may also improve performance. Country codes should be ISO 3166-1 alpha-2 and separated by comma. In countries such as US, RU, AU, CA, and IN results can also be filtered by country subdivision specified as ISO 3166-2. In case the requested subdivision is not available, the results are filtered by the country. |
| bounding box (optional) | A rectangular area to which the search is limited. A possible use case for this parameter is to reduce the search space to a map view. |
| center (optional) | The center of a circular area to which the search is limited. The size of this area is determined by the radius parameter. A possible use case for the center parameter is to reduce the search space to the area around a click point in a map. |
| radius (optional) | The maximum distance in meters to the center position results may have. Per default the maximum distance is 1000 meters. |
The center resp. radius and bounding box parameters are mutually exclusive. There is only one type of search area allowed.
This endpoint also supports requesting a different language.
Output
If the request succeeds, the response is a list of records. Each record contains name and address of the place, its geographical position(s) and its category IDs. 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.
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:
If the search is based on a center position the distance from the center is provided in the quality element. In this case the distance is also used to sort the result list.
"quality": {
"distance": 10
}
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": "5ac06ecdbdb45321e4644b970a505fe8",
"causes": [
{
"description": "A parameter is set to an invalid value.",
"errorCode": "GENERAL_INVALID_VALUE",
"parameter": "countryFilter[0]",
"details": {
"value": "Germany"
}
}
]
}