API Overview

The Geog API provides geospatial services including places search and vector tile serving. Built on Hono and deployed as Cloudflare Workers, it offers high performance and global distribution.

Base URL

https://api.geog.dev

Authentication

The API supports two authentication methods:

1. API Key Authentication

Add your API key to the request headers:

curl -X POST "https://api.geog.dev/v1/places/search" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"location": {"lat": 37.7749, "lon": -122.4194}, "radius": 5000, "query": "coffee shop"}'

2. JWT Bearer Token

For user-authenticated requests:

curl -X POST "https://api.geog.dev/v1/places/search" \
  -H "Authorization: Bearer jwt-token-here" \
  -H "Content-Type: application/json" \
  -d '{"location": {"lat": 37.7749, "lon": -122.4194}, "radius": 5000, "query": "coffee shop"}'

Rate Limiting

API requests are rate-limited per API key:

Default Limit: 1,000 requests per hour
Rate Limit Headers: Included in all responses
Token Bucket: Refill-based limiting system

Response Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

API Endpoints

Places API

Search Places

POST/v1/places/search

Hybrid text and geographic search across the places database.

Request Body (JSON):

location (required) - Geographic center point: { "lat": number, "lon": number }
radius (optional) - Search radius in meters (1-100000, default: 5000)
query (optional) - Text search query (e.g., "coffee shops")
categories (optional) - Filter by categories: ["restaurant", "cafe"]
limit (optional) - Results limit (1-1000, default: 20). Values above 1000 are capped at 1000.
offset (optional) - Pagination offset (default: 0)
weights (optional) - Hybrid scoring weights: { "text": 0.6, "geo": 0.4 }

Place Details

GET/v1/places/{id}

Get detailed information about a specific place.

Vector Tiles API

Get Tile

GET/tiles/{z}/{x}/{y}.mvt

Retrieve Mapbox Vector Tiles for mapping applications.

Parameters:

z - Zoom level (0-14)
x - Tile X coordinate
y - Tile Y coordinate

Response Format

All API responses use JSON format with consistent structure:

Success Response

{
  "results": [
    {
      "id": "8529a1003ffffff-abc123def",
      "score": 0.95,
      "name": "Blue Bottle Coffee",
      "category": "cafe",
      "categories": ["cafe", "coffee_shop"],
      "location": { "lat": 37.7749, "lon": -122.4194 },
      "distance": 1250,
      "address": "315 Linden St, San Francisco, CA 94102",
      "city": "San Francisco",
      "region": "California",
      "brand": "Blue Bottle Coffee",
      "sourceId": "way/123456789",
      "confidence": 0.98
    }
  ],
  "total": 100,
  "executionTime": 45,
  "queryStats": {
    "pruningEfficiency": 0.85,
    "cellsSearched": 3
  }
}

Error Response

{
  "error": "invalid_request",
  "message": "Missing required parameter: location"
}

HTTP Status Codes

200 - Success
400 - Bad Request (invalid parameters)
401 - Unauthorized (invalid API key)
403 - Forbidden (insufficient permissions)
404 - Not Found
429 - Rate Limit Exceeded
500 - Internal Server Error

Error Codes

Authentication Errors

INVALID_API_KEY - API key is invalid or expired
MISSING_AUTH - No authentication provided
INSUFFICIENT_PERMISSIONS - API key lacks required permissions

Rate Limiting Errors

RATE_LIMIT_EXCEEDED - Request rate limit exceeded

Request Errors

INVALID_REQUEST - Malformed request parameters
MISSING_PARAMETER - Required parameter missing
INVALID_PARAMETER - Parameter value is invalid

Resource Errors

NOT_FOUND - Requested resource not found
RESOURCE_UNAVAILABLE - Resource temporarily unavailable