API Documentation

Complete reference for the Bamwor REST API. Endpoints, parameters, authentication, rate limits, and response formats.

Base URL

https://bamwor.com/api/v1

Authentication

Include your API key in every request using one of these methods:

Header

X-API-Key: bw_live_your_key_here
# or
Authorization: Bearer bw_live_your_key_here

Anonymous requests (no key) are allowed with lower limits: 10/min, 100/day.

Rate Limits

Plan	Per minute	Per day	Price
Anonymous	10	100	Free (no key)
Free	30	1,000	$0
Pro	120	50,000	$29/mo
Enterprise	600	500,000	Custom

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Pagination

Paginated endpoints accept page and per_page query parameters. Default: page=1, per_page=25 (max 100).

Response format

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 261,
    "total_pages": 11
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-11T10:00:00.000Z",
    "cached": true
  }
}

Error Handling

Error response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Country \"xyz\" not found.",
    "status": 404
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-11T10:00:00.000Z"
  }
}

Status	Code	Description
400	`BAD_REQUEST`	Invalid parameters
401	`INVALID_API_KEY`	Invalid or missing API key
403	`API_KEY_DISABLED`	API key has been disabled
404	`NOT_FOUND`	Resource not found
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	Server error

Endpoint Reference

GET/api/v1/countries

Paginated list of all countries with basic stats.

Name	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 25, max: 100)
`region`	string	No	Filter by region slug (e.g. south-america)
`sort`	string	No	Sort by: name, population, area (default: name)

curl

curl -H "X-API-Key: bw_live_your_key" \
  "https://bamwor.com/api/v1/countries?sort=population&per_page=5"

Response

{
  "data": [
    {
      "iso_code": "CH",
      "names": { "en": "China", "es": "China", "pt": "China", "it": "Cina" },
      "slugs": { "en": "china", "es": "china", "pt": "china", "it": "cina" },
      "coordinates": { "latitude": 35.0, "longitude": 105.0 },
      "region": { "slug": "east-southeast-asia", "name": "East & Southeast Asia" },
      "population": 1416043270,
      "area_sq_km": 9596960,
      "category": "country"
    }, ...
  ],
  "pagination": { "page": 1, "per_page": 5, "total": 261, "total_pages": 53 }
}

GET/api/v1/countries/:slug

Full country detail with all statistics.

Name	Type	Required	Description
`slug`	string	Yes	Country slug in any language (e.g. argentina, japon, stati-uniti)

curl

curl -H "X-API-Key: bw_live_your_key" \
  https://bamwor.com/api/v1/countries/japan

Response

{
  "data": {
    "iso_code": "JA",
    "names": { "en": "Japan", "es": "Japón", "pt": "Japão", "it": "Giappone" },
    "stats": {
      "population": { "value": 123719238, "unit": null, "year": 2025, "source": "CIA World Factbook" },
      "area_sq_km": { "value": 377915, ... },
      "gdp_nominal": { "value": 4230862, ... },
      ...
    },
    "flag_url": "/flags/ja.png",
    "map_url": "/maps/ja.png"
  }
}

GET/api/v1/countries/:slug/cities

Paginated cities within a country.

Name	Type	Required	Description
`slug`	string	Yes	Country slug
`sort`	string	No	Sort by: population, name (default: population)
`min_population`	integer	No	Minimum population filter
`province`	string	No	Filter by province/admin1 name
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (max: 100)

curl

curl -H "X-API-Key: bw_live_your_key" \
  "https://bamwor.com/api/v1/countries/brazil/cities?min_population=500000"

Response

{
  "data": [
    {
      "id": 3448439,
      "names": { "en": "São Paulo", "es": "São Paulo", ... },
      "coordinates": { "latitude": -23.5475, "longitude": -46.6361 },
      "population": 11967825,
      "province": "São Paulo"
    }, ...
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 17 }
}

GET/api/v1/cities/:id

City detail by GeoNames ID.

Name	Type	Required	Description
`id`	integer	Yes	GeoNames ID (e.g. 3435910 for Buenos Aires)

curl

curl -H "X-API-Key: bw_live_your_key" \
  https://bamwor.com/api/v1/cities/3435910

Response

