> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TomTom API reference

> API reference for the TomTom plugin in Corsair: every `tomtom.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Routing

### calculate

`routing.calculate`

Calculate a route between waypoints with travel mode, traffic and avoidance options; makes no booking

**Risk:** `read`

```ts theme={null}
await corsair.tomtom.api.routing.calculate({ origins: [{ latitude: 52.37, longitude: 4.89 }], destinations: [{ latitude: 52.09, longitude: 5.12 }], travel_mode: 'car', traffic: true });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `origins` | `object[]` | Yes | Where the route starts |
| `destinations` | `object[]` | Yes | Where the route ends |
| `travel_mode` | `car \| truck \| taxi \| bus \| van \| motorcycle \| bicycle \| pedestrian` | No | Default car |
| `route_type` | `fastest \| shortest \| eco \| thrilling` | No | Default fastest |
| `traffic` | `boolean` | No | Use live traffic in the calculation |
| `depart_at` | `string` | No | Departure time as an ISO 8601 instant, for future-traffic routing |
| `vehicle_max_speed` | `number` | No | Kilometres per hour for the travel mode |
| `avoid` | `(tollRoads \| motorways \| ferries \| unpavedRoads \| carpools \| alreadyUsedRoads)[]` | No | Features to route around |
| `language` | `string` | No | — |

Waypoints are joined in the path, origins then destinations. `depart_at` uses future traffic when `traffic` is on.

