# GEOG — Full API Reference > Vector tile provider SaaS platform with authentication, organization management, and usage-based billing. ## Overview GEOG provides vector tile serving and places search via a REST API. All requests require a Bearer JWT token in the Authorization header. Base URL: https://api.geog.dev ## Authentication API tokens are self-issued JWTs signed with RSA keys. Tokens are created in the GEOG console and include permission scopes. ### Token Format JWT claims: - sub: Token ID (tok_*) - org_id: Organization ID - scope: Granted permission scopes (e.g., "tiles:read") - token_type: "api_token" - aud: "https://api.geog.dev" - iss: "https://api.geog.dev" ### Usage ``` Authorization: Bearer ``` ## Endpoints ### Health Check ``` GET / ``` Returns "GEOG API" as plain text. No authentication required. ### JWKS ``` GET /.well-known/jwks.json ``` Returns the JSON Web Key Set for JWT validation. No authentication required. Response is cached (Cache-Control: public, max-age=3600). --- ### Vector Tiles ``` GET /v1/tiles/{tileset}/{z}/{x}/{y}.{ext} Authorization: Bearer Scope: tiles:read ``` Parameters: - tileset (string): Tileset identifier (e.g., "twin-cities") - z (integer, 0-22): Zoom level - x (integer): Tile column - y (integer): Tile row - ext (string): "mvt" or "pbf" Response: Binary protobuf data (application/x-protobuf) Status codes: - 200: Tile data returned - 204: Tile exists but is empty - 400: Invalid tile extension - 401: Unauthorized - 404: Tile not found or outside valid zoom range Example: ```bash curl "https://api.geog.dev/v1/tiles/twin-cities/14/4680/6125.mvt" \ -H "Authorization: Bearer YOUR_TOKEN" ``` --- ### Places Search ``` POST /v1/places/search Authorization: Bearer Content-Type: application/json Scope: places:read ``` Request body: ```json { "query": "coffee shop", "location": { "lat": 37.7749, "lng": -122.4194 }, "radius": 5000, "limit": 5 } ``` Response: ```json { "results": [ { "id": "place_123", "score": 0.95, "name": "Blue Bottle Coffee", "category": "cafe", "location": { "lat": 37.7849, "lng": -122.4088 }, "distance": 1250, "address": "66 Mint St, San Francisco, CA 94103", "rating": 4.5 } ], "total": 245, "executionTime": 42, "metadata": { "shardsSearched": 3, "cacheHit": false } } ``` --- ### Token Exchange ``` POST /v1/auth/token Authorization: Bearer Content-Type: application/json ``` Exchange a long-lived API token for a short-lived access token. Use this to avoid exposing long-lived credentials in frontend applications. Request body: ```json { "ttl": 3600, "scope": "tiles:read" } ``` Parameters: - ttl (integer, 1–14400): Token lifetime in seconds. Default: 3600 (1 hour). Max: 14400 (4 hours). - scope (string, optional): Subset of parent token scopes. Defaults to all parent scopes. Response: ```json { "access_token": "eyJhbGc...", "token_type": "Bearer", "expires_in": 3600, "expires_at": "2025-12-29T15:30:00Z", "scope": "tiles:read" } ``` --- ### Billing All billing endpoints require the `billing:manage` scope. #### Get Billing Overview ``` GET /v1/billing Authorization: Bearer ``` Returns billing overview including customer info, invoices, and usage summary. #### Set Up Customer ``` POST /v1/billing/setup-customer Authorization: Bearer Content-Type: application/json ``` ```json { "email": "billing@example.com", "name": "My Organization" } ``` #### Set Up Payment Method ``` POST /v1/billing/setup-payment-method Authorization: Bearer Content-Type: application/json ``` ```json { "successUrl": "https://geog.dev/console/org/billing?success=true", "cancelUrl": "https://geog.dev/console/org/billing?canceled=true" } ``` Returns a Stripe Checkout URL for adding a payment method. #### Get Usage Metrics ``` GET /v1/billing/usage?startDate=2025-01-01T00:00:00Z&endDate=2025-01-31T23:59:59Z Authorization: Bearer ``` #### Get Billing Summary ``` GET /v1/billing/summary Authorization: Bearer ``` Returns customer, subscription, invoices, and usage totals. #### Create Customer Portal Session ``` POST /v1/billing/create-portal Authorization: Bearer Content-Type: application/json ``` ```json { "returnUrl": "https://geog.dev/console/org/billing" } ``` Returns a Stripe Customer Portal URL for self-service billing management. ## Token Scopes | Scope | Description | | --- | --- | | tiles:read | Read vector tiles | | places:read | Search places | | billing:manage | Manage organization billing | | admin:access | Access admin endpoints | ## Rate Limits Free tier organizations have daily rate limits: - Vector tiles: 2,000 requests/day - Places API: 500 requests/day Limits reset at 00:00 UTC daily. Rate limit headers are endpoint-specific on free tier responses: - X-RateLimit-Tiles-Limit / X-RateLimit-Places-Limit: Daily limit - X-RateLimit-Tiles-Remaining / X-RateLimit-Places-Remaining: Requests remaining - X-RateLimit-Tiles-Reset / X-RateLimit-Places-Reset: Reset timestamp (ISO 8601) Paid plans have no rate limits. ## Error Format All errors return JSON: ```json { "success": false, "error": "Error type", "message": "Human-readable description", "code": "MACHINE_READABLE_CODE" } ``` Common status codes: - 400: Bad request (invalid parameters) - 401: Unauthorized (missing or invalid token) - 403: Forbidden (insufficient scopes) - 404: Not found - 429: Rate limit exceeded (free tier) - 500: Internal server error ## Resources - Documentation: https://geog.dev/docs - OpenAPI spec: https://geog.dev/openapi.yaml - Console: https://geog.dev/console