{
  "data": {
    "id": 3435910,
    "names": { "en": "Buenos Aires", ... },
    "coordinates": { "latitude": -34.6132, "longitude": -58.3772 },
    "population": 13076300,
    "elevation": 31,
    "timezone": "America/Argentina/Buenos_Aires",
    "province": "Buenos Aires F.D.",
    "country": { "name": "Argentina", "slug": "argentina", "iso_code": "AR" }
  }
}

GET/api/v1/cities/:id/nearby

Find cities near a given city using PostGIS radius search.

Name	Type	Required	Description
`id`	integer	Yes	Origin city GeoNames ID
`radius`	integer	No	Radius in km (default: 50, max: 200)
`limit`	integer	No	Max results (default: 10, max: 50)

curl

curl -H "X-API-Key: bw_live_your_key" \
  "https://bamwor.com/api/v1/cities/3435910/nearby?radius=100&limit=5"

Response

{
  "data": [
    {
      "id": 3432043,
      "names": { "en": "La Plata", ... },
      "coordinates": { "latitude": -34.9215, "longitude": -57.9545 },
      "population": 694167,
      "distance_km": 56.2
    }, ...
  ]
}

GET/api/v1/search

Search countries and cities by name in any of the 4 supported languages.

Name	Type	Required	Description
`q`	string	Yes	Search query (min 2 chars, max 100)
`type`	string	No	Filter: all, country, city (default: all)
`limit`	integer	No	Max results (default: 20, max: 50)

curl

curl -H "X-API-Key: bw_live_your_key" \
  "https://bamwor.com/api/v1/search?q=tokyo&type=city"

Response

{
  "data": [
    {
      "type": "city",
      "id": 1850147,
      "names": { "en": "Tokyo", "es": "Tokio", "pt": "Tóquio", "it": "Tokyo" },
      "coordinates": { "latitude": 35.6895, "longitude": 139.6917 },
      "population": 8336599,
      "country_code": "JA"
    }
  ]
}

GET/api/v1/rankings

List all available ranking metrics.

curl

curl -H "X-API-Key: bw_live_your_key" \
  https://bamwor.com/api/v1/rankings

Response

{
  "data": [
    { "slug": "population", "label": "Population", "url": "/api/v1/rankings/population" },
    { "slug": "area", "label": "Area (sq km)", "url": "/api/v1/rankings/area" },
    { "slug": "gdp", "label": "GDP (nominal)", "url": "/api/v1/rankings/gdp" },
    { "slug": "hdi", "label": "Human Development Index", "url": "/api/v1/rankings/hdi" },
    ...
  ]
}

GET/api/v1/rankings/:slug

Paginated country ranking by a specific metric.

Name	Type	Required	Description
`slug`	string	Yes	Metric: population, area, density, gdp, gdp-per-capita, hdi, life-expectancy
`region`	string	No	Filter by region slug
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (default: 50)

curl

curl -H "X-API-Key: bw_live_your_key" \
  "https://bamwor.com/api/v1/rankings/population?region=south-america&per_page=5"

Response

{
  "data": [
    {
      "rank": 1,
      "country": {
        "iso_code": "BR",
        "names": { "en": "Brazil", ... },
        "region": { "slug": "south-america", "name": "South America" }
      },
      "value": 220051512,
      "unit": null,
      "year": 2025
    }, ...
  ],
  "pagination": { "page": 1, "per_page": 5, "total": 14 }
}

API Key Management

POST/api/v1/keys

Name	Type	Required	Description
`email`	string	Yes	Your email address
`name`	string	No	App or project name

curl

curl -X POST https://bamwor.com/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "My App"}'

Response

{
  "data": {
    "api_key": "bw_live_a1b2c3d4e5f6...",
    "plan": "free",
    "limits": { "per_minute": 30, "per_day": 1000 },
    "message": "Store this key securely — it cannot be retrieved later."
  }
}

GET/api/v1/keys/usage

Check your current API key usage and remaining limits.

curl

curl -H "X-API-Key: bw_live_your_key" \
  https://bamwor.com/api/v1/keys/usage

Response

{
  "data": {
    "plan": "free",
    "usage": {
      "minute": { "used": 5, "limit": 30, "resets_in": 42 },
      "day": { "used": 127, "limit": 1000, "resets_in": 54321 }
    }
  }
}

Get started View pricing