Pular para o conteúdo principal

​
Endpoint

POST https://api.bunny.build/api/v1/geocoding

​
Autenticação

HeaderObrigatórioValor
X-API-KeySimSua chave de API (bun_...)
Content-TypeSimapplication/json

​
Visão geral

Realize geocodificação direta (endereço para coordenadas) passando uma query, ou geocodificação reversa (coordenadas para endereço) passando lat e lon. Retorna dados de localização estruturados incluindo endereço formatado, país, cidade e latitude/longitude precisos.

​
Casos de uso

  • Geocodificar endereços informados pelo usuário para exibição em mapas
  • Converter coordenadas GPS em endereços legíveis por humanos
  • Validar e normalizar endereços de entrega
  • Enriquecer dados de localização em pipelines de análise

​
Detalhes

A geocodificação direta aceita consultas em texto livre em qualquer idioma. A geocodificação reversa requer coordenadas em graus decimais. Os resultados são retornados para a melhor correspondência; não há paginação.

​
Corpo da requisição

CampoTipoObrigatórioDescrição
querystringNãoEndereço ou nome de lugar em texto livre (geocodificação direta)
latnumberNãoLatitude em graus decimais (geocodificação reversa)
lonnumberNãoLongitude em graus decimais (geocodificação reversa)
Forneça query para geocodificação direta, ou lat e lon para geocodificação reversa.

​
Exemplo — geocodificação direta

{
  "query": "1600 Amphitheatre Parkway, Mountain View, CA"
}

​
Exemplo — geocodificação reversa

{
  "lat": 37.4224764,
  "lon": -122.0842499
}

​
Resposta

​
200 OK

CampoTipoDescrição
formatted_addressstringEndereço completo formatado
latnumberLatitude
lonnumberLongitude
countrystringNome do país
country_codestringCódigo de país ISO 3166-1 alpha-2
citystringCidade ou localidade
postcodestringCódigo postal
Exemplo 
{
  "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "lat": 37.4224764,
  "lon": -122.0842499,
  "country": "United States",
  "country_code": "US",
  "city": "Mountain View",
  "postcode": "94043"
}

​
401 Unauthorized

{
  "detail": "Missing API key. Include X-API-Key header."
}

​
402 Payment Required

{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}

​
422 Unprocessable Entity

{
  "detail": "Provide 'query' for forward geocoding or 'lat' and 'lon' for reverse geocoding"
}

​
429 Too Many Requests

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

​
Exemplo cURL

curl -X POST https://api.bunny.build/api/v1/geocoding \
  -H "X-API-Key: bun_sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{"query": "1600 Amphitheatre Parkway, Mountain View, CA"}'