canonical: https://jentic.com/apis/tomtom.com/tomtom-search-api

# TomTom Search API

Jentic publishes the only available OpenAPI specification for TomTom Search API, keeping it validated and agent-ready. Run fuzzy, category, POI, nearby, and geometry-based searches across TomTom's global location database to find addresses, businesses, and points of interest. The API supports forward and structured geocoding, reverse geocoding with cross-street lookup, search along a driving route with detour-time constraints, and geometry filtering to restrict results to custom polygons or circles - all returning coordinates, address components, and POI metadata across 16 endpoints.

## For AI agents

Search for addresses, POIs, and places using fuzzy, category, geometry, or along-route queries. Geocode and reverse geocode with cross-street resolution.

## Scope

Does not handle map tile rendering, traffic flow data, routing calculations, or fleet tracking - use for location search and geocoding only.

## Capabilities

- Perform fuzzy search across addresses, POIs, and geographic features with typo tolerance and typeahead support
- Geocode addresses using free-form or structured queries with country code, street, and postal code components
- Reverse geocode coordinates to street-level addresses with optional speed limit and road use data
- Search for points of interest by category within a bounding box or radius
- Find POIs along a planned driving route within a maximum detour time of up to 3600 seconds
- Filter search results within custom geometry shapes (circles and polygons) via both GET and POST methods
- Retrieve additional geometry data for search results using geometry UUIDs

## Use cases

### AI Agent Location Search via Jentic

AI agents use TomTom's fuzzy search endpoint to resolve ambiguous location references from user queries into precise coordinates and structured addresses. Through Jentic, agents search for 'find a location' and receive the operation schema for the fuzzy search endpoint, which handles misspellings, partial addresses, and POI names in a single query. The typeahead mode enables real-time suggestions, and results include coordinates, formatted addresses, and match scores.

Example prompt: Search for 'pizza near Times Square' using the /search/2/search/{query}.json endpoint with lat=40.758 and lon=-73.985 and return the top 3 results with coordinates

### Along-Route POI Discovery for Navigation

Navigation and trip-planning applications find fuel stations, restaurants, or rest areas along a planned route without requiring significant detours. The searchAlongRoute endpoint accepts a route geometry (as an array of lat/lon points) and a maximum detour time in seconds, returning only POIs reachable within that constraint. This eliminates irrelevant results that are geographically close but require long detours to reach.

Example prompt: Search for 'gas' along a route from San Francisco to San Jose with a maximum detour time of 600 seconds using the /search/2/searchAlongRoute/{query}.json POST endpoint

### Geometry-Based Geofence Querying

Logistics and delivery platforms query POIs within custom delivery zones defined as polygons or circles. The geometrySearch endpoint accepts a query term and a list of geometry shapes (circles with center/radius or polygons with vertices), returning only results that fall within those boundaries. The geometry filter endpoint further narrows existing result sets to custom areas.

Example prompt: Search for 'restaurant' within a circle of 2000m radius centered at 37.7749,-122.4194 using the /search/2/geometrySearch/{query}.json endpoint

### Reverse Geocoding for Vehicle Telematics

Telematics systems convert raw GPS streams from vehicles into street-level addresses for driver logs, trip reports, and compliance records. The reverse geocode endpoint returns the street address, and optionally the posted speed limit and road use classification (arterial, local, ramp). Cross-street lookup provides the nearest intersection name for more human-friendly location descriptions.

