📖 API Documentation
Complete reference — authentication, endpoints, parameters and examples. Base URL: https://api.scorecidades.com.br
Introduction
The Score de Cidades REST API provides socioeconomic data for 5,570 Brazilian municipalities, 27 states and over 20,000 neighborhoods. Data integrates IBGE, RAIS, Anatel, Central Bank, Ministry of Health and Federal Revenue.
Base URL: https://api.scorecidades.com.br — all responses in JSON.
🔑 Authentication
The Free plan requires no authentication — rate limits apply per IP. Starter and Pro plans require an API key in the x-api-key header.
# Free plan (no key required) curl https://api.scorecidades.com.br/v1/cidade/rio-de-janeiro?lang=en # Starter/Pro plans curl -H "x-api-key: sk_live_YOUR_TOKEN" \ "https://api.scorecidades.com.br/v1/cidade/rio-de-janeiro/economia?lang=en"
Never expose your API key in client-side code. Use it only in backends or secure environments.
📊 Rate Limits
| Plan | Limit | Period | Reset |
|---|---|---|---|
| Free | 100 req | Per day | Midnight UTC |
| Starter | 10,000 req | Per month | 1st of each month |
| Pro | 100,000 req | Per month | 1st of each month |
| Enterprise | Unlimited | — | — |
Exceeding the limit returns 429 Too Many Requests.
⚠️ Errors
| Status | Code | Description |
|---|---|---|
| 400 | bad_request | Invalid or missing parameters |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Your plan does not include this endpoint |
| 404 | not_found | Municipality or resource not found |
| 429 | rate_limited | Request limit exceeded |
| 500 | internal_error | Internal server error |
GET /v1/cidade/{slug}Free
GET/v1/cidade/{slug}
Returns basic data for a municipality. The slug is the city name in lowercase with hyphens (e.g. sao-paulo, belo-horizonte).
curl "https://api.scorecidades.com.br/v1/cidade/curitiba?lang=en"
{
"slug": "curitiba",
"name": "Curitiba",
"state": "PR",
"region": "South",
"population": 1948626,
"area_km2": 435.27,
"hdi": 0.823,
"gdp_per_capita": 48320,
"investor_score": 84.0,
"literacy_rate": 97.3,
"capital": true
}🌐 Language Support
All endpoints accept the ?lang= parameter.
| Value | Language | Note |
|---|---|---|
pt | Portuguese (default) | — |
en | English | — |
es | Spanish | — |
zh | Simplified Chinese | Includes AI-generated investment_summary (Pro plan) |
Questions or interested in an Enterprise plan? Get in touch.