API Documentation | Free World Geographical Data Bank

Getting Started

Urania provides a strict, RESTful JSON API for global geographical data. The base URL for all v1 endpoints is:

https://urania.obilodev.com/api/v1

All responses are enveloped in a consistent JSON structure containing a data array or object, and a meta block containing pagination and data provenance information.

Authentication

Every request requires an X-API-Key HTTP header. API keys are long-lived and scoped to your project. There are no rotating tokens or OAuth flows.

curl "https://urania.obilodev.com/api/v1/countries" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Global Query Parameters

All list endpoints support pagination, search, and filtering via standard query parameters:

Parameter	Type	Description
`page`	int	Page number for paginated results (default 1).
`per_page`	int	Number of results per page (max 100).
`name`	string	Case-insensitive substring search across names.
`sort`	string	Sort by field. Prefix with `-` for descending.

API Endpoints

Below is the complete list of available resources, showing the HTTP method, endpoint route, and a sample response for each.

GET /v1/countries

Retrieve a list of all countries available in the dataset.

// Example Response

{
    "code": 200,
    "data": {
        "countries": [
            "Andorra",
            "United Arab Emirates",
            "Afghanistan",
            "Antigua and Barbuda",
            "Anguilla"
        ]
    },
    "status": "success"
}

GET /v1/countries/{country}

Retrieve detailed information about a specific country available in the dataset.

// Example Response

{
    "code": 200,
    "data": {
        "country": "Andorra",
        "iso2": "AD",
        "iso3": "AND",
        "phoneCode": "376",
        "currency": "EUR",
        "timezone": null
    },
    "status": "success"
}

GET /v1/countries/{country}/states

Fetch states within a specific country.

// Example Response

{
    "code": 200,
    "data": {
        "country": "Andorra",
        "states": [
            "Canillo",
            "Encamp",
            "La Massana",
            "Ordino",
            "Sant Juli\u00e0 de Loria"
        ]
    },
    "status": "success"
}

GET /v1/states

Fetch a list of all states in the dataset.

// Example Response

{
    "code": 200,
    "data": {
        "states": [
            "Canillo",
            "Encamp",
            "La Massana",
            "Ordino",
            "Sant Juli\u00e0 de Loria"
        ]
    },
    "status": "success"
}

GET /v1/states/{state}/cities

Retrieve all cities within a given state.

// Example Response

{
    "code": 200,
    "data": {
        "state": "Canillo",
        "cities": [
            "Canillo"
        ]
    },
    "status": "success"
}

GET /v1/cities

Fetch a list of all cities in the dataset.

// Example Response

{
    "code": 200,
    "data": {
        "cities": [
            "Canillo",
            "Encamp",
            "la Massana",
            "Ordino",
            "Sant Juli\u00e0 de L\u00f2ria"
        ]
    },
    "status": "success"
}

GET /v1/cities/{city}

Retrieve information about a specific city available in the dataset.

// Example Response

{
    "code": 200,
    "data": {
        "name": "Canillo",
        "lat": "42.5676000",
        "lng": "1.5975600",
        "stateId": 5,
        "countryId": 1
    },
    "status": "success"
}

GET /v1/cities/nearby?lat=6.524&lng=3.379&radius=50

Find cities near a given coordinate using the Haversine formula.

// Example Response

{
    "code": 200,
    "data": [
        {
            "name": "Ikeja",
            "lat": 6.6059,
            "lng": 3.3491,
            "distance_km": 9.65
        }
    ],
    "status": "success"
}

Geospatial Nearby Search

Find cities near a specific latitude and longitude using the Haversine formula. Results are automatically sorted by proximity and include a distance_km attribute.

Parameter	Required	Description
`lat`	Yes	Latitude (-90.0 to 90.0)
`lng`	Yes	Longitude (-180.0 to 180.0)
`radius`	No	Search radius in kilometers (default 50, max 500).

Rate Limits & Quotas

Your API key tracks usage across all endpoints. If you exceed limits, the API returns a 429 Too Many Requests response.

Metric	Limit	Scope
Burst limit	1,000 req / minute	Per API key
Daily quota (Free)	5,000 req / day	Per API key
Monthly quota (Free)	100,000 req / month	Per API key

Multi-Language Examples

You can consume the API using any HTTP client. Below are common examples across different environments:

                    Python (Requests)
                

import requests

url = "https://urania.obilodev.com/api/v1/countries"
headers = {"X-API-Key": "YOUR_API_KEY"}
params = {"name": "nigeria"}

r = requests.get(url, headers=headers, params=params)
print(r.json())

                    Node.js (Fetch)
                

const fetch = require('node-fetch');

const res = await fetch(
  'https://urania.obilodev.com/api/v1/countries?name=nigeria',
  { headers: { 'X-API-Key': 'YOUR_KEY' } }
);

const { data } = await res.json();
console.log(data);

                    PHP (Guzzle)
                

$client = new \GuzzleHttp\Client();

$res = $client->get('https://urania.obilodev.com/api/v1/countries', [
    'headers' => ['X-API-Key' => 'YOUR_KEY'],
    'query'   => ['name' => 'nigeria']
]);

$data = json_decode($res->getBody(), true);

                    Go (net/http)
                

req, _ := http.NewRequest(
    "GET", 
    "https://urania.obilodev.com/api/v1/countries?name=nigeria", 
    nil,
)
req.Header.Set("X-API-Key", "YOUR_KEY")

res, _ := http.DefaultClient.Do(req)

Need native SDKs?

Download typed libraries for JS, Python, and PHP directly from your dashboard.

Go to Dashboard