🔎API Busca de Endereços

Busca de endereços brasileiros por geolocalização ou texto.

Endpoint: https://cep.awesomeapi.com.br/searcharrow-up-right

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:

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:

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:

4. Filtro por Estado (UF)

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

Exemplo de Request:

Exemplo de Resposta (JSON)

Last updated