Rate Limiting

This document describes the rate limiting policies and usage tracking mechanisms for the Geog API.

Overview

The Geog API implements daily rate limits for organizations on the free tier, enforced via Cloudflare Durable Objects. Rate limits ensure fair usage and protect the infrastructure while providing a generous free tier for evaluation and development.

Free Tier Rate Limiting

Overview

Organizations without billing enabled are subject to daily rate limits enforced using Cloudflare Durable Objects. This provides a cost-effective free tier (~$0.02/month per organization) with generous limits for evaluation and development.

Rate Limit Flow

sequenceDiagram
    participant Client
    participant API as Geog API

    Client->>API: Request with Bearer token
    Note over API: Check organization billing tier
    alt Paid tier
        API->>Client: 200 Response (no rate limit headers)
    else Free tier — under limit
        API->>Client: 200 Response + X-RateLimit headers
    else Free tier — limit exceeded
        API->>Client: 429 Too Many Requests
    end

Free Tier Limits

Endpoint Type	Daily Limit	Description
Vector Tiles	2,000	Vector tile requests per day
Places API	1,000	Places API requests per day

Key Features:

Limits reset daily at 00:00 UTC
One Durable Object per organization tracks both limits
Limits are enforced per organization (not per token)
Upgrading to a paid plan removes all rate limits
Independent counters for tiles and places

Rate Limit Headers (Free Tier)

All free tier requests include rate limit headers:

X-RateLimit-Tiles-Limit: 2000
X-RateLimit-Tiles-Remaining: 1999
X-RateLimit-Tiles-Reset: 2024-01-02T00:00:00.000Z

X-RateLimit-Places-Limit: 1000
X-RateLimit-Places-Remaining: 999
X-RateLimit-Places-Reset: 2024-01-02T00:00:00.000Z

Header	Description
`X-RateLimit-<Type>-Limit`	Maximum requests per day
`X-RateLimit-<Type>-Remaining`	Requests remaining today
`X-RateLimit-<Type>-Reset`	ISO 8601 timestamp of next reset

Free Tier 429 Response

When free tier limits are exceeded:

HTTP 429 Too Many Requests:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your free tier limit of 2,000 vector tile requests per day. Your limit will reset at 2024-01-02T00:00:00.000Z. Upgrade to a paid plan to remove these limits and continue using the API.",
  "endpoint": "tiles",
  "limit": 2000,
  "reset": "2024-01-02T00:00:00.000Z"
}

Checking Current Usage

Endpoint:

GET/v1/rate-limit/usage

Authentication: Required (Bearer token)

Response:

{
  "organizationId": "org-abc123",
  "usage": {
    "tiles": {
      "limit": 2000,
      "current": 750,
      "remaining": 1250
    },
    "places": {
      "limit": 1000,
      "current": 45,
      "remaining": 955
    },
    "resetAt": 1704153600000
  }
}

Upgrading to Remove Limits

Enable billing to remove all rate limits:

Navigate to your organization's billing settings
Add a payment method
Enable billing
Rate limits are immediately lifted

Paid tier organizations are never rate limited and do not receive rate limit headers.