Documentazione API

Riferimento completo dell'API REST di Bamwor. Endpoint, parametri, autenticazione, limiti e formati di risposta.

Base URL

https://bamwor.com/api/v1

Autenticazione

Includi la tua API key in ogni richiesta usando uno di questi metodi:

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

Le richieste anonime (senza key) sono consentite con limiti inferiori: 10/min, 100/giorno.

Limiti di Utilizzo

PlanAl minutoAl giornoPrezzo
Anonymous10100Gratuito (senza key)
Free301,000$0
Pro12050,000$29/mo
Enterprise600500,000Personalizzato

Gli header di rate limit sono inclusi in ogni risposta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Paginazione

Gli endpoint paginati accettano i parametri page e per_page. 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
  }
}

Gestione Errori

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"
  }
}
StatusCodeDescrizione
400BAD_REQUESTParametri non validi
401INVALID_API_KEYAPI key non valida o mancante
403API_KEY_DISABLEDAPI key disabilitata
404NOT_FOUNDRisorsa non trovata
429RATE_LIMIT_EXCEEDEDTroppe richieste
500INTERNAL_ERRORErrore del server

Riferimento Endpoint

GET/api/v1/countries

Lista paginata di tutti i paesi con statistiche di base.

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

Dettaglio completo del paese con tutte le statistiche.

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

Città paginate all'interno di un paese.

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

Dettaglio della città per ID 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

Trovare città vicine usando ricerca per raggio 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

Cerca paesi e città per nome in una delle 4 lingue supportate.

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

Elenco di tutte le metriche di classifica disponibili.

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

Classifica paginata dei paesi per una metrica specifica.

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

Gestione API Key

POST/api/v1/keys

Registrare una nuova API key gratuita.

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

Verifica l'uso attuale della tua API key e i limiti rimanenti.

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 }
    }
  }
}
IniziareVedi prezzi