API Documentatie

Versie 1 — Stabiel

Snel aan de slag

  1. 1 Maak een account aan en genereer een API-sleutel via je account.
  2. 2 Kies je tier: Gratis (500 calls/mnd, geen creditcard) of koop credits voor Basis/Pro (€0,01 per credit).
  3. 3 Voeg de Authorization: Bearer <sleutel> header toe aan elk verzoek.
  4. 4 Stuur een GET-verzoek naar /api/v1/address met postcode en huisnummer.

Tiers en limieten

Elke API-sleutel heeft een tier. De tier bepaalt de rate limit, het maandelijkse volume en welke velden in de response zitten.

Tier Kosten Rate limit Volume Coördinaten SLA
Gratis €0 10 req/min 500 calls/maand Nee (altijd null) Geen
Basis 1 credit/call 50 req/min Onbeperkt Ja Best effort
Pro 2 credits/call 100 req/min Onbeperkt Ja 99,9% uptime
Gratis tier: de velden lat en lng zijn altijd null, ongeacht of de BAG-coördinaten beschikbaar zijn. De maandelijkse teller reset op de eerste van iedere kalendermaand om 00:05 (Amsterdam). Bij het bereiken van de 500-call limiet retourneert de API een 402 free_tier_limit_reached.

Endpoint

GET /api/v1/address

Retourneert een volledig, gevalideerd adresobject op basis van postcode en huisnummer. Authenticatie via Authorization: Bearer <sleutel> header (Sanctum PAT).

Parameters

Parameter Type Vereist Omschrijving
postcode string Verplicht Nederlandse postcode, bijv. 1011PN
huisnummer integer Verplicht Huisnummer, bijv. 1
toevoeging string Optioneel Huisnummertoevoeging, bijv. A of bis

Response schema

Bij een succesvolle aanvraag (HTTP 200) retourneert Geoto het volgende JSON-object:

{
  "straat":      "Damrak",
  "huisnummer":  1,
  "toevoeging":  null,
  "postcode":    "1011PN",
  "woonplaats":  "Amsterdam",
  "gemeente":    "Amsterdam",
  "provincie":   "Noord-Holland",
  "land":        "Nederland",
  "lat":         52.37403,
  "lng":         4.89538
}
Veld Type Omschrijving
straatstringOfficiële straatnaam uit de BAG
huisnummerintegerHuisnummer
toevoegingstring|nullHuisnummertoevoeging (null als niet van toepassing)
postcodestringPostcode in formaat DDDDLL
woonplaatsstringOfficiële BAG-woonplaatsnaam
gemeentestringGemeentenaam
provinciestringProvincienaam
landstringAltijd "Nederland"
latfloat|nullBreedtegraad (WGS84) — altijd null op de gratis tier
lngfloat|nullLengtegraad (WGS84) — altijd null op de gratis tier

Foutcodes

Code Status Wanneer
401 Unauthorized Geen of ongeldige API-sleutel meegegeven
402 Payment Required Tegoed is op (insufficient_balance), of de gratis maandlimiet is bereikt (free_tier_limit_reached)
404 Not Found Postcode + huisnummer combinatie niet gevonden in de BAG
422 Unprocessable Entity Ontbrekende of ongeldige parameters (bijv. postcode ontbreekt)
429 Too Many Requests Rate limit overschreden (10/min Gratis, 50/min Basis, 100/min Pro)

Codevoorbeelden

curl -G https://geoto.nl/api/v1/address \
  -H "Authorization: Bearer {jouw-sleutel}" \
  -d "postcode=1011PN" \
  -d "huisnummer=1"
<?php

$client = new \GuzzleHttp\Client();

$response = $client->get('https://geoto.nl/api/v1/address', [
    'headers' => [
        'Authorization' => 'Bearer {jouw-sleutel}',
        'Accept'        => 'application/json',
    ],
    'query' => [
        'postcode'   => '1011PN',
        'huisnummer' => 1,
    ],
]);

$adres = json_decode($response->getBody(), true);
echo $adres['straat'] . ' ' . $adres['huisnummer'];
// Damrak 1
import requests

response = requests.get(
    "https://geoto.nl/api/v1/address",
    headers={
        "Authorization": "Bearer {jouw-sleutel}",
        "Accept": "application/json",
    },
    params={
        "postcode": "1011PN",
        "huisnummer": 1,
    },
)
response.raise_for_status()

adres = response.json()
print(adres["straat"], adres["huisnummer"])
# Damrak 1
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://geoto.nl/api/v1/address?postcode=1011PN&huisnummer=1"
    ))
    .header("Authorization", "Bearer {jouw-sleutel}")
    .header("Accept", "application/json")
    .GET()
    .build();

HttpResponse<String> response = client.send(
    request,
    HttpResponse.BodyHandlers.ofString()
);

System.out.println(response.body());
// {"straat":"Damrak","huisnummer":1,...}
using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "{jouw-sleutel}");
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var response = await client.GetAsync(
    "https://geoto.nl/api/v1/address?postcode=1011PN&huisnummer=1");
response.EnsureSuccessStatusCode();

var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);
// {"straat":"Damrak","huisnummer":1,...}

Testpostcodes

Gebruik de onderstaande postcode/huisnummer combinaties om je integratie te testen. Deze adressen zijn gevalideerde BAG-entries die altijd een correct resultaat geven.

Postcode Huisnummer Adres Gemeente
1011PN 1 Damrak 1 Amsterdam
2511CR 1 Binnenhof 1 Den Haag
3012CN 1 Coolsingel 1 Rotterdam
3511XJ 1 Domplein 1 Utrecht

Sandbox

Met een test sleutel (geo_test_...) kun je de API testen zonder credits te verbruiken. Sandbox-calls retourneren altijd dezelfde fictieve respons, ongeacht de opgegeven postcode.

Kenmerken van sandbox-sleutels:

  • Prefix geo_test_ — nooit inzetbaar in productie
  • Geen credits verbruikt, geen maandlimiet
  • Altijd volledige respons met coördinaten (ook zonder betaald account)
  • Rate limit 50 req/min (gelijk aan Basis-tier)
  • Fictieve data: straat Teststraat, woonplaats Teststad, Amsterdam-coördinaten

Maak test sleutels aan via je dashboard.

Voorbeeld met een test sleutel:

curl "https://geoto.nl/api/v1/address?postcode=1234AB&huisnummer=1" \
  -H "Authorization: Bearer geo_test_jouwSleutelHier"

Respons is altijd identiek aan productie — veilig om mee te testen in CI/CD pipelines.

Interactieve API

Verken en test alle endpoints direct in de browser. Voer je API-sleutel in en verstuur verzoeken zonder extra tooling. Gebruik een sandbox-sleutel om te testen zonder kosten.