Geocode an address to a coordinate (South Africa)
geocode_addressConvert a single delivery address into a point with its precision level, so you can tell whether to dispatch, ask for a landmark, or confirm with the customer.
Instructions
Turn ONE address into a point, with an honest account of how much of it was found. Built for deliveries. South Africa today; more countries as their data loads. 1 lookup per address, found or not.
Send either q (one line) or address (housenumber, street, suburb, city, postcode, unit) — never both. If the address is already split, send it split: it matches better.
READ precision BEFORE using the point. "address" means the house was found; "interpolated" means it was estimated between the numbers either side; "intersection" means a street corner ("Cnr Main Rd and Belmont Rd", "Bree & Strand Streets"), at the point where the two meet, with the second street in matched.crossStreet; "site" means a named site — a shopping centre, office park, complex or estate, hospital, school, airport or hotel — at a point inside it, named in matched.site; "street" means the right street but NOT the house; "locality" means only the suburb or town. NEVER present a street- or locality-level point as a door: a driver sent there will be at the wrong house. In South Africa most answers are street-level, because OpenStreetMap has house numbers on about 13% of street names — that is the data being honest, not a failure.
What to do with an answer — the result line says which applies:
address, interpolated, intersection or site, not ambiguous, confidence 0.5 or more: dispatch. For a site, pass on the unit or shop number from the original address ("Shop 12") — the answer does not include it, and the driver needs it.
street: ask the recipient for a pin or a landmark.
ambiguous, or locality: ask the customer before dispatching. When the advice is to ask the customer, ASK — do not pick one. result.alternatives holds up to 4 other candidates the answer was chosen from, and the result line lists them with the suburb each lies in and its distance and direction from the first, because they often share a street name AND a town (five "Long Street, Cape Town"s: City Centre, Observatory, Maitland…). Put the first answer and those to the user, by suburb. Free: still one lookup. matched.locality is the place the caller wrote; matched.suburb is the suburb the point actually lies in, absent at locality precision and where no suburb is near. confidence ranks answers; it is NOT a probability. ambiguous means a same-named street elsewhere scored about as well, or the street was a near-miss spelling with no house number to confirm it. result null means nothing trustworthy was found, and that still costs the lookup.
Some addresses name something that cannot be placed: an erf, stand, plot or farm portion (land parcels — there is no cadastre), a township stand, a PO box or private bag. Those parts come back in unmatched and the answer is the place named, at locality: ask the customer for a street address.
country is a hard filter; region (ZA-WC, or "Western Cape") only ranks streets inside it first, so a wrong province does not lose the address. An uncovered country is refused, unbilled, with the list of covered countries in the message — that message is the live coverage list; there is no other. sets and base answer "which delivery zone is it in" in the same call, at no extra cost.
One address per call, deliberately. For a delivery list, call this once per row so the user sees what is being spent; programs with thousands of rows should use the API’s POST /geocode/batch directly. Not for: searching for a business or landmark by name, or a coordinate to an address (that is lookup_location with the street layer).
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "geocode_address"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | The whole address on one line, e.g. "25 Adderley Street, Cape Town". | |
| base | No | Administrative layers to resolve at the found point. | |
| sets | No | Boundary sets on this account to match at the found point, e.g. delivery zones. | |
| region | No | ISO 3166-2 ("ZA-WC") or a name ("Western Cape"). A preference, not a filter. | |
| address | No | The address already split into parts. Needs at least a street. Use instead of q. | |
| country | No | ISO 3166-1 alpha-2, e.g. "ZA". A hard filter: only that country is searched. | |
| streetGeometry | No | The matched street’s line, trimmed to about 250 m. Only if something will draw it. |