BAG Address API Documentatie

Deze API biedt toegang tot BAG (Basisregistratie Adressen en Gebouwen) adresgegevens. Er zijn twee manieren om de data te benaderen:

Authenticatie

Alle API-verzoeken vereisen authenticatie met een API-sleutel die moet worden opgenomen in de Authorization header.

Headers

Authorization: Bearer YOUR_API_KEY

Neem contact op met de beheerder om een API-sleutel aan te vragen.

Voorbeeld authenticatie

// JavaScript voorbeeld met authenticatie
fetch('/api/addresses/lookup?postcode=1234AB&huisnummer=10', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

REST API

Adres Opzoeken

Zoek adressen op basis van postcode en huisnummer.

Endpoint

GET /api/addresses/lookup?postcode={postcode}&huisnummer={huisnummer}

Parameters

Parameter Type Verplicht Beschrijving
postcode string Ja Nederlandse postcode (bijv. "1234AB" of "1234 AB")
huisnummer integer Ja Huisnummer (bijv. 10)

Voorbeeld Aanvraag

GET /api/addresses/lookup?postcode=1234AB&huisnummer=10

Voorbeeld Respons

{
  "success": true,
  "count": 2,
  "data": [
    {
      "nummeraanduiding_id": "0123456789",
      "postcode": "1234AB",
      "huisnummer": 10,
      "huisletter": null,
      "huisnummertoevoeging": null,
      "straat": "Voorbeeldstraat",
      "woonplaats": "Amsterdam",
      "oppervlakte": 120,
      "gebruiksdoel": ["woonfunctie"],
      "oorspronkelijkBouwjaar": 1980,
      "latitude": 52.123456,
      "longitude": 4.123456,
      "rd_x": 12345.678,
      "rd_y": 12345.678,
      "is_ligplaats": false,
      "is_standplaats": false,
      "is_verblijfsobject": true,
      "status": "in gebruik",
      "nummeraanduiding_status": "naamgeving uitgegeven",
      "object_status": "in gebruik",
      "adres_status": "in gebruik",
      "is_bruikbaar": true,
      "begindatum": "1980-01-01",
      "einddatum": null,
      "object_id": "NL.IMBAG.VERBLIJFSOBJECT.0123456789"
    },
    {
      "nummeraanduiding_id": "0123456790",
      "postcode": "1234AB",
      "huisnummer": 10,
      "huisletter": "A",
      "huisnummertoevoeging": null,
      "straat": "Voorbeeldstraat",
      "woonplaats": "Amsterdam",
      "oppervlakte": 90,
      "gebruiksdoel": ["woonfunctie"],
      "oorspronkelijkBouwjaar": 1980,
      "latitude": 52.123457,
      "longitude": 4.123457,
      "rd_x": 12345.679,
      "rd_y": 12345.679,
      "is_ligplaats": false,
      "is_standplaats": false,
      "is_verblijfsobject": true,
      "status": "in gebruik",
      "nummeraanduiding_status": "naamgeving uitgegeven",
      "object_status": "in gebruik",
      "adres_status": "in gebruik",
      "is_bruikbaar": true,
      "begindatum": "1980-01-01",
      "einddatum": null,
      "object_id": "NL.IMBAG.VERBLIJFSOBJECT.0123456790"
    }
  ]
}

GraphQL API

Bulk Adressen Ophalen

Haal meerdere adressen op met verschillende filteropties.

Endpoint

POST /api/graphql

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-apollo-operation-name: YourOperationName

Voorbeeld Aanvraag

{
  "query": "query BulkAddressQuery($input: BulkAddressInput!) { bulkAddresses(input: $input) { data { nummeraanduiding_id postcode huisnummer huisletter huisnummertoevoeging straat woonplaats } meta { total page limit totalPages } } }",
  "variables": {
    "input": {
      "postcodeRange": {
        "from": "1234AA",
        "to": "1234ZZ"
      },
      "limit": 100,
      "offset": 0
    }
  }
}

Parameters

Parameter Type Verplicht Beschrijving
postcodes string[] Nee Lijst van postcodes om op te filteren (exacte match)
postcodeRange object Nee Bereik van postcodes (inclusief)
city string Nee Woonplaats (gedeeltelijke match)
straat string Nee Straatnaam (gedeeltelijke match)
minBouwjaar integer Nee Minimum bouwjaar
maxBouwjaar integer Nee Maximum bouwjaar
gebruiksdoel string Nee Gebruiksdoel (bijv. "woonfunctie")
limit integer Nee Maximum aantal resultaten (standaard: 1000, max: 5000)
offset integer Nee Paginering offset (standaard: 0)

Rate Limits

Om eerlijk gebruik van de API te garanderen, gelden de volgende rate limits:

Als je deze limieten overschrijdt, ontvang je een 429 (Too Many Requests) response met een Retry-After header.

Foutafhandeling

De API retourneert standaard HTTP-statuscodes:

Voorbeeld Foutresponsen

Authenticatie Fout (401)
{
  "success": false,
  "error": "Unauthorized",
  "message": "Valid API key required"
}
CSRF Beschermingsfout (GraphQL)
{
  "errors": [
    {
      "message": "This operation has been blocked as a potential Cross-Site Request Forgery (CSRF). Please either specify a 'content-type' header or provide a non-empty value for one of the following headers: x-apollo-operation-name, apollo-require-preflight",
      "extensions": {
        "code": "BAD_REQUEST"
      }
    }
  ]
}
Rate Limit Fout (429)
{
  "success": false,
  "error": "Too many requests",
  "message": "Rate limit exceeded. Please try again later."
}

Voorbeeld Code

JavaScript

// REST API voorbeeld
fetch('/api/addresses/lookup?postcode=1234AB&huisnummer=10', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

// GraphQL API voorbeeld
fetch('/api/graphql', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-apollo-operation-name': 'BulkAddressQuery'
  },
  body: JSON.stringify({
    query: `query BulkAddressQuery($input: BulkAddressInput!) {
      bulkAddresses(input: $input) {
        data {
          nummeraanduiding_id
          postcode
          huisnummer
          straat
          woonplaats
        }
        meta {
          total
          page
          limit
          totalPages
        }
      }
    }`,
    variables: {
      input: {
        city: "Amsterdam",
        limit: 10
      }
    }
  })
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Python

import requests

# REST API voorbeeld
headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('https://jouw-domein.nl/api/addresses/lookup', 
    params={
        'postcode': '1234AB',
        'huisnummer': 10
    },
    headers=headers
)
data = response.json()
print(data)

# GraphQL API voorbeeld
query = """
query BulkAddressQuery($input: BulkAddressInput!) {
  bulkAddresses(input: $input) {
    data {
      nummeraanduiding_id
      postcode
      huisnummer
      straat
      woonplaats
    }
    meta {
      total
      page
      limit
      totalPages
    }
  }
}
"""

variables = {
    'input': {
        'city': 'Amsterdam',
        'limit': 10
    }
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-apollo-operation-name': 'BulkAddressQuery'
}

response = requests.post('https://jouw-domein.nl/api/graphql',
    json={
        'query': query,
        'variables': variables
    },
    headers=headers
)
data = response.json()
print(data)

PHP

<?php
// REST API voorbeeld
$opts = [
    'http' => [
        'header' => "Authorization: Bearer YOUR_API_KEY
"
    ]
];
$context = stream_context_create($opts);

$url = 'https://jouw-domein.nl/api/addresses/lookup?postcode=1234AB&huisnummer=10';
$response = file_get_contents($url, false, $context);
$data = json_decode($response, true);
print_r($data);

// GraphQL API voorbeeld
$url = 'https://jouw-domein.nl/api/graphql';
$query = '
query BulkAddressQuery($input: BulkAddressInput!) {
  bulkAddresses(input: $input) {
    data {
      nummeraanduiding_id
      postcode
      huisnummer
      straat
      woonplaats
    }
    meta {
      total
      page
      limit
      totalPages
    }
  }
}
';

$variables = [
  'input' => [
    'city' => 'Amsterdam',
    'limit' => 10
  ]
];

$data = [
  'query' => $query,
  'variables' => $variables
];

$options = [
  'http' => [
    'header' => "Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-apollo-operation-name: BulkAddressQuery
",
    'method' => 'POST',
    'content' => json_encode($data)
  ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$result = json_decode($response, true);
print_r($result);
?>

Testen met Postman

REST API Testen

  1. Open Postman en maak een nieuw request
  2. Stel de request methode in op GET
  3. Voer de URL in: http://localhost:3000/api/addresses/lookup?postcode=1234AB&huisnummer=10
  4. Ga naar de Authorization tab
  5. Selecteer Bearer Token uit de Type dropdown
  6. Voer je API sleutel in in het Token veld
  7. Klik op Send om het request uit te voeren

GraphQL API Testen

  1. Open Postman en maak een nieuw request
  2. Stel de request methode in op POST
  3. Voer de URL in: http://localhost:3000/api/graphql
  4. Ga naar de Headers tab en voeg toe:
  5. Ga naar de Authorization tab
  6. Ga naar de Body tab 
    {
  "query": query BulkAddressQuery($input: BulkAddressInput!) {
  bulkAddresses(input: $input) {
    data {
      nummeraanduiding_id
      postcode
      huisnummer
      huisletter
      huisnummertoevoeging
      straat
      woonplaats
    }
    meta {
      total
      page
      limit
      totalPages
    }
  }
}
  "variables": {
    {
  "input": {
    "postcodeRange": {
      "from": "1234AA",
      "to": "1234ZZ"
    },
    "limit": 100,
    "offset": 0
  }
}
  
}
  7. Klik op Send om het request uit te voeren