Documentação da API

Referência completa da API REST da Bamwor. Endpoints, parâmetros, autenticação, limites e formatos de resposta.

Base URL

https://bamwor.com/api/v1

Autenticação

Inclua sua API key em cada requisição usando um destes métodos:

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

Requisições anônimas (sem key) são permitidas com limites menores: 10/min, 100/dia.

Limites de Uso

PlanPor minutoPor diaPreço
Anonymous10100Grátis (sem key)
Free301,000$0
Pro12050,000$29/mo
Enterprise600500,000Personalizado

Os headers de rate limit são incluídos em cada resposta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Paginação

Endpoints paginados aceitam os parâmetros page e per_page. Padrão: page=1, per_page=25 (máx 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
  }
}

Tratamento de Erros

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"
  }
}
StatusCodeDescrição
400BAD_REQUESTParâmetros inválidos
401INVALID_API_KEYAPI key inválida ou ausente
403API_KEY_DISABLEDAPI key desabilitada
404NOT_FOUNDRecurso não encontrado
429RATE_LIMIT_EXCEEDEDMuitas requisições
500INTERNAL_ERRORErro do servidor

Referência de Endpoints

GET/api/v1/countries

Lista paginada de todos os países com estatísticas básicas.

NameTypeRequiredDescription
pageintegerNoPage number (default: 1)
per_pageintegerNoItems per page (default: 25, max: 100)
regionstringNoFilter by region slug (e.g. south-america)
sortstringNoSort 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

Detalhe completo do país com todas as estatísticas.

NameTypeRequiredDescription
slugstringYesCountry 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

Cidades paginadas dentro de um país.

NameTypeRequiredDescription
slugstringYesCountry slug
sortstringNoSort by: population, name (default: population)
min_populationintegerNoMinimum population filter
provincestringNoFilter by province/admin1 name
pageintegerNoPage number
per_pageintegerNoItems 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

Detalhe da cidade por ID do GeoNames.

NameTypeRequiredDescription
idintegerYesGeoNames 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

Encontrar cidades próximas usando busca por raio PostGIS.

NameTypeRequiredDescription
idintegerYesOrigin city GeoNames ID
radiusintegerNoRadius in km (default: 50, max: 200)
limitintegerNoMax 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

Buscar países e cidades por nome em qualquer um dos 4 idiomas suportados.

NameTypeRequiredDescription
qstringYesSearch query (min 2 chars, max 100)
typestringNoFilter: all, country, city (default: all)
limitintegerNoMax 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

Listar todas as métricas de ranking disponíveis.

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

Ranking paginado de países por uma métrica específica.

NameTypeRequiredDescription
slugstringYesMetric: population, area, density, gdp, gdp-per-capita, hdi, life-expectancy
regionstringNoFilter by region slug
pageintegerNoPage number
per_pageintegerNoItems 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 }
}

Gestão de API Keys

POST/api/v1/keys

Registrar uma nova API key grátis.

NameTypeRequiredDescription
emailstringYesYour email address
namestringNoApp 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

Verificar o uso atual da sua API key e limites restantes.

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 }
    }
  }
}
ComeçarVer preços