TomTom APItomtom.com ↗
Access TomTom Traffic Index data: global city congestion rankings, AM/PM peak metrics, country-level rankings, and monthly traffic trends via 3 endpoints.
What is the TomTom API?
The TomTom Traffic Index API exposes city-level congestion data across 3 endpoints, covering global rankings, country-specific rankings, and per-city detail. The get_congestion_rankings endpoint returns cities sorted by congestion score worldwide, while get_city_details delivers AM/PM peak-hour metrics and monthly trend data for a named city. All data reflects the 2025 TomTom Traffic Index report.
curl -X GET 'https://api.parse.bot/scraper/3fe605e6-cddf-426b-a50d-77f32c3498b4/get_congestion_rankings?limit=5&countries=united-kingdom' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tomtom-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: TomTom Traffic Index — bounded, re-runnable; every call capped."""
from parse_apis.tomtom_traffic_index_api import TomTom, CityNotFound
client = TomTom()
# Global congestion rankings filtered to one country — limit caps total items.
for city in client.cities.list(countries="united-kingdom", limit=5):
print(city.name, city.congestion_score, f"rank={city.rank}")
# Country-scoped rankings via the constructible Country resource.
uk = client.country(name="united-kingdom")
for city in uk.rankings(limit=3):
print(city.name, city.congestion_score)
# Drill into one city's detailed traffic data via .first() then .details().
top_city = uk.rankings(limit=1).first()
if top_city:
detail = top_city.details()
metrics = detail.data.all
print(detail.city, detail.year)
print(f" AM peak: hour={metrics.am.time}, congestion={metrics.am.c}%")
print(f" PM peak: hour={metrics.pm.time}, congestion={metrics.pm.c}%")
for month in metrics.monthly[:2]:
print(f" {month.time}: {month.c}%")
# Typed error handling for a city that doesn't exist.
try:
bad = client.city(key="nonexistent-city-xyz")
bad.details()
except CityNotFound as exc:
print(f"City not found: {exc.city}")
print("exercised: cities.list / country.rankings / city.details / CityNotFound")
Get global city congestion rankings across multiple countries. Returns cities sorted by congestion score (highest first). Each city includes its key, name, country, AM/PM metrics, congestion score, and rank. When no countries are specified, defaults to the first 10 countries alphabetically from the internal list. Fetching many countries is expensive — one HTTP round-trip per country.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of cities to return in the ranking. |
| countries | string | Comma-separated list of country keys to include (e.g. 'united-kingdom,mexico,united-states-of-america'). Omitting returns cities from default set of countries. |
{
"type": "object",
"fields": {
"year": "Data year string, currently '2025'",
"ranking": "Array of city objects sorted by congestion_score descending, each containing key, name, country, ampm metrics object, congestion_score, and rank",
"total_cities": "Total number of cities found across all queried countries"
},
"sample": {
"data": {
"year": "2025",
"ranking": [
{
"key": "belfast",
"ampm": {
"c": 98.9,
"s": 19498071.74,
"v": 22.4,
"fv": 44.7
},
"name": "Belfast",
"rank": 1,
"country": "United Kingdom",
"congestion_score": 98.9
}
],
"total_cities": 34
},
"status": "success"
}
}About the TomTom API
What the API covers
The TomTom Traffic Index API surfaces congestion data from TomTom's annual Traffic Index, which benchmarks cities on how much extra travel time congestion adds to a typical trip. The API covers three scopes: global multi-country rankings, single-country rankings, and full detail for an individual city.
Endpoint breakdown
get_congestion_rankings accepts an optional countries parameter (comma-separated country keys such as united-kingdom,mexico) and an optional limit. It returns a ranking array where each object includes key, name, country, congestion_score, rank, and an ampm metrics object. The total_cities field tells you how many cities matched across all queried countries.
get_country_rankings takes a required country key and an optional limit, returning the same city-object structure scoped to one country. The response includes the country name in title case alongside the ranking array and total_cities count.
get_city_details takes a required city key (e.g. london, new-york-ny) obtained from either ranking endpoint. The data object contains a nested all key with base, am, pm, and ampm sub-objects — each carrying fields c (congestion percentage), v, fv, and s — plus monthly trend data covering the full year.
Data freshness and keys
All three endpoints return a year field currently set to 2025. City and country keys follow a lowercase hyphenated format; the ranking endpoints are the canonical source for valid keys to pass into get_city_details.
The TomTom API is a managed, monitored endpoint for tomtom.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when tomtom.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official tomtom.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Building a city comparison tool that ranks metros by
congestion_scoreacross selected countries. - Plotting monthly traffic trend data from
get_city_detailsto visualize seasonal congestion patterns. - Filtering
get_country_rankingsby country to identify the most congested cities in a single market. - Feeding AM peak congestion percentages into a commute-cost calculator for employee relocation analysis.
- Powering a real estate research dashboard that surfaces traffic conditions for cities under consideration.
- Generating country-level congestion league tables for logistics and fleet planning reports.
- Alerting users when a city's
congestion_scorerank changes between annual index releases.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TomTom offer an official developer API?+
What does the `ampm` metrics object contain in the ranking endpoints versus `get_city_details`?+
get_congestion_rankings and get_country_rankings), each city object includes a summary ampm metrics object alongside congestion_score and rank. In get_city_details, the data.all key expands this into separate am, pm, ampm, and base sub-objects, each with fields for congestion percentage (c), plus v, fv, and s values, and adds monthly trend data.Does the API cover real-time or historical traffic data beyond the annual index?+
How do I get a valid city key to use with `get_city_details`?+
london, new-york-ny, mexico-city). The reliable way to retrieve valid keys is to call get_congestion_rankings or get_country_rankings first and read the key field from each city object in the ranking array.Is there pagination support for the ranking endpoints?+
limit parameter to cap how many cities are returned, but there is no offset or cursor-based pagination. If you need cities beyond the default set, increase limit or filter by specific countries. You can fork the API on Parse and revise it to add offset-based pagination if your use case requires iterating through large result sets.