API REFERENCE

API Documentation

Integrate the GeoPin geolocation engine into your application. Upload a street photo and receive GPS coordinates.

Base URL https://geopin.nl

# Quick Start

Get your API key from your account page and send your first request:

curl

curl -X POST https://geopin.nl/api/geolocate \
  -H "X-API-Key: sk_geopin_your_key" \
  -F "image=@photo.jpg"

# Authentication

All requests to /api/geolocate require an API key in the X-API-Key header.

Find your API key on your account page. Never share your key publicly.

# Rate Limits

Plan	Searches / month	Result
Free	3	Location within ~500m
Starter	10	Exact GPS coordinates
Pro	150	Exact GPS coordinates
Business	1,000	Exact GPS coordinates

# Endpoints

POST /api/geolocate

Geolocate a street photo and receive GPS coordinates.

Headers

`X-API-Key`	required	Your API key
`Content-Type`	automatic	multipart/form-data

Body multipart/form-data

image required Image file (JPG, PNG or WebP)

Example response 200 OK

JSON

{
  "search_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location": {
    "lat": 52.21987,
    "lon": 6.89350,
    "confidence": 0.847,
    "heading": 142.5
  },
  "pano_id": "CAoSLEFGMVFp...",
  "server_time": 1.243,
  "usage": {
    "plan": "pro",
    "used": 42,
    "limit": 150
  }
}

Error codes

`400`	No image provided
`401`	Invalid or missing API key
`402`	Monthly limit reached
`429`	Too many requests
`503`	Service temporarily unavailable

GET /api/stats

Returns the current status of the GeoPin index.

No authentication required.

Example response 200 OK

JSON

{
  "total_indexed_images": 112885,
  "coverage": "Enschede (pilot)",
  "last_updated": "2026-03-22T10:00:00.000Z"
}

GET /api/auth/me

Retrieve your account details and current usage.

Headers

Authorization required Bearer <auth_token>

Example response 200 OK

JSON

{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "Jane Smith",
    "plan": "pro",
    "apiKey": "sk_geopin_abc123...",
    "usage": 42
  }
}

# Code Examples

Python

import requests

API_KEY = "sk_geopin_your_key"

with open("photo.jpg", "rb") as f:
    resp = requests.post(
        "https://geopin.nl/api/geolocate",
        headers={"X-API-Key": API_KEY},
        files={"image": f},
    )

data = resp.json()
loc = data["location"]
print(f"Location: {loc['lat']}, {loc['lon']}")
print(f"Confidence: {loc['confidence']:.1%}")

JavaScript / Node.js

JavaScript

const form = new FormData();
form.append("image", fileInput.files[0]);

const res = await fetch("https://geopin.nl/api/geolocate", {
  method: "POST",
  headers: { "X-API-Key": "sk_geopin_your_key" },
  body: form,
});

const { location } = await res.json();
console.log(`Location: ${location.lat}, ${location.lon}`);

# Response Fields

Field	Type	Description
`location.lat`	float	Latitude (WGS84)
`location.lon`	float	Longitude (WGS84)
`location.confidence`	float	Confidence score (0–1)
`location.heading`	float	Estimated viewing direction in degrees (0–360)
`pano_id`	string	Matched panorama ID
`server_time`	float	Processing time in seconds
`search_id`	string	Unique search ID