> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /geocoding

> Converta endereços em coordenadas (geocodificação direta) ou coordenadas em endereços (geocodificação reversa).

## Endpoint

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

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/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

| Campo   | Tipo   | Obrigatório | Descrição                                                        |
| ------- | ------ | ----------- | ---------------------------------------------------------------- |
| `query` | string | Não         | Endereço ou nome de lugar em texto livre (geocodificação direta) |
| `lat`   | number | Não         | Latitude em graus decimais (geocodificação reversa)              |
| `lon`   | number | Não         | Longitude 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

```json theme={null}
{
  "query": "1600 Amphitheatre Parkway, Mountain View, CA"
}
```

### Exemplo — geocodificação reversa

```json theme={null}
{
  "lat": 37.4224764,
  "lon": -122.0842499
}
```

## Resposta

### 200 OK

| Campo               | Tipo   | Descrição                         |
| ------------------- | ------ | --------------------------------- |
| `formatted_address` | string | Endereço completo formatado       |
| `lat`               | number | Latitude                          |
| `lon`               | number | Longitude                         |
| `country`           | string | Nome do país                      |
| `country_code`      | string | Código de país ISO 3166-1 alpha-2 |
| `city`              | string | Cidade ou localidade              |
| `postcode`          | string | Código postal                     |

**Exemplo**

```json theme={null}
{
  "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

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Provide 'query' for forward geocoding or 'lat' and 'lon' for reverse geocoding"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Exemplo cURL

```bash theme={null}
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"}'
```