apyhub
Back
▣ VERIFICATION KIT

Geocode Addresses API

What it does

The Geocode Addresses API turns addresses, postcodes and place names into coordinates using each country's official address register, such as the U.S. Census Bureau, IGN France (Base Adresse Nationale), CartoCiudad in Spain, BAG in the Netherlands and the Norwegian Matrikkel. Send up to 100 lines in addresses, or points in coordinates for reverse lookups, and get back one row per input in items with lat, lon, a formatted_address, the match precision, a score, the source register and its licence.

Forward geocoding covers the US, Canada, the UK (postcode and place level), France, Spain, the Netherlands, Switzerland, Norway, Estonia and Poland. The country is detected from each line (postcode format, city or country name). Set country to force one country for every line, or prefix a single line like FR: 8 bd du Port, 80000 Amiens. Reverse geocoding covers the US, UK, France, Spain, the Netherlands, Norway and Poland and returns the nearest official address (or the nearest postcode in the UK, or the county and census tract in the US). Set includeCensus to true to add state, county and census tract FIPS codes to US rows.

Use it to place customer or store addresses on a map, enrich US addresses with census geography for demographics, insurance or lending work, or turn device coordinates into an official address. Each row reports its own status, so addresses that are not found, outside coverage or temporarily unavailable do not fail the whole batch.

POST
Geocoding API - Official Registers
https://api.eu.apyhub.com/martin10291/geocode-official-addresses

QUICKSTART

GUIDE

Quickstart

Geocode a batch of addresses in different countries and let the API detect each country.

curl -X POST "https://api.eu.apyhub.com/martin10291/geocode-official-addresses" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addresses": ["1600 Pennsylvania Ave NW, Washington, DC 20500", "Damrak 1, 1012 LG Amsterdam", "Calle Gran Via 28, Madrid", "10 Downing Street, London SW1A 2AA"]}'

What you'll get back

Returns a JSON object with count, billed and an items array, one row per address with its status, coordinates, formatted_address, match precision, score and the source register. The example below is trimmed to the first 2 of the 4 rows.

{
  "billed": 4,
  "count": 4,
  "items": [
    {
      "checked_at": "2026-11-17T08:13:30Z",
      "city": "WASHINGTON",
      "country": "United States",
      "country_code": "US",
      "country_detected": true,
      "formatted_address": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500",
      "house_number": "1600",
      "input": "1600 Pennsylvania Ave NW, Washington, DC 20500",
      "lat": 38.8987026,
      "licence": "Public domain (U.S. Government work)",
      "lon": -77.0351892,
      "official_id": "TIGER:76225813",
      "postcode": "20500",
      "precision": "interpolated (address range)",
      "region": "DC",
      "response_ms": 524,
      "score": 1.0,
      "source": "U.S. Census Bureau Geocoder",
      "status": "ok",
      "street": "PENNSYLVANIA AVE NW"
    },
    {
      "checked_at": "2026-11-17T08:13:29Z",
      "city": "Amsterdam",
      "country": "Netherlands",
      "country_code": "NL",
      "country_detected": true,
      "formatted_address": "Damrak 1, 1012LG Amsterdam",
      "house_number": "1",
      "input": "Damrak 1, 1012 LG Amsterdam",
      "lat": 52.3771445,
      "licence": "CC0 1.0",
      "lon": 4.8980385,
      "official_id": "BAG:0363200012113669",
      "postcode": "1012LG",
      "precision": "rooftop (BAG address)",
      "region": "Noord-Holland",
      "response_ms": 298,
      "score": 1.0,
      "source": "PDOK Locatieserver (BAG)",
      "status": "ok",
      "street": "Damrak"
    }
  ]
}
TRY ITLIVE · 100 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
One country for every address line. 'auto' detects it per line. A per-line prefix overrides it.
addresses
Addresses, postcodes or place names, up to 100 per call. Send addresses, coordinates or both. The country is detected from the text; prefix a line like 'FR: 8 bd du Port, 80000 Amiens' to force it. Covered: US, CA, GB (postcode/place level), FR, ES, NL, CH, NO, EE, PL.
coordinates
Points to reverse geocode as 'lat,lon' in decimal degrees, e.g. 52.3759,4.8975. Returns the nearest official address (FR, ES, NL, NO, PL), the nearest postcode (GB) or the county and census tract (US).

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

ParameterTypeDescription
addressesString ArrayAddresses, 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.
coordinatesString ArrayPoints 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.
countryENUMOne 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.
includeCensusBooleanFor 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.

ParameterTypeDescription
countIntegerNumber of rows in items.
billedIntegerProvider-side count of ok rows. Rows with any other status are not counted. ApyHub charges per call, not per row.
itemsObject ArrayOne result per input.
items[].inputStringThe input line or coordinate as sent (a country prefix is removed).
items[].statusENUMAllowed 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[].latNumberLatitude of the match. null unless status is ok.
items[].lonNumberLongitude of the match. null unless status is ok.
items[].formatted_addressStringAddress as written in the register. null unless status is ok.
items[].streetStringStreet name. null when not part of the match (postcode or place-level results).
items[].house_numberStringHouse number. null when not part of the match.
items[].postcodeStringPostcode.
items[].cityStringCity or municipality.
items[].regionStringState, province or region.
items[].countryStringCountry name. null when the country is unknown.
items[].country_codeStringTwo-letter country code. null when the country is unknown.
items[].country_detectedBooleantrue when the country was detected from the text. Only present on forward rows when country is auto and the line has no prefix.
items[].precisionStringMatch level reported by the register, for example rooftop (BAG address), rooftop / entrance, interpolated (address range), street, postcode centroid, postcode, geoname (location).
items[].scoreNumberMatch confidence from 0 to 1, as reported by the register.
items[].official_idStringRegister identifier of the match, for example BAG:0363200012113669 or TIGER:76225813.
items[].sourceStringRegister 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[].licenceStringLicence 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_mNumberReverse rows only. Distance in metres from the input point to the returned address or postcode.
items[].censusObjectUS rows with includeCensus: true. Fields: state, state_fips, county, county_fips, tract, tract_geoid.
items[].extraObjectGB rows only. Additional ONS data for the postcode, such as constituency and lsoa.
items[].errorStringReason for a row that is not ok. On ok rows it is null (reverse rows) or left out (forward rows).
items[].checked_atStringTime this row was produced, ISO 8601 UTC.
items[].response_msIntegerUpstream 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 502 with code: upstream_unavailable; in a multi-input request the same input gets an unavailable row instead.
  • Errors use one shape: {"code": "invalid_input", "error": "...", "message": "..."}.
▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.