Documentação da API

REST, JSON, autenticado por token. Geocodificação, rotas, matriz e CEP — servidos 100% pela nossa infraestrutura no Brasil.

Autenticação

Toda chamada leva sua chave no header Authorization. Crie a chave no painel.

# header em toda requisição
Authorization: Bearer rk_live_sua_chave_aqui

Toda resposta traz os headers de cota: X-Quota-Limit, X-Quota-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining.

Erros

Envelope único: {"ok":false,"erro":{"codigo","mensagem"}}.

Rate limit & cota

Cada plano tem cota mensal + rate por segundo. Excedeu a cota → 402; excedeu o rate → 429. Veja seu consumo ao vivo no painel.

POST /v1/geocode

Endereço → coordenada (precisão de número de casa).

curl -X POST https://mapacore.com.br/v1/geocode \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"endereco":"Rua XV de Novembro","numero":"1500","cidade":"Blumenau","uf":"SC","cep":"89010200"}'

→ {"ok":true,"lat":-26.9217,"lng":-49.0582,"precisao":"numero","fonte":"nominatim"}

GET /v1/cep/:cep

curl https://mapacore.com.br/v1/cep/89010001 -H "Authorization: Bearer $TOKEN"
→ {"ok":true,"logradouro":"Rua XV de Novembro","bairro":"Centro","cidade":"Blumenau","uf":"SC"}

POST /v1/route

Rota de carro origem→destino, com paradas[] opcionais. Coords no retorno em [lat,lng], prontas pra desenhar.

curl -X POST https://mapacore.com.br/v1/route \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"origem":{"lat":-26.9038,"lng":-49.0736},"destino":{"lat":-26.9216,"lng":-49.0582}}'

→ {"ok":true,"coords":[[-26.90,-49.07],...],"distancia_m":4772,"duracao_s":505,"eta_texto":"8 min"}

POST /v1/matrix

Matriz N×M de tempos/distâncias + ordem_sugerida (melhor sequência de multiparadas).

curl -X POST https://mapacore.com.br/v1/matrix \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"pontos":[{"lat":-26.90,"lng":-49.07},{"lat":-26.92,"lng":-49.06},{"lat":-26.89,"lng":-49.09}]}'

→ {"ok":true,"ordem_sugerida":[0,2,1],"tempo_total_s":1176,"eta_texto":"20 min"}

GET /v1/usage

Consumo do seu token: plano, cota, usados, restante, rate limit.

Playground

Teste agora, sem cadastro (chave de demonstração já preenchida).

// resposta aparece aqui

SDKs

Bibliotecas oficiais — o cliente só configura MAPS_API_URL + MAPS_API_TOKEN, nunca vê a infraestrutura.

# Python
from maps_client import MapsClient
mc = MapsClient("https://mapacore.com.br", "rk_live_...")
mc.route((-26.90,-49.07), (-26.92,-49.06))   # dist, dur, coords
mc.geocode(endereco="Rua XV de Novembro", numero="1500", cidade="Blumenau")