---
title: "Compute an N×M distance + duration matrix"
method: POST
path: "/v1/distance-matrix"
tags: ["Routing"]
---

# Compute an N×M distance + duration matrix

`POST /v1/distance-matrix`

## Request

- Base URL: `https://geo.thinair.co`
- URL: `https://geo.thinair.co/v1/distance-matrix`
- Auth: HTTP bearer

Compute road distances and travel times for every origin → destination pair. Endpoints accept free-text addresses or coordinate pairs; N × M is capped at 625 pairs. Quota cost is origins.count + destinations.count + 1 (one unit per geocoded endpoint plus one for the matrix call). Matrix durations do NOT include live or historical traffic — see `duration_basis` on the response; use `directions` for a traffic-adjusted ETA between two specific points.

## Request body

- DistanceMatrixRequest: N origins × M destinations distance + duration matrix. Endpoints accept free-text addresses or coordinate pairs; N × M is capped at 625 pairs.
  - `origins` union[], required: Origin endpoints (1–25). Each is free text or { lat, lon }.
    - union: Free-text address ('Houston, TX') OR a coordinate pair { lat, lon }.
      - string
      - object
        - `lat` number, required
        - `lon` number, required
  - `destinations` union[], required: Destination endpoints (1–25). origins.length × destinations.length must be ≤ 625.
    - union: Free-text address ('Houston, TX') OR a coordinate pair { lat, lon }.
      - string
      - object
        - `lat` number, required
        - `lon` number, required
  - `costing` 'auto' | 'truck' | 'bicycle' | 'pedestrian' | 'motorcycle': Transport mode. Default: auto.
  - `units` 'miles' | 'kilometers': Distance units. Default: kilometers.

## Response `200`

Distance + duration matrix with resolved endpoints.

- DistanceMatrixResponse
  - `origins` DistanceMatrixLocation[], required
    - `lat` number, required
    - `lon` number, required
    - `label` string
    - `confidence` number
    - `method` string
  - `destinations` DistanceMatrixLocation[], required
    - `lat` number, required
    - `lon` number, required
    - `label` string
    - `confidence` number
    - `method` string
  - `matrix` array[], required: matrix[i][j] = origin i → destination j.
    - DistanceMatrixCell[]
      - `distance` number, nullable, required: Road distance in the requested units; null when no route.
      - `time_seconds` number, nullable, required: Travel time in seconds; null when no route.
  - `units` 'miles' | 'kilometers', required
  - `costing` string, required
  - `duration_basis` 'static_road_speeds', required: How matrix durations were computed. `static_road_speeds` (the only value today): durations come from the road network's own speed data — posted limits and road-class defaults — never from historical or live traffic. Use `directions` for a traffic-adjusted ETA between two specific points.
  - `traffic_applied` false, required: Whether live or historical traffic influenced any matrix duration. Always false today — see `duration_basis`.
  - `meta` object, required
    - `upstream_ms` number, required
    - `origin_count` number, required
    - `destination_count` number, required
  - `upstream_error` string, nullable

## Other responses

- `400`: Invalid request body or matrix over the 625-pair limit.
- `429`: Quota exceeded for this tenant.
- `502`: Upstream routing engine unavailable.

---

[API](https://skmtc.dev/thinair/apis/thinair-geo-api.md) · [All operations](https://skmtc.dev/thinair/apis/thinair-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinair/apis/thinair-geo-api/revisions/8fac2d5e4b34?raw)