GeoPin biedt een eenvoudige REST API waarmee je een foto kunt indienen en een voorspelde locatie binnen Nederland terugkrijgt. Of je nu een intern verificatiehulpmiddel bouwt, een contentmanagementpipeline verrijkt, of locatiebewustzijn toevoegt aan een mobiele app, de integratie kost slechts enkele minuten. Deze gids behandelt authenticatie, je eerste verzoek, het verwerken van antwoorden en best practices voor productiegebruik.

Je API-sleutel verkrijgen

Elk verzoek aan de GeoPin API vereist een API-sleutel die wordt meegegeven in de Authorization-header. Je kunt een sleutel genereren vanuit je dashboard op geopin.nl/dashboard na het aanmaken van een account. Gratis accounts ontvangen 100 verzoeken per maand. Betaalde abonnementen bieden hogere limieten en prioriteitsverwerking.

Houd je API-sleutel geheim. Neem deze nooit op in client-side JavaScript dat naar eindgebruikers wordt verzonden. Als je vermoedt dat een sleutel is gecompromitteerd, trek deze dan onmiddellijk in via het dashboard en genereer een nieuwe.

Je eerste verzoek

Het kerneindpunt is POST /api/v1/geolocate. Je stuurt een afbeelding, en GeoPin retourneert een gerangschikte lijst van voorspelde locaties.

curl

curl -X POST https://api.geopin.nl/api/v1/geolocate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@photo.svg"

Python

import requests

API_KEY = "YOUR_API_KEY"
URL = "https://api.geopin.nl/api/v1/geolocate"

with open("photo.svg", "rb") as f:
    response = requests.post(
        URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"image": ("photo.svg", f, "image/jpeg")},
    )

data = response.json()
print(f"Top prediction: {data['results'][0]['latitude']}, "
      f"{data['results'][0]['longitude']}")
print(f"Confidence: {data['results'][0]['confidence']}")

JavaScript (Node.js)

import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const API_KEY = "YOUR_API_KEY";
const URL = "https://api.geopin.nl/api/v1/geolocate";

const form = new FormData();
form.append("image", fs.createReadStream("photo.svg"));

const response = await fetch(URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    ...form.getHeaders(),
  },
  body: form,
});

const data = await response.json();
console.log("Top prediction:", data.results[0]);

Het antwoord begrijpen

Een succesvol antwoord retourneert JSON met de volgende structuur:

{
  "request_id": "req_8f3a2b1c",
  "status": "success",
  "processing_time_ms": 1423,
  "results": [
    {
      "rank": 1,
      "latitude": 52.3676,
      "longitude": 4.9041,
      "confidence": 0.92,
      "radius_m": 150,
      "region": "Amsterdam",
      "province": "Noord-Holland"
    },
    {
      "rank": 2,
      "latitude": 52.3712,
      "longitude": 4.8952,
      "confidence": 0.78,
      "radius_m": 300,
      "region": "Amsterdam",
      "province": "Noord-Holland"
    }
  ]
}

Belangrijke velden om op te letten:

confidence is een float tussen 0 en 1. Waarden boven 0,85 duiden over het algemeen op voorspellingen met hoge betrouwbaarheid. Waarden onder 0,5 suggereren dat het model onzeker is, en je het resultaat met voorzichtigheid moet behandelen.
radius_m is de geschatte nauwkeurigheidsstraal in meters. Een kleinere straal betekent dat het model ruimtelijk nauwkeuriger is.
results bevat altijd maximaal vijf gerangschikte voorspellingen. Het retourneren van meerdere kandidaten stelt je in staat je eigen herrangschikkingslogica toe te passen als je applicatie extra context heeft, zoals een bekende stad of tijdzone.

Foutafhandeling

De API gebruikt standaard HTTP-statuscodes. Dit zijn de codes die je expliciet moet afhandelen:

Status	Betekenis	Actie
200	Succes	Verwerk de resultaten
400	Ongeldig verzoek (ontbrekende afbeelding, niet-ondersteund formaat)	Controleer je verzoekinhoud
401	Ongeldige of ontbrekende API-sleutel	Verifieer je sleutel
413	Afbeelding overschrijdt 20 MB-limiet	Verklein voor het uploaden
429	Snelheidslimiet overschreden	Wacht en probeer opnieuw
500	Interne serverfout	Probeer opnieuw met exponential backoff

