API Reference - Georaf

The Georaf REST API does everything the website does, over HTTP. Convert files between formats, run health checks, auto-fix problems, manage embeds, all from your own backend.

Base URL

https://api.georaf.com

Authentication

All API requests require an API key, passed as a bearer token in the Authorization header:

curl https://api.georaf.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

You can generate API keys in Settings → API Keys on your dashboard. The API is available on the Pro and Team plans. See Plans & limits.

A note on file uploads

Most endpoints work with files you’ve already uploaded. Upload references use the upload:// scheme:

{
  "source": "upload://amazon_reserves.zip",
  "target": "geojson"
}

For Shapefiles, upload the zipped bundle (the .shp plus all its sibling files), not just the .shp alone. The bundle is what the format actually requires. See Convert a file for the full list of supported formats.

Rate limits

API requests are subject to the same monthly usage limits as the website (conversions, health checks, etc.) plus an additional rate limit of 60 requests per minute per API key. Burst above that returns a 429 Too Many Requests with a Retry-After header.

Errors

Errors follow standard HTTP status codes with a JSON body explaining what went wrong:

{
  "detail": "File exceeds plan size limit (25 MB).",
  "code": "file_too_large"
}

Common codes:

HTTP	Code	What it means
400	`invalid_format`	The source file format couldn’t be detected.
401	`unauthorized`	API key missing or invalid.
403	`plan_required`	This endpoint isn’t available on your current plan.
413	`file_too_large`	File exceeds the per-file size cap for your plan.
429	`rate_limited`	Too many requests. Back off and retry.
500	`internal_error`	Something broke on our side. We log every 500 and investigate.

Endpoints

Every endpoint, request schema, and response shape is in the endpoints reference (generated from the live OpenAPI spec, always in sync with what production accepts).

​Base URL

​Authentication

​A note on file uploads

​Rate limits

​Errors

​Endpoints