# TomTom Maps

> Geocode, search places, calculate routes, and read live traffic with the TomTom Maps API.

Lets an agent work with location data through the TomTom Maps API: turn addresses into coordinates and back, search for addresses and points of interest, calculate routes between waypoints, and read live traffic incidents.

## What it can do

| Method | What it does |
| --- | --- |
| `tomtom_geocode` | Geocode an address to coordinates. Optional country filter, limit, language. |
| `tomtom_search` | Fuzzy search for addresses and POIs, with optional proximity bias (lat/lon + radius) and category filter. |
| `tomtom_reverse_geocode` | Reverse geocode coordinates to the nearest street address. |
| `tomtom_route` | Calculate a route between waypoints. Travel mode, route type, live traffic, departure time, guidance instructions. |
| `tomtom_traffic_incidents` | Get active traffic incidents (jams, closures, accidents) within a bounding box. |
| `tomtom_request` | Generic passthrough to any TomTom endpoint for full coverage (POI search, batch, etc.). |

## How to get your key

TomTom authenticates with an API key sent as a `key` query parameter.

1. Sign up at the [TomTom Developer Portal](https://developer.tomtom.com/).
2. Open **My Dashboard -> Keys** ([developer.tomtom.com/user/me/apps](https://developer.tomtom.com/user/me/apps)).
3. Create an app / key, or copy an existing one. The free tier includes a daily request allowance.
4. Paste the key into FlyMyAI.

## Fields to fill

| FlyMyAI field | Where it comes from |
| --- | --- |
| `TOMTOM_API_KEY` | TomTom Developer Portal -> My Dashboard -> Keys |

## Troubleshooting

- **`403 Forbidden`** - the key is wrong, disabled, or the requested service is not enabled for it. Check the key in My Dashboard -> Keys.
- **`429 Too Many Requests`** - you exceeded the daily request quota for the key. Wait for the reset or upgrade the plan.
- **No results from `tomtom_search` / `tomtom_geocode`** - broaden the query, drop the `countrySet` filter, or remove the proximity bias.
- **`tomtom_route` fails** - check the `locations` format: colon-separated `lat,lon` pairs, e.g. `52.50931,13.42936:52.50274,13.43872`.

## Links

- [TomTom API keys](https://developer.tomtom.com/user/me/apps)
- [TomTom Developer documentation](https://developer.tomtom.com/)