World API Reference

The World Data API provides a consistent way to access global geographical and demographic data. Use our endpoints to build location-aware applications with ease.

terminal Base API URL
https://api.orbisregistry.rainbowwinglabs.com/world
Example Request
GET /api/v1/public/countries
GET /api/v1/monitoring/health

Health Check

Monitor the health status of our API services. Returns a 200 OK if all systems are operational. 

{
  "status": "healthy",
  "version": "1.0.0"
}

Authentication

All requests require an API key passed in the X-API-Key header. You can manage your keys in the developer dashboard.

warning Security Note

Never share your API keys or commit them to version control.

cURL Example
curl -H "X-API-Key: wd_live_..." \
  https://api.orbisregistry.rainbowwinglabs.com/world/api/v1/public/countries

Rate Limits

Limits are enforced per API key to ensure stability for all developers.

Plan Limit
Free Tier 60 req/min
Pro Tier 3,000 req/min
shutter_speed

Exceeding limits will return a 429 Too Many Requests response.

GET /api/v1/monitoring/ping

Ping

Verify API connectivity with a lightweight request. Use this for keep-alive or latency tests.

"pong"
GET /api/v1/public/countries

List Countries

Access our global database of countries. Filter and paginate results as needed.

Query Parameters

name Filter by name or ISO code
limit Default: 10
GET /api/v1/public/countries/count

Count Countries

Fetch the total number of records in the countries table.

GET /api/v1/public/states

List States

Fetch states and provinces. Highly recommended to filter by countryName for optimal performance.

Parameters

countryName Filter by parent country
GET /api/v1/public/states/count

Count States

Retrieve the total number of states/provinces globally.

GET /api/v1/public/cities

List Cities

Comprehensive list of cities worldwide. Filter results by state to narrow down your search.

Parameters

stateName Filter by state/province
GET /api/v1/public/cities/count

Count Cities

Get the total volume of city records available.

GET /api/v1/public/towns

List Towns

Retrieve a list of towns and small urban settlements.

GET /api/v1/public/towns/count

Count Towns

Get total number of town records.

GET /api/v1/public/villages

List Villages

Access data on rural settlements and villages globally.

GET /api/v1/public/villages/count

Count Villages

Get total number of village records.

GET /api/v1/public/hamlets

List Hamlets

Retrieve information about small hamlets and isolated dwellings.

GET /api/v1/public/hamlets/count

Count Hamlets

Get total number of hamlet records.