AccountCloud
NLGet a test key

The right address form for 34 countries.

Which fields an address has in each country, in which order, which ones are required and what the postcode looks like. Plus validating an address and formatting it the way its country writes it.

Get a test keyRead the guide
Status
LiveGenerally available, for live and test keys.
Price
free
Operations
address.formsaddress.validateaddress.format
Docs
The guideAPI referenceTest values

What it does

What you can do

  • Get the form for a country. The fields in the order to ask for them, each with an English or Dutch label, whether it’s required, its maximum length, the HTML autocomplete token and a place on a 12-column grid. Plus the postcode pattern with an example, and the provinces or regions where a country uses them.
  • Validate an address. You get it back normalised: trimmed, the postcode in its national form and a region as its code. If something is wrong, the answer says what, field by field.
  • Format an address. The lines as the address’s country writes them. When the letter is sent from another country, the country line is added.

The countries

The EU, the EEA, Switzerland, the United Kingdom, Turkey and the United Arab Emirates: AE, AT, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK and TR.

Where it comes from

The register combines Google’s libaddressinput address data with the rules of the national postal operators, and each country is tested against fixed examples. The verified field tells you whether a form was checked against the rules of that country’s postal operator.

The address forms are partly based on the address data of Google libaddressinput, licensed under CC BY 4.0, with our own changes per country.

Good to know

  • Address forms are live and free. Validating and formatting are in preview: until they have a price, a live key gets 503 operation_unavailable. Test keys already get real answers.
  • A country we don’t support gets 404 country_not_supported, with the list of countries we do.

Example

Real calls with a test key. Replace ac_test_… with your own key.

The address form of the Netherlands: which fields, in which order, and the postcode.
GET/v1/address/forms/NL
Request
curl https://api.accountcloud.io/v1/address/forms/NL \
  -H "Authorization: Bearer ac_test_…"
Response200 OKshortened
AccountCloud-Charged: 0.0000
{
  "country": "NL",
  "verified": true,
  "fields": [
    {
      "id": "street",
      "label": "Street",
      "type": "text",
      "required": true,
      "max_length": 255,
      "options": null,
      "options_source": null,
      "example": null,
      "autocomplete": "address-line1",
      "layout": { "row": 1, "column": 1, "span": 8 }
    },
    {
      "id": "postal_code",
      "label": "Postal code",
      "type": "text",
      "required": true,
      "max_length": 20,
      "options": null,
      "options_source": null,
      "example": "1234 AB",
      "autocomplete": "postal-code",
      "layout": { "row": 3, "column": 5, "span": 4 }
    }
  ],
  "postcode": {
    "pattern": "[1-9]\\d{3} ?(?:[A-RT-Z][A-Z]|S[BCE-RT-Z])",
    "example": "1234 AB"
  },
  "subdivisions": []
}
Validate an address: the postcode comes back normalised.
POST/v1/address/validate
Request
curl https://api.accountcloud.io/v1/address/validate \
  -H "Authorization: Bearer ac_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "country": "NL", "street": "Hoofdstraat", "house_number": "12",
      "postal_code": "1234ab", "city": "Amsterdam"
    }
  }'
Response200 OK
AccountCloud-Charged: 0.0000
{
  "valid": true,
  "address": {
    "country": "NL",
    "street": "Hoofdstraat",
    "house_number": "12",
    "postal_code": "1234 AB",
    "city": "Amsterdam"
  },
  "errors": []
}
The same address, formatted for a letter sent from Belgium: with the country line added.
POST/v1/address/format
Request
curl https://api.accountcloud.io/v1/address/format \
  -H "Authorization: Bearer ac_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "country": "NL", "street": "Hoofdstraat", "house_number": "12",
      "postal_code": "1234ab", "city": "Amsterdam"
    },
    "from_country": "BE"
  }'
Response200 OK
AccountCloud-Charged: 0.0000
{
  "country": "NL",
  "lines": ["Hoofdstraat 12", "1234 AB Amsterdam", "Netherlands"],
  "text": "Hoofdstraat 12\n1234 AB Amsterdam\nNetherlands"
}

What it costs

Addressesfreethe address form of a country
Validate an addresspreviewprice to followfields and postcode, by the country's rules
Format an addresspreviewprice to followas the lines on an envelope

Excluding VAT, from your prepaid balance. Test keys are free, and an error or invalid input costs nothing.

Until it has a price, a live key gets 503 operation_unavailable. Test keys work already.

Read more

Start with a test key. It's free.

Signing up takes a minute. The quickstart in the docs, five.

Get a test keyRead the guide