# Search API

> Search API on Apizie: 14 endpoints (Additional Data, Category Search, Geocode, Geometry Filter, …) returned as clean JSON through one API key. Send your own provider key in the x-upstream-key header. Call it over REST at https://apizie.tech/v1/places:tomtom-search/{endpoint} or from Claude, ChatGPT and Cursor through the Apizie MCP server. Free plan: 1,000 requests a month.

- Project key: `places:tomtom-search`
- Category: Places
- Status: byok
- Source: https://developer.tomtom.com/contact-us
- Page: https://apizie.tech/api/places/tomtom-search
- OpenAPI: https://apizie.tech/api/places/tomtom-search/openapi.json

Search API is a RESTful API that allows developers to run a single line fuzzy search for addresses and POIs. Search API returns the latitude/longitude of a specific address, cross street, geographic feature, or point…

## Endpoints

### Additional Data
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-additional-data-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| ext | string | yes | Expected response format. |
| geometries | string | yes | Comma separated list of geometry UUIDs, previously retrieved from an Search API request. |
| geometriesZoom | integer | no | Defines the precision of the geometries. |

### Category Search
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-category-search-query-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| query | string | yes | Query string. Must be properly URL encoded. |
| ext | string | yes | Expected response format. |
| typeahead | boolean | no | If the "typeahead" flag is set, the query will be interpreted as a partial input and the search will enter predictive mode. |
| limit | integer | no | Maximum number of search results that will be returned. |
| ofs | integer | no | Starting offset of the returned results within the full result set. |
| countrySet | string | no | Comma separated string of country codes. This will limit the search to the specified countries. |
| lat | number | no | Latitude where results should be biased. NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| lon | number | no | Longitude where results should be biased NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| radius | integer | no | If radius and position are set, the results will be constrained to the defined area. The radius parameter is specified in meters. |
| topLeft | string | no | Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| btmRight | string | no | Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |
| extendedPostalCodesFor | string | no | Indexes for which extended postal codes should be included in the results. Available indexes are: - Addr = Address ranges - Geo =… |
| view | string | no | Geopolitical View. |

### Geocode
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-geocode-query-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| query | string | yes | Query string. Must be properly URL encoded. |
| ext | string | yes | Expected response format. |
| storeResult | boolean | no | If the "storeResult" flag is set, the query will be interpreted as a stored geocode and will be billed according to the terms of use. |
| typeahead | boolean | no | If the "typeahead" flag is set, the query will be interpreted as a partial input and the search will enter predictive mode. |
| limit | integer | no | Maximum number of search results that will be returned. |
| ofs | integer | no | Starting offset of the returned results within the full result set. |
| countrySet | string | no | Comma separated string of country codes. This will limit the search to the specified countries. |
| lat | number | no | Latitude where results should be biased. NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| lon | number | no | Longitude where results should be biased NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| radius | integer | no | If radius and position are set, the results will be constrained to the defined area. The radius parameter is specified in meters. |
| topLeft | string | no | Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| btmRight | string | no | Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |
| extendedPostalCodesFor | string | no | Indexes for which extended postal codes should be included in the results. Available indexes are: - Addr = Address ranges - Geo =… |
| view | string | no | Geopolitical View. |

### Geometry Filter
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-geometry-filter-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| ext | string | yes | Expected response format. |
| geometryList | string | yes | List of geometries to filter by. Available types are CIRCLE (with the radius expressed in meters) and POLYGON. |
| poiList | string | yes | List of POIs to filter. The only required attribute of a POI is position, everything else is optional and will be echoed back when passed… |

### Geometry Filter
`POST https://apizie.tech/v1/places:tomtom-search/post-search-version-number-geometry-filter-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| ext | string | yes | Expected response format. |
| body | object | no | JSON request body |

### Geometry Search
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-geometry-search-query-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| query | string | yes | Query string. Must be properly URL encoded. |
| ext | string | yes | Expected response format. |
| geometryList | string | no | List of geometries to filter by. Available types are CIRCLE (with the radius expressed in meters) and POLYGON. |
| limit | integer | no | Maximum number of search results that will be returned. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |
| extendedPostalCodesFor | string | no | Indexes for which extended postal codes should be included in the results. Available indexes are: - Addr = Address ranges - Geo =… |
| idxSet | string | no | A comma separated list of indexes which should be utilized for the search. Item order does not matter. Available indexes are: - Addr =… |

### Geometry Search
`POST https://apizie.tech/v1/places:tomtom-search/post-search-version-number-geometry-search-query-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| query | string | yes | Query string. Must be properly URL encoded. |
| ext | string | yes | Expected response format. |
| limit | integer | no | Maximum number of search results that will be returned. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |
| extendedPostalCodesFor | string | no | Indexes for which extended postal codes should be included in the results. Available indexes are: - Addr = Address ranges - Geo =… |
| idxSet | string | no | A comma separated list of indexes which should be utilized for the search. Item order does not matter. Available indexes are: - Addr =… |
| body | object | no | JSON request body |

