API Best Practices

Guidelines for building reliable, performant integrations with the Geog API.

Request/Response Examples

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

# Response
{
  "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
  }
}

Vector Tiles

# Request
curl -H "Authorization: Bearer your-api-key" \
  "https://api.geog.dev/tiles/10/163/395.mvt" \
  --output tile.mvt

# Response: Binary Mapbox Vector Tile data

cURL Examples

# Set API key as environment variable
export GEOG_API_KEY="your-api-key-here"

# Search places
curl -X POST "https://api.geog.dev/v1/places/search" \
  -H "Authorization: Bearer $GEOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location": {"lat": 40.7128, "lng": -74.0060}, "radius": 3000, "query": "restaurant"}'

# Get vector tile
curl -H "Authorization: Bearer $GEOG_API_KEY" \
  "https://api.geog.dev/tiles/12/1024/1024.mvt" \
  --output tile.mvt

Performance

  • Use appropriate limit parameters to avoid large responses
  • Implement client-side caching for repeated requests
  • Use vector tiles for map rendering instead of individual place requests

Error Handling

  • Always check for error responses and handle them gracefully
  • Implement exponential backoff for rate limit errors
  • Handle network timeouts gracefully

See the Error Handling Guide for detailed patterns and code examples.

Security

  • Never expose API keys in client-side code
  • Use environment variables for API key storage
  • Rotate API keys regularly
  • Use Token Exchange for frontend applications

Rate Limit Management

  • Monitor rate limit headers in responses
  • Implement request queuing for high-volume applications
  • Consider upgrading API key limits for production use

See Also