resolve_location
Turn a place name or a lat/lon point into canonical area_ids (max 5 candidates).
Turn a place name or a lat/lon point into canonical area_ids (max 5 candidates). If status is 'ambiguous', do NOT pick one: ask the user or call again with area_type.
Counts against your plan: yes, one call. Read-only: yes, nothing you send is stored or changes any data.
Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | no | none | Place name, e.g. 'Matzikama', 'Kenilworth', 'West Coast'. |
lat | number | no | none | WGS84 latitude (with lon) |
lon | number | no | none | WGS84 longitude (with lat) |
area_type | "province" / "district" / "local_municipality" / "ward" / "police_station" | no | none | Restrict to one geography type |
Caps
| Cap | Value |
|---|---|
| Candidates returned | 5 |
Your plan can set lower caps. See Plans and limits. A request over a cap is refused with LIMIT_EXCEEDED; nothing is truncated silently.
Response
Every response also carries citations, caveats and dataset_version (Citations).
| Field | Type | Description |
|---|---|---|
citations | object[] | |
caveats | string[] | |
dataset_version | string | |
status | "resolved" / "ambiguous" / "not_found" | |
resolved_area_id | string | |
candidates | object[] | |
message | string |
candidates[] (each item)
| Field | Type | Description |
|---|---|---|
area_id | string | |
name | string | |
area_type | string | |
province_code | string | |
parent_id | string | |
parent_name | string | |
match | "exact" / "prefix" / "contains" / "point_in_polygon" |
Examples
Fixture data
These responses were produced by the real tool against the synthetic test dataset (fixture-2026.11.05), so the numbers are illustrative, not real statistics. Production responses cite the real sources.
A unique match
Request:
{
"query": "Matzikama"
}Response:
{
"citations": [
{
"source_id": "mdb_wards_2026",
"name": "[FIXTURE] MDB Wards 2026",
"publisher": "Municipal Demarcation Board (MDB)",
"url": "https://www.demarcation.org.za/",
"licence": "MDB custom terms",
"commercial_use": "unclear",
"attribution": "Source: Municipal Demarcation Board (MDB)",
"retrieved_at": "2026-11-05",
"dataset_version": "fixture-2026.11.05"
}
],
"caveats": [
"FIXTURE DATA: these numbers are synthetic test values, not real statistics. Do not use them for decisions.",
"Licence note (mdb_wards_2026): MDB custom terms; commercial use 'unclear'. Served only as derived aggregates with attribution: Source: Municipal Demarcation Board (MDB)"
],
"dataset_version": "fixture-2026.11.05",
"status": "resolved",
"resolved_area_id": "lm:WC011",
"candidates": [
{
"area_id": "lm:WC011",
"name": "Matzikama",
"area_type": "local_municipality",
"province_code": "WC",
"parent_id": "dm:DC1",
"parent_name": "West Coast",
"match": "exact"
}
],
"message": "Resolved to Matzikama (local_municipality)."
}Provenance in this example: source mdb_wards_2026, licence “MDB custom terms”, retrieved 2026-11-05, dataset_version fixture-2026.11.05.
An ambiguous name (two police stations are called Kenilworth)
Request:
{
"query": "Kenilworth",
"area_type": "police_station"
}Response:
{
"citations": [
{
"source_id": "saps_crime_stats",
"name": "[FIXTURE] SAPS Crime Statistics",
"publisher": "South African Police Service (SAPS)",
"url": "https://www.saps.gov.za/services/crimestats.php",
"licence": "SAPS website copyright (no open licence)",
"commercial_use": "unclear",
"attribution": "Source: South African Police Service, Crime Statistics",
"retrieved_at": "2026-11-05",
"dataset_version": "fixture-2026.11.05"
}
],
"caveats": [
"FIXTURE DATA: these numbers are synthetic test values, not real statistics. Do not use them for decisions.",
"Licence note (saps_crime_stats): SAPS website copyright (no open licence); commercial use 'unclear'. Served only as derived aggregates with attribution: Source: South African Police Service, Crime Statistics"
],
"dataset_version": "fixture-2026.11.05",
"status": "ambiguous",
"resolved_area_id": null,
"candidates": [
{
"area_id": "saps:kenilworth-gt",
"name": "Kenilworth",
"area_type": "police_station",
"province_code": "GT",
"parent_id": "prov:GT",
"parent_name": "Gauteng",
"match": "exact"
},
{
"area_id": "saps:kenilworth-wc",
"name": "Kenilworth",
"area_type": "police_station",
"province_code": "WC",
"parent_id": "prov:WC",
"parent_name": "Western Cape",
"match": "exact"
}
],
"message": "'Kenilworth' matches several places; no guess was made. Ask the user which one they mean, or call again with area_type or a more specific name."
}Provenance in this example: source saps_crime_stats, licence “SAPS website copyright (no open licence)”, retrieved 2026-11-05, dataset_version fixture-2026.11.05.
Errors
Errors read <CODE>: <what went wrong>. Fix: <how to fix it>. Shared codes are on the Tool reference page.
| Request | Error |
|---|---|
{} | INVALID_ARGUMENT: Give a place name (query) or a point (lat and lon). Fix: e.g. resolve_location(query='Matzikama') or resolve_location(lat=-31.6, lon=18.5). |
{"lat": -31.0} | INVALID_ARGUMENT: lat and lon must be given together. Fix: Pass both lat and lon. |