MAPS

Geocodificação e rotas

Converte um endereço em coordenadas, coordenadas em endereço, e calcula distância/duração de carro entre dois pontos.

Geocoding and routes

Turns an address into coordinates, coordinates into an address, and calculates driving distance/duration between two points.

SYNC resposta na mesma chamada answers in the same call

Endpoints

GET /api/v1/maps/geocode endereço → coordenadas address → coordinates

GET /api/v1/maps/reverse coordenadas → endereço coordinates → address

GET /api/v1/maps/route distância e duração de carro entre dois pontos driving distance and duration between two points

Não inclui tiles nem imagem de mapa renderizada — só os três cálculos acima.

Doesn't include tiles or a rendered map image — just the three calculations above.

Parâmetros

Parameters

Nome	Name	Onde	In
`address`	query	`/geocode` — endereço livre, até 500 caracteres (ex.: `Avenida Paulista, São Paulo`)	`/geocode` — free-text address, up to 500 characters (e.g. `Avenida Paulista, São Paulo`)
`lat`, `lon`	query	`/reverse` — latitude (-90 a 90) e longitude (-180 a 180)	`/reverse` — latitude (-90 to 90) and longitude (-180 to 180)
`from`, `to`	query	`/route` — cada um no formato `lat,lon` (ex.: `-23.5505,-46.6333`)	`/route` — each formatted as `lat,lon` (e.g. `-23.5505,-46.6333`)

Exemplo

Example

curl "https://api.alicercelabs.com.br/api/v1/maps/route?from=-23.5505,-46.6333&to=-22.9068,-43.1729" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "from": { "lat": -23.5505, "lon": -46.6333 },
    "to": { "lat": -22.9068, "lon": -43.1729 },
    "distance_km": 433.62,
    "duration_min": 334.8
  },
  "meta": { "elapsed_ms": 639, "request_id": "..." }
}

Erros possíveis

Possible errors

Status	Motivo	Reason
400	parâmetro obrigatório ausente ou mal formado	missing or malformed required parameter
401	token ausente ou inválido	missing or invalid token
429	limite de taxa excedido	rate limit exceeded
503	endereço/coordenadas não encontrados, ou o serviço de geocodificação/rotas não respondeu	address/coordinates not found, or the geocoding/routing service didn't respond

Limites

Limits

10.000/dia · 416/hora por operação (geocode/reverse contam junto; route conta separado). Resultado em cache: 180 dias pra geocodificação, 30 dias pra rota — o mesmo endereço ou par de pontos não paga o custo de consultar o serviço externo de novo.

10,000/day · 416/hour per operation (geocode/reverse share one quota; route has its own). Cached result: 180 days for geocoding, 30 days for routes — the same address or pair of points never pays the external-service cost twice.