> ## Documentation Index
> Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# batch_geocode

> Geocode up to 1,000 addresses in one call

Geocode a list of addresses in a single request. Each address can be free text or structured components (street, city, country). Results are returned in the same order as the input — `results[i]` corresponds to `addresses[i]` — and failed items don't break the batch.

## Example prompts

* "Geocode these 5 addresses and tell me which ones are in London"
* "Find coordinates for all the addresses in this list"
* "Batch geocode these office locations and tell me which country each is in"
* "Process these 50 delivery addresses and flag any that couldn't be found"

## What you get back

An array of results aligned with the input addresses. Each entry is one of:

* **Successful match** — the geocoded result fields directly: `coordinates`, `label`, `name`, `district`, `locality`, etc. Same shape as `geocode` returns. Confidence is omitted when 1.0.
* **Failed row** — `{ error }` only, no coordinates. The error is one of `timeout`, `upstream_unavailable`, `rate_limited`, `invalid_input`, or `unknown` — branch on this rather than parsing free text.
* **No match, no error** — `{}` (empty object) preserves array alignment with the input.

The presence of `coordinates` discriminates a successful row from a failure — there's no separate wrapper.

When all matches share the same country / region (e.g. a batch of UK-only addresses), those fields are hoisted to a top-level `context` object instead of being repeated on every row. Mixed-country batches keep the per-row admin fields.

A `summary` object also reports `total`, `matched`, and `failed` counts.

## Tips for landmark queries

Free-text rows benefit from the same query hygiene as `geocode`:

* **Qualify with city context** — `"Big Ben, London"` resolves much more reliably than `"Big Ben"`.
* **Plain street addresses don't need extra context.**

For batch jobs that mix addresses and landmarks, the structured fields (`address`, `locality`, `region`, `country`, etc.) give the most precise control for the address rows.

## Map rendering

Responses include a `render` envelope with a `point` layer for the **successfully** matched rows — failed rows are skipped in the layer (their structured-response row carries an `error` field instead). Pass `compact: true` for summary-only responses. See [response defaults & controls](/mcp/defaults) and [render envelopes](/mcp/render-envelopes).

## Example response

```json theme={null}
{
  "structuredContent": {
    "results": [
      { "name": "London", "coordinates": { "lat": 51.5, "lng": -0.1 } },
      { "error": "no match" },
      { "name": "Paris", "coordinates": { "lat": 48.85, "lng": 2.35 } }
    ],
    "summary": { "total": 3, "matched": 2, "failed": 1 },
    "render": [
      { "kind": "point", "label": "Geocoded addresses", "data": {/* FeatureCollection: only matched rows */}, "bbox": [/* … */] }
    ]
  }
}
```