Search for content

Places by Text

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 FieldDescription
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"
            }
        }
    ]
}