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

Usando o SDK

Using the SDK

Três métodos independentes: endereço → coordenadas, coordenadas → endereço, e distância de carro entre dois pontos.

Three independent methods: address → coordinates, coordinates → address, and driving distance between two points.

SDKs oficiais: Go · Python · JavaScript.

Official SDKs: Go · Python · JavaScript.

Geocodificar um endereço

Geocode an address

import (
	"context"
	"fmt"

	alicercelabs "github.com/alicercelabs/alicercesdk-go"
)

client := alicercelabs.New("alk_...")
ctx := context.Background()

res, err := client.Maps.Geocode(ctx, "Avenida Paulista, 1000, Sao Paulo")
fmt.Println(res.Lat, res.Lon)

from alicercelabs import AlicerceLabs

client = AlicerceLabs(api_key="alk_...")

res = client.maps.geocode("Avenida Paulista, 1000, Sao Paulo")
print(res["lat"], res["lon"])

import { AlicerceLabs } from "alicercesdk-javascript";

const client = new AlicerceLabs("alk_...");

const res = await client.maps.geocode("Avenida Paulista, 1000, Sao Paulo");
console.log(res.lat, res.lon);

Geocodificação reversa

Reverse geocode

res, err := client.Maps.Reverse(ctx, -23.5613, -46.6563)
fmt.Println(res.Address)

res = client.maps.reverse(-23.5613, -46.6563)
print(res["address"])

const res = await client.maps.reverse(-23.5613, -46.6563);
console.log(res.address);

Distância/duração de carro

Driving distance/duration

res, err := client.Maps.Route(ctx, "-23.5613,-46.6563", "-23.5505,-46.6333")
fmt.Println(res.DistanceKM, res.DurationMin)

res = client.maps.route("-23.5613,-46.6563", "-23.5505,-46.6333")
print(res["distance_km"], res["duration_min"])

const res = await client.maps.route("-23.5613,-46.6563", "-23.5505,-46.6333");
console.log(res.distance_km, res.duration_min);

Limites

Limits

100/dia · 4/hora sem token; com uma API key (gerada no painel), 1.000/dia · 41/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.

100/day · 4/hour without a token; with an API key (generated in the panel), 1,000/day · 41/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.