{
  "openapi": "3.1.0",
  "info": {
    "title": "x402 Geocoding API",
    "description": "A pay-per-request geocoding API for AI agents and developers. Forward and reverse geocoding for $0.001 USDC per request via x402 V2. No API key or subscription required.",
    "version": "2.0.0",
    "contact": {
      "email": "feedback@example.com"
    },
    "x-guidance": "Use GET /api/geocode?q=ADDRESS for forward geocoding (address to coordinates). Use GET /api/reverse?lat=LAT&lon=LON for reverse geocoding (coordinates to address). Both endpoints require x402 V2 payment of $0.001 USDC on Base mainnet. Without payment, the server responds with HTTP 402 and a PAYMENT-REQUIRED header containing the payment challenge."
  },
  "servers": [
    {
      "url": "https://geocoding-x402.royaldemocracy.workers.dev",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/geocode": {
      "get": {
        "operationId": "forwardGeocode",
        "summary": "Forward geocoding - Convert address to coordinates",
        "description": "Convert a street address, city, landmark, or location string into geographic coordinates (latitude and longitude). Requires x402 V2 payment of $0.001 USDC on Base mainnet.",
        "tags": ["Geocoding"],
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "x-bazaar": {
          "info": {
            "input": {
              "type": "http",
              "method": "GET",
              "queryParams": { "q": "1600 Pennsylvania Avenue NW, Washington, DC" }
            },
            "output": {
              "type": "json",
              "example": { "lat": 38.8976763, "lon": -77.0365298, "display_name": "1600 Pennsylvania Ave NW, Washington, DC 20500, USA" }
            }
          },
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "input": {
                "type": "object",
                "properties": {
                  "type": { "type": "string", "const": "http" },
                  "method": { "type": "string", "enum": ["GET"] },
                  "queryParams": {
                    "type": "object",
                    "properties": { "q": { "type": "string", "description": "Address or location string to geocode" } },
                    "required": ["q"]
                  }
                },
                "required": ["type", "method"]
              },
              "output": {
                "type": "object",
                "properties": {
                  "type": { "type": "string" },
                  "example": { "type": "object" }
                },
                "required": ["type"]
              }
            },
            "required": ["input"]
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 1 },
            "description": "The address or location string to geocode.",
            "example": "1600 Pennsylvania Avenue NW, Washington, DC"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful geocoding result with payment settled.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded settlement response",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lat": { "type": "number" },
                    "lon": { "type": "number" },
                    "display_name": { "type": "string" },
                    "payer": { "type": "string" },
                    "settlement": {
                      "type": "object",
                      "properties": {
                        "success": { "type": "boolean" },
                        "transaction": { "type": "string" },
                        "network": { "type": "string" },
                        "payer": { "type": "string" }
                      }
                    }
                  },
                  "required": ["lat", "lon", "display_name"]
                },
                "example": {
                  "lat": 38.8976763,
                  "lon": -77.0365298,
                  "display_name": "1600 Pennsylvania Ave NW, Washington, DC 20500, USA"
                }
              }
            }
          },
          "400": {
            "description": "Missing required query parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "error": { "type": "string" } }
                },
                "example": { "error": "Missing ?q= parameter" }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded PaymentRequired object",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "x402Version": { "type": "number" },
                    "error": { "type": "string" },
                    "resource": { "type": "object" },
                    "accepts": { "type": "array" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Location not found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "error": { "type": "string" } }
                },
                "example": { "error": "Location not found" }
              }
            }
          }
        }
      }
    },
    "/api/reverse": {
      "get": {
        "operationId": "reverseGeocode",
        "summary": "Reverse geocoding - Convert coordinates to address",
        "description": "Convert latitude and longitude coordinates into a human-readable address. Requires x402 V2 payment of $0.001 USDC on Base mainnet.",
        "tags": ["Geocoding"],
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }
        },
        "x-bazaar": {
          "info": {
            "input": {
              "type": "http",
              "method": "GET",
              "queryParams": { "lat": "40.7128", "lon": "-74.006" }
            },
            "output": {
              "type": "json",
              "example": { "address": "New York, NY, USA", "place": "New York" }
            }
          },
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "input": {
                "type": "object",
                "properties": {
                  "type": { "type": "string", "const": "http" },
                  "method": { "type": "string", "enum": ["GET"] },
                  "queryParams": {
                    "type": "object",
                    "properties": {
                      "lat": { "type": "number", "description": "Latitude coordinate" },
                      "lon": { "type": "number", "description": "Longitude coordinate" }
                    },
                    "required": ["lat", "lon"]
                  }
                },
                "required": ["type", "method"]
              },
              "output": {
                "type": "object",
                "properties": {
                  "type": { "type": "string" },
                  "example": { "type": "object" }
                },
                "required": ["type"]
              }
            },
            "required": ["input"]
          }
        },
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": { "type": "number" },
            "description": "Latitude coordinate.",
            "example": 40.7128
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": { "type": "number" },
            "description": "Longitude coordinate.",
            "example": -74.006
          }
        ],
        "responses": {
          "200": {
            "description": "Successful reverse geocoding result with payment settled.",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded settlement response",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "address": { "type": "string" },
                    "place": { "type": "string" },
                    "payer": { "type": "string" },
                    "settlement": {
                      "type": "object",
                      "properties": {
                        "success": { "type": "boolean" },
                        "transaction": { "type": "string" },
                        "network": { "type": "string" },
                        "payer": { "type": "string" }
                      }
                    }
                  },
                  "required": ["address", "place"]
                },
                "example": {
                  "address": "New York, NY, USA",
                  "place": "New York"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid lat/lon parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "error": { "type": "string" } }
                },
                "example": { "error": "Missing ?lat= and ?lon=" }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded PaymentRequired object",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "x402Version": { "type": "number" },
                    "error": { "type": "string" },
                    "resource": { "type": "object" },
                    "accepts": { "type": "array" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Could not reverse geocode coordinates.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "error": { "type": "string" } }
                },
                "example": { "error": "Could not reverse geocode" }
              }
            }
          }
        }
      }
    }
  }
}