API Praticidade Score

A API recebe lat/lon e devolve o score — não faz geocodificação (converter endereço em coordenadas é o centro de custo pago, então fica do seu lado, ou use o widget, que já emite lat/lon). O score usa uma isócrona de caminhada de 10 minutos.

Envie a sua chave em um dos cabeçalhos:

Authorization: Bearer pk_live_SUA_CHAVE
# ou
x-api-key: pk_live_SUA_CHAVE

A chave é mostrada uma única vez na emissão e não é recuperável (guardamos apenas o hash).

GET /api/v1/score?lat=<num>&lon=<num>[&city=<slug>]

Exemplo (São Paulo, av. Paulista):

curl "https://praticidade.com/api/v1/score?lat=-23.561&lon=-46.656" \
  -H "Authorization: Bearer pk_live_SUA_CHAVE"

Resposta

{
  "success": true,
  "data": {
    "overall": 8.4,
    "city": { "slug": "sao-paulo", "name": "São Paulo" },
    "coordinates": { "lat": -23.561, "lon": -46.656 },
    "walkingMinutes": 10,
    "totalPOIs": 1284,
    "diversity": 0.82,
    "density": 7.1,
    "categories": [
      { "category": "seguranca", "label": "Segurança", "score": 7.9, "weight": 0.16, "count": 0 },
      { "category": "transporte", "label": "Transporte", "score": 9.1, "weight": 0.13, "count": 22 }
      /* ... 14 categorias no total ... */
    ],
    "computedAt": "2026-05-31T12:00:00.000Z"
  }
}

Campo evidence (segurança): em Belo Horizonte, Curitiba, Porto Alegre, Brasília e Fortaleza não existe fonte oficial de criminalidade por bairro. Nessas cidades a categoria seguranca traz "evidence": "urban-activity-proxy" (e a resposta traz o campo de conveniência segurancaEvidence): o valor é uma estimativa por atividade urbana, ancorada no nível de segurança da cidade, e não deve ser usado para ordenar bairros dentro da cidade. Detalhes em /metodologia.

GET /api/v1/prices?city=<slug>[&district=<slug>][&include_series=1]

Preço mediano do m² por bairro, com proveniência explícita. Mesma chave, mesmos limites e mesma cota do /api/v1/score (cada resposta 2xx consome 1 unidade). Sem district, devolve todos os bairros da cidade com preço publicado; include_series=1 acrescenta a série temporal agregada quando existe.

curl "https://praticidade.com/api/v1/prices?city=lisboa&district=ajuda" \
  -H "Authorization: Bearer pk_live_SUA_CHAVE"

Resposta (abreviada)

{
  "success": true,
  "data": {
    "city": { "slug": "lisboa", "name": "Lisboa" },
    "currency": "EUR",
    "unit": "m2",
    "count": 1,
    "districts": [
      {
        "district": { "slug": "ajuda", "name": "Ajuda" },
        "canonical_url": "https://praticidade.com/cidade/lisboa/bairro/ajuda",
        "price_m2_mediano": 4874,
        "source": "ine",
        "reference_period": "4.º trimestre de 2025",
        "rent_mediano_m2": 17.06,
        "rent_source": "ine",
        "rent_reference_period": "2.º semestre de 2024"
      }
    ],
    "attribution": [
      {
        "source": "ine",
        "label": "INE — Instituto Nacional de Estatística (Portugal)",
        "url": "https://www.ine.pt",
        "license": "CC BY 4.0"
      }
    ],
    "computedAt": "2026-06-12T12:00:00.000Z"
  }
}

Proveniência (campo source): itbi são agregados de transações registadas (São Paulo e Belo Horizonte; o campo num_transacoes só existe aqui); ine são medianas oficiais do INE por freguesia (Lisboa e Porto, venda e renda, licença CC BY 4.0); estimate são estimativas de mercado e trazem sempre um disclaimer — nunca são apresentadas como dados oficiais. Bairros abaixo dos gates de publicação (ex.: menos de 30 transações ITBI, supressão de confidencialidade do INE) simplesmente não aparecem na resposta. Os dados são apenas agregados (medianas e séries por período) e cada resposta inclui a attribution obrigatória das fontes.

Apenas respostas 2xx contam para a cota. Cada resposta traz os cabeçalhos X-RateLimit-* e X-Quota-*.

O preço do tier pilot segue o plano API do rate card. Tabela de preços completa.