# 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
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.awesomeapi.com.br/api-cep/api-busca-de-enderecos.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.