> For the complete documentation index, see [llms.txt](https://docs.awesomeapi.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.awesomeapi.com.br/api-cep/api-busca-de-enderecos.md).

# API Busca de Endereços

Endpoint: <https://cep.awesomeapi.com.br/search>

Esta documentação detalha os novos endpoints de busca, permitindo pesquisas textuais e por Geolocalização + distância em KM.

Permite buscar endereços por termos textuais (logradouro, cidade, estado, etc.) e/ou por proximidade geográfica (latitude e longitude).\
\
**Método:** `GET`\
**URL:** `/search` (e variantes como `/search/:query`)

#### Parâmetros de Consulta (Query Parameters)

| Parâmetro | Tipo   | Descrição                                                                               | Padrão  |
| --------- | ------ | --------------------------------------------------------------------------------------- | ------- |
| `q`       | string | Termo de busca textual. Pode ser passado na URL como `/search/termo`.                   | `*`     |
| `state`   | string | Filtra resultados por UF (ex: SP, RJ).                                                  | -       |
| `lat`     | float  | Latitude para busca por geolocalização. Obrigatório para funcionalidades de distância.  | -       |
| `lng`     | float  | Longitude para busca por geolocalização. Obrigatório para funcionalidades de distância. | -       |
| `d`       | float  | Raio de distância em quilômetros (km) para filtrar resultados. (padrão é sem limite)    | `0.0`\* |
| `sort`    | string | Direção da ordenação por distância (`asc` ou `desc`). Requer `lat` e `lng`.             | `asc`   |
| `limit`   | int    | Número máximo de resultados retornados por página (Máx: 10).                            | `10`    |
| `page`    | int    | Número da página para paginação. (Apenas autenticado)                                   | `1`     |
| `format`  | string | Formato da resposta: `json` ou `xml`.                                                   | `json`  |

\* *O valor padrão de `d` é sem limite sempre que `lat`/`lng` forem fornecidos e `d` for omitido.*

#### Cenários de Uso

**1. Busca Textual Simples**

**Exemplo de Request:**

```http
GET https://cep.awesomeapi.com.br/search?q=paulista
# ou
GET https://cep.awesomeapi.com.br/search/paulista
```

**2. Busca por Geolocalização (Proximidade)**

Busca endereços próximos a uma coordenada específica. Se nenhum raio (`d`) for informado, busca num raio padrão de 1km.

**Exemplo de Request:**

```http
GET https://cep.awesomeapi.com.br/search?lat=-23.56168&lng=-46.65598
```

**3. Busca Combinada (Texto + Geolocalização)**

Busca por termos textuais dentro de um raio específico de uma coordenada, ordenando os resultados pela distância.

**Exemplo de Request:**

```http
GET https://cep.awesomeapi.com.br/search?q=paulista&lat=-23.56168&lng=-46.65598&d=5
```

**4. Filtro por Estado (UF)**

Filtra os resultados para exibir apenas endereços de um estado específico.

**Exemplo de Request:**

```http
GET https://cep.awesomeapi.com.br/search?q=av+paulista&state=SP
```

#### Exemplo de Resposta (JSON)

```json
{
  "results": [
    {
      "cep": "01310-100",
      "address_type": "Avenida",
      "address_name": "Paulista",
      "address": "Avenida Paulista",
      "state": "SP",
      "state_name": "São Paulo",
      "district": "Bela Vista",
      "lat": "-23.561684",
      "lng": "-46.655981",
      "city": "São Paulo",
      "city_ibge": "3550308",
      "ddd": "11",
      "distance_km": 0.010534
    },
    {
      "cep": "01311-200",
      "address_type": "Rua",
      "address_name": "Augusta",
      "address": "Rua Augusta",
      "state": "SP",
      "state_name": "São Paulo",
      "district": "Consolação",
      "lat": "-23.558284",
      "lng": "-46.660981",
      "city": "São Paulo",
      "city_ibge": "3550308",
      "ddd": "11",
      "distance_km": 0.543210
    }
  ]
}
```