Geocode an address to a coordinate (South Africa)
geocode_addressConvert a single address into a coordinate and precision level for delivery dispatch, showing whether the house, street, intersection, or locality was found.
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. 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).
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. |