Example prompt: Reverse geocode position 37.8328,-122.27669 using the /search/2/reverseGeocode/{position}.json endpoint with returnSpeedLimit=true and return the address and speed limit

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /search/{versionNumber}/search/{query}.{ext} | Fuzzy search for addresses, POIs, and features |
| GET | /search/{versionNumber}/geocode/{query}.{ext} | Forward geocode an address |
| GET | /search/{versionNumber}/structuredGeocode.{ext} | Structured geocode with address components |
| GET | /search/{versionNumber}/reverseGeocode/{position}.{ext} | Reverse geocode coordinates to address |
| GET | /search/{versionNumber}/poiSearch/{query}.{ext} | Search for points of interest |
| GET | /search/{versionNumber}/nearbySearch/.{ext} | Find nearby POIs by location |
| POST | /search/{versionNumber}/searchAlongRoute/{query}.{ext} | Search POIs along a driving route |
| GET | /search/{versionNumber}/geometrySearch/{query}.{ext} | Search within custom geometry shapes |

## Key resources

- **Search** — Fuzzy search, POI search, nearby search, category search, along-route search, and low-bandwidth variants
- **Geocoding** — Forward geocoding with free-form and structured address queries
- **Reverse Geocoding** — Convert coordinates to addresses with cross-street lookup and road metadata
- **Filters** — Geometry-based and route-based filtering of POI results
- **Additional Data** — Retrieve extended geometry data for search results using UUIDs

## Why Jentic

- **Setup:** Wiring TomTom Search by hand means appending its key query parameter to every call, encoding the query, position, and extension into the URL path, and tracking the api.tomtom.com host. Through Jentic you install once, import the TomTom Search API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** TomTom Search is read-only search and geocoding, so scope the agent to the operations it needs, such as geocoding an address or searching along a route. You choose which operations are allowed, and only those you include are callable.
- **Credential handling:** Your TomTom key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'geocode an address' or 'search for places along a route', and Jentic returns the matching TomTom Search operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HERE Geocoding & Search API** — Similar geocoding and place search with autosuggest, category browse, and place detail lookup
- **LocationIQ API** — OSM-based geocoding and search with routing and lower pricing
- **TomTom Routing API** — Calculate routes, distances, and travel times to complement search results

## FAQ

### Why is there no official OpenAPI spec for TomTom Search API?

TomTom does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call TomTom Search API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the TomTom Search API use?

The TomTom Search API uses an API key passed as the `key` query parameter on every request. Through Jentic, your TomTom API key is stored encrypted in your Jentic One instance and injected automatically - agents never see the raw key value.

### Can I search for POIs along a driving route with the TomTom API?

Yes. The /search/2/searchAlongRoute/{query}.json POST endpoint accepts a route geometry (array of lat/lon points) and a `maxDetourTime` parameter (up to 3600 seconds). It returns only POIs reachable within that detour constraint, sorted by detour time from the route.

### What are the rate limits for the TomTom Search API?

TomTom returns HTTP 403 when queries-per-second or account rate limits are exceeded. Free tier accounts allow 2,500 transactions per day with 5 QPS. Paid plans scale based on contract terms with higher concurrency and monthly quotas.

### How do I perform a geometry-based search through Jentic?

Install the Jentic SDK with `pip install jentic` and search for 'search within a polygon'. Jentic returns the /search/2/geometrySearch/{query}.json operation schema. Pass your query term, a geometryList with POLYGON vertices or CIRCLE position/radius, and execute through Jentic to get POIs within your custom boundary.

### What is the difference between fuzzy search and POI search?

Fuzzy search (/search/2/search/) queries across all index types - addresses, streets, POIs, and geographic features - with typo tolerance. POI search (/search/2/poiSearch/) is restricted to points of interest only and is optimized for business/place name queries. Use fuzzy search when the input could be anything; use POI search when you specifically want business results.

### Can I limit what my agent is allowed to do with the TomTom Search API?

Yes. Because Jentic One is self-hosted, you decide which TomTom Search operations your agent may call, and only the ones you include are reachable. Since this API is read-only search and geocoding, you can restrict the agent to just what it needs, such as forward geocoding an address, reverse geocoding coordinates, or searching for POIs along a route, while leaving out fuzzy search, nearby search, or geometry search. Your TomTom key is stored encrypted by your own instance and injected at execution time under your rules, so the agent calls only the endpoints you have permitted.