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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.