Geocode names in batch
geocode_batchRead-onlyIdempotent
Geocode up to 20 free-text queries in one call, one best match each.
Instructions
Geocode up to 20 free-text queries in one call, one best match each.
Cuts N round-trips of geocode() into one and, more importantly,
shares ONE local divisions name table across the batch (#329) so a
two-name walk is not N cold S3 scans. For each query, keeps only
the top candidate.
Returns {"results": [{"query", "name", "type", "lat", "lon", "id"
(GERS), "rank_score"}, ...]}, one row per query, in input order — a
query with no match gets the standard error envelope {"query",
"error": "not_found", "detail"} instead, and does not fail the rest of
the batch. queries is capped at 20; a longer list returns a structured
{"error": ...} rather than truncating silently. Budgeted like every
other tool. Returns a structured {"error": ...} instead of raising if
the remote scan itself fails.
country (#457, ISO 3166-1 alpha-2, also accepting alpha-3 and aliases
like "UK"/"USA", case-insensitive) applies the same "City, Country"
constraint geocode() takes to every query in the batch — e.g.
`geocode_batch(["Cambridge", "London"], country="CA")` answers with
Ontario's London and a not_found row for Cambridge (no Canadian
Cambridge in the dataset), rather than the UK/US namesakes each query
would otherwise resolve to on its own. An unrecognized `country`, or a
per-query suffix that disagrees with it, returns a structured
{"error": "bad_request", ...} for the whole call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ||
| queries | Yes | ||
| limit_per_query | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||