---
title: "Batch geocode — up to 50 addresses in one call"
method: POST
path: "/v1/geocode/batch"
tags: ["Geocoding"]
---

# Batch geocode — up to 50 addresses in one call

`POST /v1/geocode/batch`

## Request

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

Geocode multiple addresses in one request with structured per-row results (per-row errors never fail the batch). Costs 1 quota unit per call — the same debit the MCP batch_geocode tool applies. Alias of `POST /v1/batch` (the canonical documented path) — retained for compatibility; not deprecated.

## Request body

- BatchGeocodeRequest
  - `addresses` string[], required: Addresses to geocode, in order (1–50 per batch). Empty rows are echoed back as per-row `empty_address` errors rather than failing the batch.

## Response `200`

Per-row batch results (successes and failures interleaved, input order preserved).

- BatchGeocodeResponse
  - `items` BatchGeocodeRestItem[], required
    - `input` string, required
    - `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
    - `method` string
    - `lat` number
    - `lon` number
    - `low_confidence` true
    - `error` string
    - `error_message` string
  - `meta` object, required
    - `upstream_ms` number, required
    - `feature_count` number, required
    - `low_confidence_count` number, required
    - `failed_count` number, required
    - `low_confidence_threshold` number, required
  - `geojson` object, required: FeatureCollection built from the successful (coordinate-bearing) rows only — failed rows still appear in `items`.
    - `type` 'FeatureCollection', required
    - `features` object[], required
      - `type` 'Feature', required
      - `geometry` object, required
        - `type` 'Point', required
        - `coordinates` unknown[], required
          - unknown
      - `properties` object, required

## Other responses

- `400`: Invalid request body (missing/empty/oversized addresses array).
- `429`: Quota exceeded.
- `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)