DirectMatch API

In the examples below, the following address is used:
Amersfoort Krankeledenstraat 30 3811BN.

This address Onze Lieve Vrouwetoren - Amersfoort, is the central point according to the Dutch map projection of the Dutch National Triangulation (with coordinates +155 000 m +463 000 m).

The DirectMatch API is a simple and fast API for directly looking up addresses when you already know the postcode and house number. Unlike the Autocomplete API, which offers a progressive search function, DirectMatch directly returns the complete address result.

Countries

The examples below apply to the Netherlands. At postcode-api.nl we also offer Belgium and Luxembourg, these two datasets can be found at /v1/directmatch/be/ and /v1/directmatch/lu/

For both Belgium and Luxembourg, a street name is required for an exact address determination. Example:

GET /v1/directmatch/be/1457/3/Place%20Saint-Martin
Headers: Authorization: Bearer $YOUR_TOKEN

{
  "housenumber": "3",
  "postcode": "1457",
  "street": {
    "fr": "Place Saint-Martin"
  },
  "location": {
    "bd72": [
      172028.815700002,
      148008.930100001
    ],
    "wgs84": [
      50.64229975517471,
      4.680189802852158
    ]
  },
  "municipality": {
    "de": "Walhain",
    "fr": "Walhain",
    "nl": "Walhain"
  },
  "province": {
    "de": "Wallonisch-Brabant",
    "fr": "Brabant wallon",
    "nl": "Waals-Brabant"
  }
}

However, it is also possible to omit the street name. But there is a good chance you will get multiple results back, because: "a postcode area can overlap multiple streets in Belgium/Luxembourg".

Using the DirectMatch API

The DirectMatch API works directly without context or session IDs. You only need to provide the postcode and house number, and optionally a house number addition.

The API has two variants:

Postcode + house number
Postcode + house number + house number addition

Example 1: Basic lookup with postcode and house number

We look up the address with postcode 3811BN and house number 30:

HTTP Request:

GET /v1/directmatch/nl/3811BN/30
Headers: Authorization: Bearer YOUR_API_KEY

HTTP JSON Response from https://api.postcode-api.nl:

{
  "city": "Amersfoort",
  "housenumber": "30",
  "municipality": "Amersfoort",
  "postcode": "3811BN",
  "province": "Utrecht",
  "street": "Krankeledenstraat",
  "location": {
    "rd": [
      155014.59,
      462985.67
    ],
    "wgs84": [
      52.15504560250615,
      5.387419406464223
    ]
  }
}

Example 2: Lookup with house number letter

For addresses with a house number addition (such as "A", "bis", "1" etc.), you can provide this as a third parameter.

For example, we look up the address 3811BN 1A:

HTTP Request:

GET /v1/directmatch/nl/3811BN/1/A
Headers: Authorization: Bearer $YOUR_TOKEN

HTTP JSON Response from https://api.postcode-api.nl:

{
  "city": "Amersfoort",
  "housenumber": "1",
  "housenumberaddition": "A",
  "municipality": "Amersfoort",
  "postcode": "3811BN",
  "province": "Utrecht",
  "street": "Krankeledenstraat",
  "location": {
    "rd": [
      155000.12,
      463000.45
    ],
    "wgs84": [
      52.15515,
      5.38725
    ]
  }
}

Example 3: Looking up a house number with letter and addition

To look up an address with house number + letter and an addition:

For example, we search for the address with postcode 4462CB, house number 190, letter F and addition 3015:

HTTP Request:

GET /v1/directmatch/nl/4462CB/190/F3015
Headers: Authorization: Bearer $YOUR_TOKEN

HTTP JSON Response from https://api.postcode-api.nl:

{
  "city": "Goes",
  "housenumber": "190",
  "houseletter": "F",
  "housenumberaddition": "3015",
  "municipality": "Goes",
  "postcode": "4462CB",
  "province": "Zeeland",
  "street": "Beukenstraat",
  "location": {
    "rd": [
      51998.091,
      390393.977
    ],
    "wgs84": [
      51.49314796497575,
      3.903961211877206
    ]
  }
}

Response Structure

The DirectMatch API returns an address object with the following fields:

city: The city name
housenumber: The house number
housenumberaddition: The house number addition (if present)
municipality: The municipality name
postcode: The postcode
province: The province
street: The street name
location: Location data in two coordinate systems:
rd: Dutch National Triangulation coordinates [x, y]
wgs84: WGS84 coordinates [latitude, longitude]

Error Handling

When no match is found, the API returns a 404 Not Found status:

HTTP Request:

GET /v1/directmatch/nl/1234XX/999
Headers: Authorization: Bearer $YOUR_API_KEY

HTTP Response:

Status: 404 Not Found

When to Use DirectMatch?

Use the DirectMatch API when:

You already have the exact postcode and house number
You don't need progressive search functionality
You want to quickly and efficiently validate or complete an address
You want to enrich address data with coordinates and municipality information

For situations where the user needs to enter or search for an address step by step, use the Autocomplete API.

Practical Example

A common use of DirectMatch is to validate and complete user input in a form:

async function validateAddress(postcode, housenumber, addition = null) {
    const apiKey = 'YOUR_TOKEN';
    let url = `https://api.postcode-api.nl/v1/directmatch/nl/${postcode}/${housenumber}`;
    if (addition) {
        url += `/${addition}`;
    }
    const response = await fetch(url, {
        headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Accept': 'application/json'
        }
    });
    if (response.ok) {
        const address = await response.json();
        document.getElementById('street').value = address.street;
        document.getElementById('city').value = address.city;
        document.getElementById('municipality').value = address.municipality;
        document.getElementById('province').value = address.province;
        return true;
    } else if (response.status === 404) {
        alert('Address not found. Please check postcode and house number.');
        return false;
    } else {
        console.error('API error:', response.status);
        return false;
    }
}

validateAddress('3811BN', '26');

Note: it is not recommended to use the above JavaScript code in your frontend. This should be done on the backend (server side).

Differences with Autocomplete API

Feature	DirectMatch	Autocomplete
Input required	Postcode + house number	Free text search
Context IDs	Not needed	Required for drill-down
Session ID	Not required	X-AutocompleteSessionId required
Use case	Address validation/completion	Address search/selection
Response	Direct address object	Suggestions list → address object