---
title: "Resolve a named cross-street to coordinates"
method: POST
path: "/v1/intersection"
tags: ["Intersections"]
---

# Resolve a named cross-street to coordinates

`POST /v1/intersection`

## Request

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

Resolve a named intersection (street1 × street2 within a locality/region/country) to a single best coordinate with a confidence score, admin context, and a fleet-safe fallback. The high-confidence tier matches US-metro highway corners; named non-highway streets resolve through the geocoder fallback. Costs 1 quota unit. `POST /v1/intersections/resolve` is a functional alias with the identical contract (retained for compatibility; not separately listed).

## Request body

- IntersectionResolveRequest: Resolve a named cross-street to coordinates. The high-confidence tier (CSV) is US highways only; named non-highway streets resolve via the geocoder fallback (global, lower-confidence). For free-form streets use /v1/geocode.
  - `street1` string, required: First street of the cross-street pair.
  - `street2` string, required: Second (cross) street of the pair.
  - `locality` string: City / town that scopes the lookup.
  - `region` string: State / province (full name or abbreviation, e.g. 'TX').
  - `country` string: ISO 3166-1 alpha-2/alpha-3 country code to scope results.
  - `confidence_threshold` number: Confidence floor (0–1) below which a CSV/geocoder hit falls through to the next resolution rung. Defaults to 0.5.

## Response `200`

Resolved intersection (or honest-empty `feature: null` with a coverage warning).

- IntersectionResolveResponse
  - `feature` IntersectionResolvedFeature, nullable, required: Best resolved intersection feature, or null when nothing resolved.
    - `id` string: Stable public ThinAir id (`ta_intersection_<key>` when the resolved doc carries the derivation inputs, else `ta_place_<key>`). Resolvable via `GET /v1/place`.
    - `name` string
    - `label` string
    - `confidence` number
    - `layer` string
    - `intersection_type` 'corner' | 'interchange'
    - `intersection_precision` 'geometric_crossing' | 'tangent_intersection' | 'centroid_cluster' | 'approximate'
    - `street_kind` 'street' | 'route'
    - `cross_street_kind` 'street' | 'route'
    - `street_route` string
    - `cross_street_route` string
    - `place_type` string, required
    - `method` string, required
    - `lat` number, required
    - `lon` number, required
  - `confidence` number, required: Resolved feature's confidence (0–1); 0 when unresolved.
  - `fallback_used` boolean, required: True when the geocoder fallback produced the answer (CSV missed or was below threshold).
  - `admin` object, required: Admin context echoed back.
    - `locality` string
    - `region` string
    - `country` string
  - `meta` object, required: Resolution metadata; `method` is the rung that resolved (csv_intersection | intersection | none).
    - `upstream_ms` number, required
    - `method` string, required
    - `query` string, required
  - `warnings` string[]: Advisory strings — present on a miss (coverage hint) or geocoder suppress signals.
  - `upstream_error` string, nullable
  - `precision` object: Learning-overlay precision adjudication. Present only when the flag-gated overlay applied to this resolution. Omitted otherwise — legacy consumers see no shape change.
    - `class` string, required
    - `risk_flags` string[], required
    - `required_context` string[], required
    - `learning_overlay` object, required
      - `applied` boolean, required
      - `rule_ids` string[]
      - `actions` string[]

## Other responses

- `400`: Invalid request body.
- `429`: Quota exceeded for this tenant.
- `502`: Upstream geocoder 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)