### Nearby Search
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-nearby-search-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| ext | string | yes | Expected response format. |
| lat | number | yes | Latitude where results should be biased. NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| lon | number | yes | Longitude where results should be biased NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| limit | integer | no | Maximum number of search results that will be returned. |
| ofs | integer | no | Starting offset of the returned results within the full result set. |
| countrySet | string | no | Comma separated string of country codes. This will limit the search to the specified countries. |
| radius | integer | no | If radius and position are set, the results will be constrained to the defined area. The radius parameter is specified in meters. |
| topLeft | string | no | Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| btmRight | string | no | Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |
| extendedPostalCodesFor | string | no | Indexes for which extended postal codes should be included in the results. Available indexes are: - Addr = Address ranges - Geo =… |
| minFuzzyLevel | integer | no | Minimum fuzziness level to be used. |
| maxFuzzyLevel | integer | no | Maximum fuzziness level to be used. |
| idxSet | string | no | A comma separated list of indexes which should be utilized for the search. Item order does not matter. Available indexes are: - Addr =… |
| view | string | no | Geopolitical View. |

### Points of Interest Search
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-poi-search-query-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| query | string | yes | Query string. Must be properly URL encoded. |
| ext | string | yes | Expected response format. |
| typeahead | boolean | no | If the "typeahead" flag is set, the query will be interpreted as a partial input and the search will enter predictive mode. |
| limit | integer | no | Maximum number of search results that will be returned. |
| ofs | integer | no | Starting offset of the returned results within the full result set. |
| countrySet | string | no | Comma separated string of country codes. This will limit the search to the specified countries. |
| lat | number | no | Latitude where results should be biased. NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| lon | number | no | Longitude where results should be biased NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| radius | integer | no | If radius and position are set, the results will be constrained to the defined area. The radius parameter is specified in meters. |
| topLeft | string | no | Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| btmRight | string | no | Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |
| extendedPostalCodesFor | string | no | Indexes for which extended postal codes should be included in the results. Available indexes are: - Addr = Address ranges - Geo =… |
| view | string | no | Geopolitical View. |