Bij 429-antwoorden geeft de Retry-After-header aan hoeveel seconden je moet wachten voordat je opnieuw probeert. Een eenvoudige herhalingsstrategie in Python ziet er als volgt uit:

import time

def geolocate_with_retry(image_path, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"image": open(image_path, "rb")},
        )
        if response.status_code == 200:
            return response.json()
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 5))
            time.sleep(wait)
            continue
        response.raise_for_status()
    raise Exception("Max retries exceeded")

Batchverwerking

Als je veel afbeeldingen moet geolocaliseren, bijvoorbeeld het verwerken van een achterstand aan archieffoto’s, gebruik dan het batch-eindpunt POST /api/v1/geolocate/batch. Dit accepteert maximaal 50 afbeeldingen in een enkel verzoek en verwerkt ze parallel op ons GPU-cluster.

files = [
    ("images", (f"photo_{i}.svg", open(f"photo_{i}.jpg", "rb"), "image/jpeg"))
    for i in range(50)
]

response = requests.post(
    "https://api.geopin.nl/api/v1/geolocate/batch",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files=files,
)

for result in response.json()["results"]:
    print(f"{result['filename']}: {result['latitude']}, {result['longitude']}")

Batchverzoeken worden gefactureerd als een verzoek per afbeelding, maar profiteren van verminderde overhead en snellere totale verwerkingstijd in vergelijking met opeenvolgende individuele aanroepen.

Best practices

Beeldkwaliteit telt. Afbeeldingen met hogere resolutie en zichtbare herkenningspunten, straatnaamborden of onderscheidende architectuur leveren betere resultaten op. Bijgesneden close-ups van gezichten of generieke binnenscènes zullen resultaten met lage betrouwbaarheid opleveren omdat ze geografische context missen.

Verwijder EXIF-gegevens als privacy belangrijk is. GeoPin leest of bewaart geen EXIF GPS-tags van geüploade afbeeldingen. Onze geolocatie is puur visueel. Als je workflow gevoelige afbeeldingen omvat, verwijder dan metadata voor het uploaden als extra beveiligingslaag.

Cache resultaten aan je kant. Als je dezelfde afbeelding meer dan eens geolokaliseert, cache het resultaat dan lokaal in plaats van het opnieuw in te dienen. Dit bespaart zowel API-quotum als verwerkingstijd.

Gebruik betrouwbaarheidsdrempels. Niet elke afbeelding kan betrouwbaar worden gegeolocaliseerd. Bouw je applicatielogica zo dat het op een elegante manier omgaat met antwoorden met lage betrouwbaarheid. Je kunt bijvoorbeeld het resultaat met een disclaimer tonen wanneer de betrouwbaarheid tussen 0,5 en 0,85 ligt, en het resultaat volledig onderdrukken onder 0,5.

Gebruik uitsluitend HTTPS. Alle API-eindpunten vereisen TLS. Verzoeken via platte HTTP worden geweigerd. Dit zorgt ervoor dat je API-sleutel en beeldgegevens versleuteld zijn tijdens de overdracht.

Snelheidslimieten en prijzen

Abonnement	Maandelijkse verzoeken	Prijs
Trial	3	Gratis
Starter	100	EUR 19
Pro	500	EUR 99
Business	2.000	EUR 149

Alle abonnementen bieden toegang tot het batch-eindpunt, webhookmeldingen en volledige API-documentatie. Enterprise-abonnementen bieden daarnaast persoonlijke ondersteuning, aangepaste SLA’s en on-premises implementatieopties.

Wat komt er aan

We zijn actief bezig met het ontwikkelen van een WebSocket-eindpunt voor realtime videogeolocatie en een client-SDK voor Python en TypeScript die de REST API omhult met ingebouwde herhalingen, connection pooling en type-safe antwoordobjecten. Volg onze changelog op geopin.nl/changelog om op de hoogte te blijven.

Als je problemen tegenkomt tijdens de integratie, neem dan contact met ons op via support@geopin.nl of open een discussie in ons ontwikkelaarsforum. We reageren doorgaans binnen enkele uren op werkdagen.