# x402 Geocoding API

A pay-per-request geocoding API designed for AI agents and developers.

## Capabilities

- Forward geocoding (address to coordinates)
- Reverse geocoding (coordinates to address)
- Structured JSON output
- x402 V2 payment protocol
- $0.001 USDC per successful request
- No API key required
- No subscription required

## Documentation

- Homepage: https://geocoding-x402.royaldemocracy.workers.dev/
- Documentation: https://geocoding-x402.royaldemocracy.workers.dev/docs
- OpenAPI: https://geocoding-x402.royaldemocracy.workers.dev/openapi.json
- x402 service descriptor: https://geocoding-x402.royaldemocracy.workers.dev/.well-known/x402
- Forward geocoding guide: https://geocoding-x402.royaldemocracy.workers.dev/geocoding-api
- Reverse geocoding guide: https://geocoding-x402.royaldemocracy.workers.dev/reverse-geocoding-api
- x402 geocoding guide: https://geocoding-x402.royaldemocracy.workers.dev/x402-geocoding-api

## Forward Geocoding

Endpoint: GET /api/geocode?q=ADDRESS

Example:

curl "https://geocoding-x402.royaldemocracy.workers.dev/api/geocode?q=1600 Pennsylvania Ave NW, Washington, DC 20500"

Response (after x402 payment):

{
  "lat": 38.8976763,
  "lon": -77.0365298,
  "display_name": "1600 Pennsylvania Ave NW, Washington, DC 20500, USA"
}

## Reverse Geocoding

Endpoint: GET /api/reverse?lat=LAT&lon=LON

Example:

curl "https://geocoding-x402.royaldemocracy.workers.dev/api/reverse?lat=40.7128&lon=-74.006"

Response (after x402 payment):

{
  "address": "New York, NY, USA",
  "place": "New York"
}

## Payment

Payment is handled via the x402 V2 protocol. Each successful request costs $0.001 USDC on Base mainnet (eip155:8453). The server responds with HTTP 402 when payment is required. Include a signed x402 payment in the PAYMENT-SIGNATURE header to complete the request.

## Network

Base mainnet. Chain ID: 8453. CAIP-2: eip155:8453.

## Pricing

$0.001 USDC per request. No subscriptions. No API keys.