REST API Documentation

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

{
  "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 }
}

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

{
  "data": {
    "gec_code": "JA",
    "iso_code": "JA",
    "names": { "en": "Japan", "es": "Japón", "pt": "Japão", "it": "Giappone" },
    "population": 123719238,
    "population_year": 2025,
    "area_sq_km": 377915,
    "stats": {
      "population": { "value": 123719238, "unit": "people", "year": 2025, "source": "CIA World Factbook" },
      "gdp_ppp": { "value": 6025000000000, "unit": "USD", "year": 2023, "source": "CIA World Factbook" },
      "ibeu": { "value": 56.32, "unit": "index score", "year": 2026, "source": "Bamwor Proprietary Index" },
      ...
    },
    "flag_url": "/flags/ja.png",
    "map_url": "/maps/ja.png"
  }
}
// gec_code: FIPS 10-4 country code (2 chars, differs from ISO 3166-1)
// population_year: year of the population estimate
// stats include 9 Bamwor indices (ibeu, ibcp, ibda, ibcx, ibee, ibfm, ibdi, ibed, ibsa)

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

{
  "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 }
}

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

{
  "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" }
  }
}

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

{
  "data": [
    {
      "id": 3432043,
      "names": { "en": "La Plata", ... },
      "coordinates": { "latitude": -34.9215, "longitude": -57.9545 },
      "population": 694167,
      "distance_km": 56.2
    }, ...
  ],
  "pagination": { "page": 1, "per_page": 5, "total": 5, "total_pages": 1 }
}

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

{
  "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"
    }
  ]
}

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

{
  "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" },
    ...
  ]
}

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

{
  "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 }
}

curl -H "X-API-Key: bw_live_your_key" \
  "https://bamwor.com/api/v1/countries/argentina/sections?section=government"

{
  "data": {
    "country": { "name": "Argentina", "slug": "argentina", "iso_code": "AR" },
    "sections": {
      "government": {
        "Country name": { "conventional long form": { "text": "Argentine Republic" }, ... },
        "Government type": { "text": "presidential republic" },
        "Capital": { "name": { "text": "Buenos Aires" }, ... },
        ...
      }
    },
    "section_count": 1
  }
}
// Non-premium: 403 PREMIUM_REQUIRED (demo: colombia, italy, australia)

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

{
  "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."
  }
}

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

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