🔎API Busca de Endereços

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

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:

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:

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:

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:

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

Exemplo de Resposta (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
    }
  ]
}