API Documentatie
Versie 1 — Stabiel
Snel aan de slag
- 1 Maak een account aan en genereer een API-sleutel via je account.
- 2 Kies je tier: Gratis (500 calls/mnd, geen creditcard) of koop credits voor Basis/Pro (€0,01 per credit).
-
3
Voeg de
Authorization: Bearer <sleutel>header toe aan elk verzoek. -
4
Stuur een GET-verzoek naar
/api/v1/addressmet 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 |
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
/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 |
|---|---|---|
| straat | string | Officiële straatnaam uit de BAG |
| huisnummer | integer | Huisnummer |
| toevoeging | string|null | Huisnummertoevoeging (null als niet van toepassing) |
| postcode | string | Postcode in formaat DDDDLL |
| woonplaats | string | Officiële BAG-woonplaatsnaam |
| gemeente | string | Gemeentenaam |
| provincie | string | Provincienaam |
| land | string | Altijd "Nederland" |
| lat | float|null | Breedtegraad (WGS84) — altijd null op de gratis tier |
| lng | float|null | Lengtegraad (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.