> [accordion] origins full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number
> }[]
> ```

> [accordion] destinations full type
>
> ```ts theme={null}
> {
>   latitude: number,
>   longitude: number
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `formatVersion` | `string \| null` | No | — |
| `routes` | `object[]` | Yes | — |

> [accordion] routes full type
>
> ```ts theme={null}
> {
>   summary?: {
>     lengthInMeters?: number | null,
>     travelTimeInSeconds?: number | null,
>     trafficDelayInSeconds?: number | null,
>     departureTime?: string | null,
>     arrivalTime?: string | null,
>     hasTollRoad?: boolean | null,
>     hasHighway?: boolean | null,
>     hasFerry?: boolean | null
>   } | null,
>   legs?: {
>   }[] | null,
>   guidance?: {
>   } | null
> }[]
> ```

***

## Search

### fuzzy

`search.fuzzy`

Search for places, addresses, streets and geography, with optional geo bias and country filters

**Risk:** `read`

```ts theme={null}
await corsair.tomtom.api.search.fuzzy({ query: 'pizza', lat: 52.37, lon: 4.89, radius: 5000, limit: 5 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | What to search for, e.g. "pizza" |
| `typeahead` | `boolean` | No | Treat the query as partial input for predictive search |
| `radius` | `number` | No | Metres from the bias point; requires lat and lon |
| `limit` | `number` | No | Results per page; default 10, maximum 100 |
| `offset` | `number` | No | Default 0 |
| `country_set` | `string` | No | Comma-separated ISO country codes, e.g. "US,MX" |
| `language` | `string` | No | BCP-47 language tag, e.g. "en-GB" |
| `lat` | `number` | No | Latitude for the geo bias |
| `lon` | `number` | No | Longitude for the geo bias |

`radius` needs both `lat` and `lon`. `limit` caps at 100. `summary.totalResults` is the total match count and `summary.numResults` the size of this page.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `summary` | `object \| null` | No | — |
| `results` | `object[]` | Yes | — |

> [accordion] summary full type
>
> ```ts theme={null}
> {
>   query?: string | null,
>   queryType?: string | null,
>   queryTime?: number | null,
>   numResults?: number | null,
>   offset?: number | null,
>   totalResults?: number | null,
>   fuzzyLevel?: number | null
> } | null
> ```

> [accordion] results full type
>
> ```ts theme={null}
> {
>   type?: string | null,
>   id?: string | null,
>   score?: number | null,
>   dist?: number | null,
>   name?: string | null,
>   address?: {
>     streetName?: string | null,
>     municipality?: string | null,
>     countrySubdivision?: string | null,
>     postalCode?: string | null,
>     countryCode?: string | null,
>     country?: string | null,
>     freeformAddress?: string | null
>   } | null,
>   position?: {
>     lat: number,
>     lon: number
>   } | null,
>   viewport?: {
>     topLeftPoint?: {
>       lat: number,
>       lon: number
>     } | null,
>     btmRightPoint?: {
>       lat: number,
>       lon: number
>     } | null
>   } | null,
>   poi?: {
>     name?: string | null,
>     categories?: string[] | null,
>     classifications?: {
>     }[] | null,
>     phone?: string | null,
>     url?: string | null
>   } | null,
>   entryPoints?: {
>   }[] | null
> }[]
> ```

***

### geocode

`search.geocode`

Turn an address into coordinates

**Risk:** `read`

```ts theme={null}
await corsair.tomtom.api.search.geocode({ query: 'Damrak 1 Amsterdam', country_set: 'NL' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | An address to turn into coordinates |
| `limit` | `number` | No | Results per page; default 10, maximum 100 |
| `offset` | `number` | No | Default 0 |
| `country_set` | `string` | No | Comma-separated ISO country codes, e.g. "US,MX" |
| `language` | `string` | No | BCP-47 language tag, e.g. "en-GB" |
| `lat` | `number` | No | Latitude for the geo bias |
| `lon` | `number` | No | Longitude for the geo bias |

The query goes in the path. Pass the address as plain text; the plugin encodes it.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `summary` | `object \| null` | No | — |
| `results` | `object[] \| null` | No | — |

> [accordion] summary full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] results full type
>
> ```ts theme={null}
> {
>   type?: string | null,
>   id?: string | null,
>   address?: {
>   } | null,
>   position?: {
>     lat: number,
>     lon: number
>   } | null
> }[] | null
> ```

***

### reverseGeocode

`search.reverseGeocode`

Turn coordinates into the nearest address

**Risk:** `read`

```ts theme={null}
await corsair.tomtom.api.search.reverseGeocode({ latitude: 52.378, longitude: 4.9, radius: 100 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `latitude` | `number` | Yes | — |
| `longitude` | `number` | Yes | — |
| `radius` | `number` | No | Metres to search around the point, up to 1000 |
| `language` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `summary` | `object \| null` | No | — |
| `addresses` | `object[]` | Yes | — |

> [accordion] summary full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] addresses full type
>
> ```ts theme={null}
> {
>   address?: {
>     streetName?: string | null,
>     municipality?: string | null,
>     countrySubdivision?: string | null,
>     postalCode?: string | null,
>     countryCode?: string | null,
>     country?: string | null,
>     freeformAddress?: string | null
>   } | null,
>   position?: string | null
> }[]
> ```

***

## Traffic

### flow

`traffic.flow`

Read the current speed and free-flow speed on the road at a point

**Risk:** `read`

```ts theme={null}
await corsair.tomtom.api.traffic.flow({ latitude: 52.37, longitude: 4.89, zoom: 12 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `latitude` | `number` | Yes | — |
| `longitude` | `number` | Yes | — |
| `zoom` | `number` | No | Detail level; higher is more precise |
| `unit` | `kmph \| mph` | No | Speed unit, default kmph |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `flowSegmentData` | `object \| null` | No | — |

> [accordion] flowSegmentData full type
>
> ```ts theme={null}
> {
>   frc?: string | null,
>   currentSpeed?: number | null,
>   freeFlowSpeed?: number | null,
>   currentTravelTime?: number | null,
>   freeFlowTravelTime?: number | null,
>   confidence?: number | null,
>   roadClosure?: boolean | null,
>   coordinates?: {
>   } | null
> } | null
> ```

***

### incidents

`traffic.incidents`

List live traffic incidents in a bounding box, with their delay and road numbers

**Risk:** `read`

```ts theme={null}
await corsair.tomtom.api.traffic.incidents({ bbox: '4.88,52.36,4.92,52.39' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `bbox` | `string` | Yes | Bounding box as "minLon,minLat,maxLon,maxLat", at most 10,000 km² in area |
| `language` | `string` | No | Default en-GB |
| `category_filter` | `number[]` | No | Incident categories to include, such as \[1, 6] for Accident and Jam; sent comma-separated |
| `time_validity_filter` | `(present \| future)[]` | No | present, future or both; default present |

The bounding box is minLon,minLat,maxLon,maxLat. The box may cover at most 10,000 km². `category_filter` is a list of category numbers, such as \[1, 6] for Accident and Jam, and `time_validity_filter` takes present, future or both.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `incidents` | `object[]` | Yes | — |

> [accordion] incidents full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type?: string | null,
>   geometry?: {
>   } | null,
>   properties?: {
>     id?: string | null,
>     iconCategory?: number | null,
>     magnitudeOfDelay?: number | null,
>     events?: {
>     }[] | null,
>     startTime?: string | null,
>     endTime?: string | null,
>     from?: string | null,
>     to?: string | null,
>     length?: number | null,
>     delay?: number | null,
>     roadNumbers?: string[] | null,
>     aci?: {
>     } | null
>   } | null
> }[]
> ```

***

### tile

`traffic.tile`

Fetch one traffic flow or incident map tile

**Risk:** `read`

```ts theme={null}
await corsair.tomtom.api.traffic.tile({ layer: 'flow', style: 'relative-delay', zoom: 12, x: 2100, y: 1350 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `layer` | `flow \| incidents` | No | Default flow |
| `style` | `absolute \| relative \| relative-delay \| reduced-sensitivity` | No | Flow layer style, default relative |
| `incident_style` | `s0 \| s0-dark \| s1 \| s2 \| s3 \| night` | No | Incidents layer style, default s3 |
| `zoom` | `number` | Yes | — |
| `x` | `number` | Yes | — |
| `y` | `number` | Yes | — |

Returns the PNG as base64. The flow layer defaults to the relative style and the incidents layer to s3.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `content_type` | `string` | Yes | Usually image/png |
| `base64` | `string` | Yes | The tile image, base64-encoded |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.