---
title: Geocode Addresses API
slug: geocode-official-addresses
url: https://apyhub.com/martin10291/service/geocode-official-addresses
provider: Martin Petrov
categories: [Verification Kit]
tags: [geocoding, address-validation, postcode-lookup, location-normalization, reverse-geocoding]
auth: api_key
version: 1.0
service_type: sync
endpoints: 1
atoms: 100
mcp: true
---

# Geocode Addresses API

Resolve addresses, postcodes, place names, and coordinates into official location rows. Supports country detection, reverse geocoding, and US census fields.

## Endpoints

| Method | URL | Description | Atoms |
| --- | --- | --- | --- |
| POST | `https://api.eu.apyhub.com/martin10291/geocode-official-addresses` | What it does Geocodes up to 100 address lines, or reverse geocodes coordinates, against official na… | 100 |

## Endpoint reference

### Geocoding API - Official Registers

`POST https://api.eu.apyhub.com/martin10291/geocode-official-addresses` · 100 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | body | string | no | One country for every address line. 'auto' detects it per line. A per-line prefix overrides it. One of: auto, US, CA, GB, FR, ES, NL, CH, NO, EE, PL. Default: `auto`. Example: `auto`. |
| `addresses` | body | array of string | no | 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. C… |
| `coordinates` | body | array of string | no | 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… |
| `includeCensus` | body | boolean | no | For US rows, also return state, county and census tract FIPS codes (GEOID) from the Census Bureau. Default: `false`. Example: `false`. |

#### Quickstart

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

```bash
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.

```json
{
  "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"
    }
  ]
}
```

## About

## 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.

## Usage

Base URL: `https://api.eu.apyhub.com` (default region — see
`GET https://apyhub.com/api/public/regions` for the rest).

Authenticate with an ApyHub API key in the `apy-token` header.
Full docs and a live playground: https://apyhub.com/martin10291/service/geocode-official-addresses
