Introduction

This is the developer documentation for adres api. Adres api exposes information about all ±9.000.000 Dutch addresses. The API is organized around RESTful principles, it uses predictable resource-oriented URLs, and standard HTTP response codes and verbs. It speaks JSON only and is no frills, and highly performant.

This API was built by developers for developers. You can view its source at GitHub. Feel free to let us know what you think!

Base URL

https://api.adres-api.nl/

Pagination

When retrieving collections, you can specify a limit query parameter with a value of at most 100 items, the default is 10. If the item you're searching for wasn't found in the first batch, you can request the following batch. Specify the starting_after query parameter and set its value to the identifier of the last element of the first batch.

arguments

  • starting_fromidentifier

    Return only entities with an identifier greater than the value of this argument.

  • limitinteger

    The amount of entities to return. Defaults to 10. Valid values are 1 through 100.

Retrieving more than 10 items

/postalcodes?limit=100

Retrieving the next page

/postalcodes?limit=100&starting_after=1011AB

Errors

The API uses conventional HTTP response codes to indicate the success or failure of a request. Generally, codes in the 2xx range indicate success. Codes in the 4xx range indicate client errors, e.g. a required parameter wasn't specified. Codes in the 5xx range indicate an error on the server side, if we do our work right these should never occur.

The attributes described below are always present in the response body if the HTTP status code is not a 2xx code.

Error response attributes

  • status integer

    The HTTP response code.

  • reason string

    A human readable reason phrase so that you don't have to open httpstatuses.com.

  • message string

    A human readable message targeted at client application developers. This field is only present if status is a 4xx code.

  • reference uuid

    This field is only present if status is a 5xx code. If you encounter a 5xx error please send us this reference when you ask for assistance.

HTTP status codes

200 – Ok Everything worked as expected.
400 – Bad Request The server didn't understand the request or refused it, often due to missing a required parameter.
403 – Forbidden The API is only available over https.
429 – Too Many Requests To prevent abuse the API is rate limited
404 – Not Found The requested resource doesn't exist.
500 – Internal Server Error An error on our end.

Rate limit

The api has a hard rate limit of 1 req/s (with bursts of 5 allowed). Because this api is publicly accessible we impose the rate limit to prevent abuse. If you're interested in removing this limit please send us an e-mail.

Addresses

Address objects contain information about a single Dutch address. An address has a unique identifier id. An address is also uniquely identified by the combination of postalcode, housenumber, letter, and suffix.

In daily life the distinction between letter (Dutch: "huisletter") and suffix (Dutch: "toevoeging") is rarely made, the government however keeps track of these separately. When formatting an address, the correct order is letter first, and then suffix.

Operations

GET /addresses
GET /addresses/{id}

The address object

attributes

  • idstring

    The official government issued identifier for this address. Treat it as a string because it can contain leading zeroes.

  • typestring

    An enumerated value.

    If the value of this field is accommodation then the address has an associated accommodation. In the case of the value plot (Dutch: "standplaats") or berth (Dutch: "ligplaats") the address has no associated accommodation, it merely demarcates a piece of land or water for a less permanent structure to be placed on.

  • postalcodestring

    The postalcode of this address.

  • housenumberint

    The housenumber of this address.

  • letterstring

    The (house)letter of this address. Approximately 1 in 10 addresses have a letter. Like the name suggests, a letter is at most 1 character long.

  • suffixstring

    The suffix of this address. Approximately 1 in 20 addresses have a suffix. A suffix can be several characters long.

  • street.idstring

    The official government issued identifier for this street. Treat it as a string because it can contain leading zeroes.

  • street.namestring

    The streetname of this address.

  • locality.namestring

    The name of the locality to which this address is related.

  • municipality.namestring

    The name of the municipality to which this address is related.

  • province.namestring

    The name of the province to which this address is related.

The address object

{
  "id": "1895200000004854",
  "type": "accommodation",
  "postalcode": "9671CA",
  "housenumber": 1,
  "letter": "B",
  "suffix": "1",
  "street": {
    "id": "1895300000000634",
    "name": "Burgemeester Schönfeldplein"
  },
  "locality": {
    "name": "Winschoten"
  },
  "municipality": {
    "name": "Oldambt"
  },
  "province": {
    "name": "Groningen"
  }
}

List addresses

Returns a list of Address objects sorted lexicographically by the id field. This method supports pagination.

Filtering

  • postalcodeoptional string

    Return only addresses that match this postalcode. The postalcode should be provided in this format: /[0-9]{4}[A-Z]{2}/.

  • housenumberoptional integer

    Return only addresses that match this housenumber.

Definition

GET /addresses

Retrieve an address

Returns a single Address object.

Path Parameters

  • idrequired

    The identifier of the address to return.

Definition

GET /addresses/{id}

Postalcodes

Postalcode objects contain information about the locality, municipality, and province to which the postalcode belongs.

Operations

GET /addresses
GET /addresses/{id}

The postalcode object

attributes

  • postalcodestring

    The postalcode. Format is /[0-9]{4}[A-Z]{2}/

  • locality.namestring

    The name of the locality to which the postalcode is related.

  • municipality.namestring

    The name of the municipality to which the postalcode is related.

  • province.namestring

    The name of the province to which the postalcode is related.

The postalcode object

{
  "postalcode": "9671CA",
  "locality": {
    "name": "Winschoten"
  },
  "municipality": {
    "name": "Oldambt"
  },
  "province": {
    "name": "Groningen"
  }
}

List postalcodes

Returns a list of postalcode objects sorted lexicographically by the postalcode field. This method supports pagination.

Filtering

  • locality_nameoptional string

    Return only postalcodes that match this locality.

Definition

GET /postalcodes

Retrieve a postalcode

Returns a single Postalcode object.

Path Parameters

  • postalcoderequired

    Retrieve the postalcode object identified by this postalcode. The postalcode should be specified in this format: /[0-9]{4}[A-Z]{2}/.

Definition

GET /postalcodes/{postalcode}

Streets

Street objects contain information about a street and its associated locality, municipality, and province.

Operations

GET /streets?name=…

The street object

attributes

  • idstring

    The official government issued identifier for this street. Treat it as a string because it can contain leading zeroes.

  • namestring

    The name of the street.

  • locality.namestring

    The name of the locality to which the street is related.

  • municipality.namestring

    The name of the municipality to which the street is related.

  • province.namestring

    The name of the province to which the street is related.

The street object

{
  "id": "1895300000000634",
  "name": "Burgemeester Schönfeldplein",
  "locality": {
    "name": "Winschoten"
  },
  "municipality": {
    "name": "Oldambt"
  },
  "province": {
    "name": "Groningen"
  }
}

List streets

Returns a list of street objects sorted from best match to worst match. This method supports pagination.

Filtering

  • namerequired

    Return only streets with a name matching the search query. A valid search query should contain at least 4 characters. Similarity matching is done by counting shared trigrams.