Skip to main content
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 and render envelopes.

​
Example response

{
  "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": [/* … */] }
    ]
  }
}