KurdGeo Documentation

Welcome to KurdGeo! This guide will help you make your first API request in under 5 minutes.

Sign up at /register to get a free trial with 1,000 requests per day.

KurdGeo uses Bearer token authentication. Pass your API key in the Authorization header on every request:

Authorization: Bearer kg_live_abc123def456...

You can also use the query parameter ?api_key= for browser-based requests where setting headers is difficult.

Your API key is shown only once at creation. Store it securely — it cannot be recovered. If lost, rotate the key to generate a new one.

Make a routing request between two coordinates:

curl https://api.kurdgeo.space/api/v1/gateway/routing/route/v1/driving/ \
  "44.009,36.193;44.012,36.195" \
  -H "Authorization: Bearer kg_live_..."

Try it in the interactive playground with multi-language code generation.

The Routing API is powered by OSRM (Open Source Routing Machine). All endpoints are accessed through the gateway proxy at /api/gateway/routing/.

Available profiles: driving, walking, cycling.

Coordinates are passed as semicolon-separated longitude,latitude pairs.

Returns the fastest route between two or more coordinates.

GET /api/gateway/routing/route/v1/driving/{coordinates}

Response includes distance (meters), duration (seconds), and encoded geometry.

Finds the nearest snapped point on the road network for each coordinate.

GET /api/gateway/routing/nearest/v1/driving/{coordinates}?number=3

Computes durations/distances between all pairs of given coordinates.

GET /api/gateway/routing/table/v1/driving/{coordinates}

Solves the Traveling Salesman Problem for the given coordinates.

GET /api/gateway/routing/trip/v1/driving/{coordinates}

Map-matches GPS traces to the road network.

GET /api/gateway/routing/match/v1/driving/{coordinates}

Raster and vector tiles are served from self-hosted OSM. Use the tile URL template in your map library (MapLibre, Leaflet, etc.):

https://api.kurdgeo.space/api/v1/gateway/maps/tiles/kurdistan/{z}/{x}/{y}.pmtiles

Available style JSONs for MapLibre GL:

https://api.kurdgeo.space/api/v1/gateway/maps/style/light.json
https://api.kurdgeo.space/api/v1/gateway/maps/style/dark.json
https://api.kurdgeo.space/api/v1/gateway/maps/style/satellite.json

Sprite sheets and glyph fonts (PBF) are served alongside the tile service. Style JSONs reference them automatically.

Create and manage API keys from the dashboard. Each key belongs to a project and inherits that project's rate limits.

Keys are stored as HMAC-SHA256 hashes — the plaintext is shown only once at creation.

All keys currently have full access to all gateway endpoints. Per-key scopes (routing-only, tiles-only, etc.) are on the roadmap.

Each plan has configurable limits:

• RPS — requests per second (sliding window)
• Daily quota — requests per UTC day
• Monthly quota — requests per calendar month

When limits are exceeded, the API returns HTTP 429 with a QUOTA_EXCEEDED error code.

Rotating a key generates a new secret and immediately invalidates the old one. This is useful if a key is compromised or you want to cycle keys periodically.

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Your daily quota has been exceeded.",
    "contact": "enterprise@kurdgeo.site",
    "upgradeUrl": "https://app.kurdgeo.site/pricing"
  },
  "meta": { "requestId": "..." }
}

Common error codes: INVALID_API_KEY, QUOTA_EXCEEDED, RATE_LIMITED, UPSTREAM_ERROR, VALIDATION_ERROR.

All successful responses are wrapped in a standard envelope:

{
  "data": { ... },
  "meta": { "requestId": "..." }
}

Every gateway response includes these headers:

• X-RateLimit-Limit — max requests per second
• X-RateLimit-Remaining — remaining requests in current window
• X-RateLimit-Reset — epoch seconds until window resets
• X-Daily-Quota-Remaining — remaining daily quota