About this endpoint
What it does
Geocodes up to 100 address lines, or reverse geocodes coordinates, against official national address registers and returns one result row per input with coordinates, match precision and the register that answered.
Request Body
| Parameter | Type | Description |
|---|---|---|
| addresses | String Array | Addresses, postcodes or place names to geocode. Send addresses, coordinates or both. The country of each line is detected from the text; prefix a line with a country code and a colon (FR: 8 bd du Port, 80000 Amiens) to force it. Max 100 items. Empty values, hidden characters (zero-width space, BOM) and markup are rejected with 400. |
| coordinates | String Array | Points to reverse geocode, each as "lat,lon" in decimal degrees, for example "52.3759,4.8975". Reverse geocoding covers US, GB, FR, ES, NL, NO and PL. Max 100 items. |
| country | ENUM | One country for every address line. Allowed values: auto, US, CA, GB, FR, ES, NL, CH, NO, EE, PL. Default: auto (detect per line). Not case sensitive. A per-line prefix overrides it. |
| includeCensus | Boolean | For US rows, also return state, county and census tract FIPS codes from the Census Bureau. Default: false. Ignored for other countries. |
Response
Returns a JSON object with count, billed and an items array with one row per distinct input line, addresses first and then coordinates, in the order sent. Rows share the same core fields; fields the register does not provide are null.
| Parameter | Type | Description |
|---|---|---|
| count | Integer | Number of rows in items. |
| billed | Integer | Provider-side count of ok rows. Rows with any other status are not counted. ApyHub charges per call, not per row. |
| items | Object Array | One result per input. |
| items[].input | String | The input line or coordinate as sent (a country prefix is removed). |
| items[].status | ENUM | Allowed values: ok, not_found, unsupported_country, invalid_input, unavailable. ok: matched. not_found: no match in the register. unsupported_country: country not covered or not detected from the text. invalid_input: malformed coordinate. unavailable: the register did not answer; retry later. |
| items[].lat | Number | Latitude of the match. null unless status is ok. |
| items[].lon | Number | Longitude of the match. null unless status is ok. |
| items[].formatted_address | String | Address as written in the register. null unless status is ok. |
| items[].street | String | Street name. null when not part of the match (postcode or place-level results). |
| items[].house_number | String | House number. null when not part of the match. |
| items[].postcode | String | Postcode. |
| items[].city | String | City or municipality. |
| items[].region | String | State, province or region. |
| items[].country | String | Country name. null when the country is unknown. |
| items[].country_code | String | Two-letter country code. null when the country is unknown. |
| items[].country_detected | Boolean | true when the country was detected from the text. Only present on forward rows when country is auto and the line has no prefix. |
| items[].precision | String | Match level reported by the register, for example rooftop (BAG address), rooftop / entrance, interpolated (address range), street, postcode centroid, postcode, geoname (location). |
| items[].score | Number | Match confidence from 0 to 1, as reported by the register. |
| items[].official_id | String | Register identifier of the match, for example BAG:0363200012113669 or TIGER:76225813. |
| items[].source | String | Register that answered, for example PDOK Locatieserver (BAG), IGN Geoplateforme (Base Adresse Nationale), CartoCiudad (IGN Spain, Catastro), U.S. Census Bureau Geocoder, postcodes.io (ONS Postcode Directory, OS Open Names), Natural Resources Canada Geolocator. |
| items[].licence | String | Licence of the source data, for example CC0 1.0, CC BY 4.0 (scne.es), Public domain (U.S. Government work). Keep it for attribution. |
| items[].distance_m | Number | Reverse rows only. Distance in metres from the input point to the returned address or postcode. |
| items[].census | Object | US rows with includeCensus: true. Fields: state, state_fips, county, county_fips, tract, tract_geoid. |
| items[].extra | Object | GB rows only. Additional ONS data for the postcode, such as constituency and lsoa. |
| items[].error | String | Reason for a row that is not ok. On ok rows it is null (reverse rows) or left out (forward rows). |
| items[].checked_at | String | Time this row was produced, ISO 8601 UTC. |
| items[].response_ms | Integer | Upstream response time in milliseconds. |
Notes
- UK addresses resolve to postcode or place level, not to a building.
- Reverse geocoding in the US returns census geography (county and tract) at the input point, not a street address.
- Repeated inputs in one request return a single row.
- A request whose only input fails upstream returns
502withcode: upstream_unavailable; in a multi-input request the same input gets anunavailablerow instead. - Errors use one shape:
{"code": "invalid_input", "error": "...", "message": "..."}.



