{
  "openapi": "3.0.3",
  "info": {
    "title": "Urania Geo API",
    "description": "Free RESTful API for global geographical data — countries, states, cities, coordinates, timezones, currencies, and more.",
    "version": "1.0.0",
    "contact": {
      "name": "Urania Support",
      "url": "https://urania.obilodev.com"
    }
  },
  "servers": [
    {
      "url": "{baseUrl}/api/v1",
      "description": "Production / Custom",
      "variables": {
        "baseUrl": {
          "default": "https://urania.obilodev.com",
          "description": "Your Urania instance URL"
        }
      }
    }
  ],
  "security": [
    { "ApiKeyHeader": [] }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "Your Urania API key. Generate one from the dashboard."
      }
    },
    "schemas": {
      "Country": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string", "example": "Nigeria" },
          "iso2": { "type": "string", "example": "NG" },
          "iso3": { "type": "string", "example": "NGA" },
          "phoneCode": { "type": "string", "example": "+234" },
          "currency": { "type": "string", "example": "NGN" },
          "flag": { "type": "string" },
          "flagEmoji": { "type": "string", "example": "🇳🇬" },
          "timezone": { "type": "string", "example": "Africa/Lagos" },
          "continent": { "type": "string", "example": "Africa" },
          "region": { "type": "string", "example": "West Africa" },
          "lat": { "type": "number", "format": "float" },
          "lng": { "type": "number", "format": "float" }
        }
      },
      "State": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string", "example": "Lagos" },
          "country_id": { "type": "integer" },
          "country_code": { "type": "string", "example": "NG" },
          "state_code": { "type": "string", "example": "LA" },
          "type": { "type": "string" },
          "lat": { "type": "number", "format": "float" },
          "lng": { "type": "number", "format": "float" }
        }
      },
      "City": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string", "example": "Ikeja" },
          "country_id": { "type": "integer" },
          "state_id": { "type": "integer" },
          "lat": { "type": "number", "format": "float" },
          "lng": { "type": "number", "format": "float" },
          "population": { "type": "integer" },
          "timezone": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "API key missing" }
        }
      }
    }
  },
  "paths": {
    "/countries": {
      "get": {
        "summary": "List all countries",
        "operationId": "listCountries",
        "parameters": [
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "example": "name" } }
        ],
        "responses": {
          "200": { "description": "Paginated list of countries" }
        }
      }
    },
    "/countries/{id}": {
      "get": {
        "summary": "Get a single country",
        "operationId": "getCountry",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Country details" },
          "404": { "description": "Country not found" }
        }
      }
    },
    "/countries/{id}/states": {
      "get": {
        "summary": "List states for a country",
        "operationId": "listCountryStates",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Paginated list of states" }
        }
      }
    },
    "/states": {
      "get": {
        "summary": "List all states",
        "operationId": "listStates",
        "parameters": [
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": { "description": "Paginated list of states" }
        }
      }
    },
    "/states/{id}": {
      "get": {
        "summary": "Get a single state",
        "operationId": "getState",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "State details" },
          "404": { "description": "State not found" }
        }
      }
    },
    "/states/{id}/cities": {
      "get": {
        "summary": "List cities for a state",
        "operationId": "listStateCities",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Paginated list of cities" }
        }
      }
    },
    "/cities": {
      "get": {
        "summary": "List all cities",
        "operationId": "listCities",
        "parameters": [
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": { "description": "Paginated list of cities" }
        }
      }
    },
    "/cities/nearby": {
      "get": {
        "summary": "Find cities near coordinates",
        "operationId": "nearbyCities",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "format": "float" } },
          { "name": "lng", "in": "query", "required": true, "schema": { "type": "number", "format": "float" } },
          { "name": "radius", "in": "query", "schema": { "type": "integer", "default": 50, "description": "Radius in km" } }
        ],
        "responses": {
          "200": { "description": "List of nearby cities" }
        }
      }
    },
    "/cities/{id}": {
      "get": {
        "summary": "Get a single city",
        "operationId": "getCity",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "City details" },
          "404": { "description": "City not found" }
        }
      }
    }
  },
  "tags": [
    { "name": "Countries", "description": "Country-level geographical data" },
    { "name": "States", "description": "State/province-level data" },
    { "name": "Cities", "description": "City-level data with coordinates" }
  ]
}