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

Vijf 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

postcodehuisnummerhuislettertoevoeging
GET/postcodes

Postcode autocomplete (returns all postcodes matching prefix)

q (4+ digits)limit

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
});
Static Maps
Binnenkort beschikbaar

Statische Kaartafbeeldingen

Genereer statische kaartafbeeldingen met markers, paden en polygonen voor gebruik in e-mails, PDF's en websites.

Deze functie is momenteel in ontwikkeling. De documentatie hieronder toont de geplande API.

Static Map Endpoint

Genereer kaartafbeeldingen:

GET /map.{format}

URL Parameters

  • centerCoördinaten: lat,lon (bijv. 52.37,4.89)
  • zoomZoomniveau 1-20
  • sizeAfmetingen: breedte×hoogte (bijv. 600x400)
  • scaleRetina schaal: 1 of 2 (optioneel)
  • markersMarkers: lat,lon,kleur,label|...
  • keyJe volledige API key (gx_live_xxx)

Voorbeeld Request

GET /map.png?center=52.3676,4.9041
&zoom=14
&size=600x400
&markers=52.3676,4.9041,red,A
&key=gx_live_yourkey

Retourneert een PNG afbeelding van de kaart met een rode marker op de opgegeven locatie.

Ondersteunde Overlays

Markers

lat,lon,color,label

Kleuren: red, blue, green, orange, purple

Paths

color:width|lat,lon|...

Lijnen tussen punten

Polygons

stroke:fill:width|...

Gevulde gebieden

Circles

lat,lon,radius,stroke,fill

Straal in meters

Geavanceerde Voorbeelden

Meerdere Markers

/map.png?center=52.37,4.90&zoom=13&size=600x400
&markers=52.3676,4.9041,red,A|52.3702,4.8952,blue,B|52.3589,4.8810,green,C
&key=gx_live_yourkey

Meerdere markers gescheiden door | (pipe). Elke marker: lat,lon,kleur,label

Route / Pad

/map.png?center=52.37,4.90&zoom=14&size=600x400
&path=blue:3|52.3676,4.9041|52.3702,4.8952|52.3589,4.8810
&key=gx_live_yourkey

Pad formaat: kleur:dikte|lat,lon|lat,lon|... Punten verbonden met lijn

Polygoon / Gebied

/map.png?center=52.37,4.90&zoom=14&size=600x400
&polygon=blue:%233b82f680:2|52.368,4.900|52.372,4.905|52.368,4.910|52.364,4.905
&key=gx_live_yourkey

Polygoon formaat: randkleur:vulkleur:dikte|lat,lon|... Laatste punt verbindt automatisch met eerste

Cirkel / Radius

/map.png?center=52.37,4.90&zoom=14&size=600x400
&circle=52.3676,4.9041,500,blue,%233b82f680
&key=gx_live_yourkey

Cirkel formaat: lat,lon,straal(m),randkleur,vulkleur - Straal in meters

Gecombineerd Voorbeeld

/map.png?center=52.37,4.90&zoom=13&size=800x600&scale=2
&markers=52.3676,4.9041,red,Start|52.3589,4.8810,green,End
&path=blue:3|52.3676,4.9041|52.3702,4.8952|52.3589,4.8810
&circle=52.3676,4.9041,200,orange,%23f9731680
&key=gx_live_yourkey

Retina (@2x) kaart met start/eind markers, route pad, en service radius cirkel

Let op: Hex kleuren moeten URL-encoded zijn: # wordt %23 (bijv. %233b82f680 voor #3b82f680). De pipe | kan ook encoded worden als %7C.

Limieten per Plan

LimietFreeStarterBusiness+
Max afmetingen800×8002048×20482048×2048
Max overlays1050100
Retina schaal@1x@2x@2x
FormatenPNGPNG, JPG, WebPPNG, JPG, WebP
Playground

URL Builder

Bouw interactief je static map URL en bekijk een preview

Centrum

Klik op de kaart om het centrum te selecteren

Zoom

Zoomniveau van 1 (wereld) tot 20 (gebouw)

11420

Afmetingen

Breedte en hoogte in pixels (max 2048)

API Key

Enter your API key for live preview

Markers

Voeg markers toe aan de kaart

Klik op de kaart om centrum te selecteren

Klik op de kaart om centrum te selecteren

Gegenereerde URL:
https://api.georex.nl/map.png?center=52.3676%2C4.9041&zoom=14&size=600x400&key=YOUR_API_KEY

Note: Enter your API key above to see a live preview of the static map.

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.

Cookie-instellingen

Wij gebruiken optionele analytische cookies om onze website te verbeteren. Deze cookies worden alleen geplaatst met uw expliciete toestemming. Meer informatie