---
title: "`POST /geocode/batch`: many geocodes in one call."
method: POST
path: "/geocode/batch"
tags: ["geocoding"]
---

# \`POST /geocode/batch\`: many geocodes in one call.

`POST /geocode/batch`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/geocode/batch`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

## Request body

- GeocodeBatchRequest: A batch of forward and reverse geocode queries.
  - `queries` GeocodeBatchQuery[], required: The queries, up to [`MAX_BATCH_QUERIES`]. Order is preserved in the response.
    - `city` string, nullable: Town or city (structured).
    - `country` string, nullable: ISO 3166-1 alpha-2 code or country name (structured), or a comma-separated list of them, which narrows the search to those countries instead.
    - `housenumber` string, nullable: House number (structured).
    - `lat` number, double, nullable: Latitude (WGS84). With `lon` and no forward query, a reverse lookup; alongside a forward query, a location bias.
    - `limit` integer, nullable: Maximum results for this entry, 1–10 (default 1).
    - `lon` number, double, nullable: Longitude (WGS84). See `lat`.
    - `postcode` string, nullable: Postcode (structured).
    - `q` string, nullable: Free-text place query.
    - `street` string, nullable: Street name (structured).

## Response `200`

One result per query, in request order. Each carries either `features` (the same GeoJSON FeatureCollection the single endpoints return, `match` object included when the entry named structured components) or `problem` (an RFC 9457 object describing what went wrong with THAT entry). A failing entry never fails the batch

- GeocodeBatchResponse: The batch response: one result per query, in the order they were sent.
  - `results` GeocodeBatchResult[], required: One entry per query, `index`-tagged and in request order.
    - `features` unknown
    - `index` integer, required: Zero-based position of this query in the request.
    - `problem` unknown

## Other responses

- `400`: Malformed body, or an empty `queries` array
- `401`: Missing or invalid API key
- `422`: More than 1,000 queries (`urn:sn-gateway:problem:batch-too-large`, body carries `max_queries` and `queries`)
- `429`: Quota or rate limit exceeded
- `501`: Geocoding not enabled (neither SN_GEOCODE_DIR nor SN_PHOTON_URL set)

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)