API Praticidade Score

Receba a pontuação de praticidade urbana a pé — 14 categorias (segurança, transporte, serviços, saúde, lazer e mais) e um score geral — para qualquer coordenada em 10 cidades premium de Brasil e Portugal. É uma API server-to-server: a chave é uma credencial de backend e nunca deve ir para o navegador.

Coordenadas, não endereços

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.

Autenticação

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).

Endpoint

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

Limites e cota

Tier	Por minuto	Por mês
free	10	1.000
pilot	60	50.000

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

Códigos de erro

HTTP	code	Significado
401	UNAUTHORIZED	Chave ausente ou inválida.
429	RATE_LIMITED	Excedeu o limite por minuto da sua chave.
429	QUOTA_EXCEEDED	Cota mensal esgotada.
400	BAD_REQUEST	lat/lon ausentes ou fora de faixa.
422	OUT_OF_COVERAGE	Coordenadas fora das cidades cobertas.
422	NO_COVERAGE	Sem score disponível nesse ponto.
500	INTERNAL_ERROR	Erro interno ao computar o score.

Cidades cobertas

São PauloRio de JaneiroBelo HorizonteBrasíliaCuritibaPorto AlegreFortalezaSalvadorLisboaPorto

Obter uma chave

O piloto é por convite. Conte-nos o seu caso de uso e volume estimado e enviamos uma chave. A faturação do piloto é por fatura (sem cartão).

Falar connosco

Uso justo durante o piloto: sem SLA contratual ainda; a chave pode ser revogada em caso de abuso. Os dados não incluem identificadores do Google nem avaliações brutas — veja a metodologia.

Endpoint

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

Tier

Por minuto

Por mês

free

1.000

pilot

50.000

Códigos de erro

HTTP	code	Significado
401	UNAUTHORIZED	Chave ausente ou inválida.
429	RATE_LIMITED	Excedeu o limite por minuto da sua chave.
429	QUOTA_EXCEEDED	Cota mensal esgotada.
400	BAD_REQUEST	lat/lon ausentes ou fora de faixa.
422	OUT_OF_COVERAGE	Coordenadas fora das cidades cobertas.
422	NO_COVERAGE	Sem score disponível nesse ponto.
500	INTERNAL_ERROR	Erro interno ao computar o score.

Obter uma chave

O piloto é por convite. Conte-nos o seu caso de uso e volume estimado e enviamos uma chave. A faturação do piloto é por fatura (sem cartão).

Falar connosco

Uso justo durante o piloto: sem SLA contratual ainda; a chave pode ser revogada em caso de abuso. Os dados não incluem identificadores do Google nem avaliações brutas — veja a metodologia.