API Documentation

Bouw met GeoRex

Integreer Nederlandse adres autocompletion in minuten. Eenvoudige REST API, uitgebreide documentatie, en kant-en-klare code voorbeelden.

Snel Starten

In 3 stappen aan de slag met GeoRex

1

API Key aanvragen

Maak een gratis account aan en ontvang direct je API key.

2

Integreer de API

Gebruik onze REST endpoints met je favoriete programmeertaal.

3

Live!

Geniet van razendsnelle adres autocompletion in je applicatie.

Base URL

Alle API verzoeken naar:

https://api.georex.nl

API Endpoints

Vier krachtige endpoints voor al je geocoding behoeften

GET/autocomplete

Real-time address suggestions as users type

q (query)limitbboxlang
GET/geocode

Convert address to coordinates

q (address)limitlang
GET/reverse

Convert coordinates to address

latlonlang
GET/address

Lookup address by postcode + house number

postcodehuisnummer

Code Voorbeelden

Kopieer en plak - direct aan de slag

// Get token from your backend (keeps API key secret)
let token = await fetch('/api/georex-token')
.then(r => r.json()).then(d => d.token);
 
// Use token in API requests
const response = await fetch(
`https://api.georex.nl/autocomplete?q=damrak&token=${token}`
);
const data = await response.json();
console.log(data.features);
 
// Refresh token every 9 minutes (before 10 min expiry)
setInterval(async () => {
token = await fetch('/api/georex-token')
.then(r => r.json()).then(d => d.token);
}, 9 * 60 * 1000);
Response Format

GeoJSON Response

Alle responses volgen het GeoJSON standaard formaat met uitgebreide adres properties.

  • Coördinaten in WGS84 formaat
  • Volledige adres componenten
  • Type indicatie (straat, stad, etc.)
  • Bounding box voor kaart zoom
{
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [4.8951679, 52.3702157]
},
"properties": {
"osm_id": 271110189,
"osm_type": "R",
"name": "Amsterdam",
"city": "Amsterdam",
"state": "Noord-Holland",
"country": "Nederland",
"countrycode": "NL",
"type": "city",
"extent": [4.72, 52.43, 5.07, 52.27]
}
}]
}
# Step 1: Get token (only endpoint using X-API-Key)
curl -X POST -H "X-API-Key: gx_live_your_key" \
  "https://api.georex.nl/api/token"
# Response: {"token": "grx_...", "expires_in": 600}

# Step 2: Use token in ALL API requests
curl "https://api.georex.nl/autocomplete?q=amsterdam&token=TOKEN"
curl "https://api.georex.nl/geocode?q=Dam+1&token=TOKEN"
curl "https://api.georex.nl/address?postcode=1012AB&token=TOKEN"

# Refresh token every 9 minutes (before 10 min expiry)
Authenticatie

Token-Based Authenticatie

POST naar /api/token met je API key in de X-API-Key header om een token te krijgen. Gebruik dit token in alle API requests als ?token= parameter. Tokens zijn 10 minuten geldig.

Krijg je API Key
Tile Server

Kaart Tiles

Naast de geocoding API bieden we ook een tile server voor kaartweergave.

Tiles Base URL

Vector tiles endpoint:

https://tiles.georex.nl

Tile URL Formaat

https://tiles.georex.nl/{style}/{z}/{x}/{y}.pbf
  • {style} - Kaartstijl (bijv. basic, bright)
  • {z} - Zoom niveau (0-20)
  • {x} - X tile coördinaat
  • {y} - Y tile coördinaat

MapLibre GL JS Voorbeeld

const map = new maplibregl.Map({
container: 'map',
style: 'https://tiles.georex.nl/styles/basic/style.json',
center: [4.9, 52.37],
zoom: 10
});
Rate Limits

Rate Limiting

Om eerlijk gebruik te garanderen, passen we rate limits toe op API verzoeken.

Free

60verzoeken / minuut
1,000lookups / maand

Starter

300verzoeken / minuut
10,000lookups / maand

Professional

600verzoeken / minuut
100,000lookups / maand

Enterprise

3,000verzoeken / minuut
Onbeperktlookups / maand

Rate Limit Headers

Elke API response bevat headers met informatie over je huidige rate limit status:

X-RateLimit-Limit: 200X-RateLimit-Remaining: 195X-RateLimit-Reset: 1704067200
Error Handling

Error Responses

De API retourneert consistente error responses in JSON formaat.

400

Bad Request

Ongeldige request parameters

{
"error": "Bad Request",
"message": "Missing required parameter: q"
}
401

Unauthorized

Ontbrekend of ongeldig token

{
"error": "Unauthorized",
"message": "Invalid or expired token"
}
403

Forbidden

Geen toegang tot deze resource

{
"error": "Forbidden",
"message": "API key does not have access to this endpoint"
}
429

Too Many Requests

Rate limit of quota overschreden

{
"error": "rate_limited",
"message": "Hourly rate limit exceeded. Please slow down.",
"limit": 500,
"remaining": 0,
"retry_after": 1847,
"upgrade": "https://georex.nl/pricing",
"docs": "https://georex.nl/docs#rate-limits"
}
500

Internal Server Error

Server fout - neem contact op als dit aanhoudt

{
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}

Voorbeeld: Error Handling

Implementeer robuuste error handling met automatische retry voor rate limits.

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(url, options);
 
// Success - return data
if (response.ok) {
return await response.json();
}
 
// Handle different error codes
switch (response.status) {
case 401:
// Token expired - refresh and retry
const newToken = await refreshToken();
url = url.replace(/token=[^&]+/, `token=${newToken}`);
continue;
 
case 429:
// Rate limited - wait and retry
const data = await response.json();
const waitTime = data.retry_after || 60;
console.log(`Rate limited. Waiting ${waitTime}s...`);
await new Promise(r => setTimeout(r, waitTime * 1000));
continue;
 
case 400:
// Bad request - don't retry, fix the request
throw new Error(`Bad request: ${(await response.json()).message}`);
 
case 500:
// Server error - retry with backoff
await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
continue;
 
default:
throw new Error(`Request failed: ${response.status}`);
}
}
throw new Error('Max retries exceeded');
}
 
// Usage
try {
const results = await fetchWithRetry(
`https://api.georex.nl/autocomplete?q=amsterdam&token=${token}`
);
console.log(results.features);
} catch (error) {
console.error('Failed:', error.message);
}

Klaar om te beginnen?

Start gratis met 1.000 lookups per maand. Geen creditcard nodig.