### Cross Street lookup
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-reverse-geocode-cross-street-posit` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| position | string | yes | This is specified as a comma separated string composed of lat., lon. |
| ext | string | yes | Expected response format. |
| limit | integer | no | Maximum number of cross-streets to return. |
| spatialKeys | boolean | no | If the "spatialKeys" flag is set, the response will also contain a proprietary geospatial keys for a specified location. |
| heading | number | no | The directional heading in degrees, usually similar to the course along a road segment. Entered in degrees, measured clockwise from north… |
| radius | integer | no | The maximum distance in meters from the specified position for the reverse geocoder to consider. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |

### Reverse Geocode
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-reverse-geocode-position-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| position | string | yes | This is specified as a comma separated string composed of lat., lon. |
| ext | string | yes | Expected response format. |
| spatialKeys | boolean | no | If the "spatialKeys" flag is set, the response will also contain a proprietary geospatial keys for a specified location. |
| returnSpeedLimit | boolean | no | To enable return of the posted speed limit (where available). |
| heading | number | no | The directional heading in degrees, usually similar to the course along a road segment. Entered in degrees, measured clockwise from north… |
| radius | integer | no | The maximum distance in meters from the specified position for the reverse geocoder to consider. |
| number | string | no | If a number is sent in along with the request, the response may include the side of the street (Left/Right) and an offset position for… |
| returnRoadUse | boolean | no | Enables return of the road use array for reverse geocodes at street level. |
| roadUse | string | no | Restricts reverse geocodes to a certain type of road use. The road use array for reverse geocodes can be one or more of: ["LimitedAccess",… |
| callback | string | no | Specifies the jsonp callback method. |

### Fuzzy Search
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-search-query-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| query | string | yes | Query string. Must be properly URL encoded. To perform a reverse geocode, the user can provide latitude and longitude coordinates directly… |
| ext | string | yes | Expected response format. |
| typeahead | boolean | no | If the "typeahead" flag is set, the query will be interpreted as a partial input and the search will enter predictive mode. |
| limit | integer | no | Maximum number of search results that will be returned. |
| ofs | integer | no | Starting offset of the returned results within the full result set. |
| countrySet | string | no | Comma separated string of country codes. This will limit the search to the specified countries. |
| lat | number | no | Latitude where results should be biased. NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| lon | number | no | Longitude where results should be biased NOTE: supplying a lat/lon without a radius will return search results biased to that point. |
| radius | integer | no | If radius and position are set, the results will be constrained to the defined area. The radius parameter is specified in meters. |
| topLeft | string | no | Top left position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| btmRight | string | no | Bottom right position of the bounding box. This is specified as a comma separated string composed of lat., lon. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |
| extendedPostalCodesFor | string | no | Indexes for which extended postal codes should be included in the results. Available indexes are: - Addr = Address ranges - Geo =… |
| minFuzzyLevel | integer | no | Minimum fuzziness level to be used. |
| maxFuzzyLevel | integer | no | Maximum fuzziness level to be used. |
| idxSet | string | no | A comma separated list of indexes which should be utilized for the search. Item order does not matter. Available indexes are: - Addr =… |
| view | string | no | Geopolitical View. |

### Along Route Search
`POST https://apizie.tech/v1/places:tomtom-search/post-search-version-number-search-along-route-query-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| query | string | yes | Query string. Must be properly URL encoded. |
| ext | string | yes | Expected response format. |
| maxDetourTime | integer | yes | Maximum detour time |
| limit | integer | no | Maximum number of search results that will be returned. |
| body | object | no | JSON request body |

### Structured Geocode
`GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-structured-geocode-ext` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| versionNumber | integer | yes | Service version number. The current value is 2. |
| ext | string | yes | Expected response format. |
| countryCode | string | yes | 2 or 3 letter country code (e.g.: FR, ES). |
| limit | integer | no | Maximum number of search results that will be returned. |
| ofs | integer | no | Starting offset of the returned results within the full result set. |
| streetNumber | string | no | The street number for the structured address. |
| streetName | string | no | The street name for the structured address. |
| crossStreet | string | no | The cross street name for the structured address. |
| municipality | string | no | The municipality (city/town) for the structured address. |
| municipalitySubdivision | string | no | The municipality subdivision (sub/super city) for the structured address. |
| countryTertiarySubdivision | string | no | The named area for the structured address. |
| countrySecondarySubdivision | string | no | The county for the structured address. |
| countrySubdivision | string | no | The state or province for the structured address. |
| postalCode | string | no | The zip code or postal code for the structured address. |
| language | string | no | Language in which search results should be returned. Should be one of supported IETF language tags , case insensitive. |
| extendedPostalCodesFor | string | no | Indexes for which extended postal codes should be included in the results. Available indexes are: - Addr = Address ranges - Geo =… |

## Example
```
curl "https://apizie.tech/v1/places:tomtom-search/get-search-version-number-additional-data-ext" \
  -H "x-api-key: $APIZIE_KEY" \
  -H "x-upstream-key: $PROVIDER_KEY"
```

## FAQ

### How do I call the Search API?
Create a free Apizie key, then send GET https://apizie.tech/v1/places:tomtom-search/get-search-version-number-additional-data-ext with the header x-api-key. Every endpoint returns { project, data, timestamp }.

### Is the Search API free on Apizie?
Yes. The Free plan includes 1,000 requests a month at 100 requests a minute, no credit card. Search itself also needs your own key from tomtom.com.

### Can AI agents use the Search API?
Yes. Add the Apizie MCP server (https://apizie.tech/mcp) to Claude, ChatGPT, Cursor or VS Code, then ask in plain language. The agent calls run_scraper with project key places:tomtom-search.

### What is the status of the Search API?
Needs your own provider key (bring your own key)