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 an area of about one square kilometer to which the search is limited. If no matching place is found in this area, then the search is extended to the whole world (or the countries defined by the country filter). A possible use case for this parameter is to reduce the search space to the area around a click point in a map. |
The center and bounding box parameters are mutually exclusive. There is only one of them 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"
]
Quality:
Because there is currently no quality characteristic available for a place matching a search text, 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": "5ac06ecdbdb45321e4644b970a505fe8",
"causes": [
{
"description": "A parameter is set to an invalid value.",
"errorCode": "GENERAL_INVALID_VALUE",
"parameter": "countryFilter[0]",
"details": {
"value": "Germany"
}
}
]
}