---
title: "Road attributes along a matched GPS trace"
method: POST
path: "/v1/trace-attributes"
tags: ["Routing"]
---

# Road attributes along a matched GPS trace

`POST /v1/trace-attributes`

## Request

- Base URL: `https://geo.thinair.co`
- URL: `https://geo.thinair.co/v1/trace-attributes`
- Auth: HTTP bearer

Trace attributes return road/network attributes for matched traces — match a GPS breadcrumb trail to the road network and get per-segment road names, classes, speed limits, surfaces, and truck-route flags, plus the matcher's confidence. Sparsely-reported traces (consecutive fixes farther apart than the default breakage distance) can split into multiple sections — see `breakage_distance_m`. Total matched distance is limited to 200 km per call; split longer sparse traces by distance, not only by the 100-point cap. Costs 1 quota unit per call.

## Request body

- TraceAttributesRequest: Trace-attributes request — a raw GPS breadcrumb trail (2–100 points) to match against the road network and describe segment-by-segment.
  - `shape` object[], required: Raw GPS breadcrumb trail in travel order — 2 to 100 points of { lat, lon, time? }.
    - `lat` number, required
    - `lon` number, required
    - `time` number: Optional epoch seconds for this fix — timestamps improve match quality on noisy traces.
  - `costing` 'auto' | 'truck' | 'bicycle' | 'pedestrian': Transport mode the trace was driven with. Default: auto.
  - `vehicle_profile` string: Truck preset (DRY_VAN_53, FLATBED_48, BOX_TRUCK_26, …) — same 10-profile table as /v1/directions. Implies costing=truck.
  - `search_radius` number: Snap radius in meters around each point (1–100). Increase for noisy GPS.
  - `breakage_distance_m` integer: Maximum gap, in meters, between consecutive fixes before the trace is split into separate sections (100–20000). Increase for sparsely-reported GPS, such as fleet units reporting every several minutes on a highway. Optional — omitted uses the default.

## Response `200`

Per-segment attributes for the matched trace.

- TraceAttributesResponse: Per-segment road attributes for the matched trace. Each edge carries only the whitelisted public fields — internal road-graph identifiers are never exposed.
  - `matched` boolean, required
  - `confidence` number, required: Matcher confidence 0–1.
  - `distance_km` number, required
  - `duration_seconds` number
  - `edge_count` number, required
  - `edges` TraceEdge[], required
    - `name` string: Road name (omitted for unnamed ways).
    - `road_class` string: Road class (motorway, primary, residential, …).
    - `speed_limit_kph` number: Posted speed limit in km/h, when mapped.
    - `length_m` number, required: Segment length in meters.
    - `surface` string: Surface type (paved_smooth, gravel, …).
    - `truck_route` boolean: True when the segment is a designated truck route.
    - `elevation_m` number, nullable, required: Reserved until an elevation-enhanced road network is promoted — null today.
    - `elevation_ft` number, nullable, required: Reserved until an elevation-enhanced road network is promoted — null today.
    - `grade_pct` number, nullable, required: Reserved until an elevation-enhanced road network is promoted — null today.
    - `weighted_grade` number, nullable, required: Engine-reported per-edge weighted grade, when present.
    - `mean_elevation_m` number, nullable, required: Engine-reported per-edge mean elevation (m), when present.
  - `road_names` string[], required
  - `admins` object[]
  - `costing` string, required
  - `geojson` object
  - `geometry` object
  - `meta` object, required
    - `upstream_ms` number, required
    - `point_count` integer, required
    - `breakage_distance_m` integer: Echoes the breakage_distance_m the caller requested, for confirmation — present only when the caller set it. This is the value SENT to the matcher, not a claim about what it did with it.

## Other responses

- `400`: Invalid request body (fewer than 2 or more than 100 points, bad coordinates).
- `404`: Trace could not be matched to any road (off-road, too sparse, or too noisy).
- `429`: Quota exceeded for this tenant.
- `502`: Upstream matching 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)