Busca de CEPs por Raio e Coordenadas Geográficas: como usar na prática

A NextAPI tem dois endpoints geoespaciais para consulta de CEPs por proximidade. Os dois aceitam um raio em metros e devolvem uma lista paginada de CEPs ordenados por distância, sem depender de serviços externos como Google Maps.

Os dois endpoints

1. CEPs próximos a coordenadas GPS (`GET /v1/ceps/geo`)

Recebe latitude, longitude e um raio em metros, e retorna os CEPs dentro daquela área. Útil quando você já tem a posição GPS do usuário ou do entregador.

GET https://api.nextapi.com.br/v1/ceps/geo?latitude=-23.5614&longitude=-46.6559&raioMetro=1000
Authorization: Bearer SEU_TOKEN

Parâmetros obrigatórios:

latitude — latitude do ponto de referência (ex: -23.5614)
longitude — longitude do ponto de referência (ex: -46.6559)
raioMetro — raio em metros ao redor do ponto (ex: 1000 para 1 km)

Parâmetros opcionais: page e pageSize (máx 200 itens por página, limite global de 2.000 itens). Consome 2 créditos por consulta.

Exemplo de resposta (cada item da lista):

{
  "cep": "01310-100",
  "logradouro": "Avenida Paulista",
  "localidade": "Bela Vista",
  "nomeMunicipio": "São Paulo",
  "uf": "SP",
  "latitude": -23.5614,
  "longitude": -46.6559
}

2. CEPs próximos a um CEP de referência (`GET /v1/ceps/geo/{cep}`)

Alternativa quando você tem um CEP em vez de coordenadas. A API usa a geolocalização do CEP informado como ponto de origem.

GET https://api.nextapi.com.br/v1/ceps/geo/01310100?raioMetro=500
Authorization: Bearer SEU_TOKEN

O parâmetro cep vai no path (somente dígitos, sem traço). O raioMetro é obrigatório na query string. Também consome 2 créditos e suporta paginação.

Exemplos práticos

Encontrar CEPs próximos à posição GPS do usuário

async function cepsProximos(raioMetros = 500) {
    const pos = await new Promise((resolve, reject) =>
        navigator.geolocation.getCurrentPosition(resolve, reject)
    );

    const { latitude, longitude } = pos.coords;
    const url = new URL('https://api.nextapi.com.br/v1/ceps/geo');
    url.searchParams.set('latitude', latitude);
    url.searchParams.set('longitude', longitude);
    url.searchParams.set('raioMetro', raioMetros);

    const response = await fetch(url, {
        headers: { Authorization: 'Bearer ' + process.env.NEXTAPI_TOKEN }
    });

    const data = await response.json();
    return data.items; // array de CEPs próximos
}

Verificar se um CEP está na zona de entrega

Para um restaurante que entrega em até 2 km, você pode checar se o CEP do cliente aparece na lista antes de confirmar o pedido:

async function dentroZonaEntrega(cepLoja, cepCliente, raioMetros = 2000) {
    // Remove formatação
    const cepLimpo = cepLoja.replace(/D/g, '');

    const response = await fetch(
        'https://api.nextapi.com.br/v1/ceps/geo/' + cepLimpo + '?raioMetro=' + raioMetros,
        { headers: { Authorization: 'Bearer ' + process.env.NEXTAPI_TOKEN } }
    );

    const data = await response.json();
    const cepClienteLimpo = cepCliente.replace(/D/g, '').replace(/(d{5})(d{3})/, '$1-$2');

    return data.items.some(item => item.cep === cepClienteLimpo);
}

// Uso
const aceita = await dentroZonaEntrega('01310100', '01311-100');
console.log(aceita ? 'Entrega disponível' : 'Fora da área de cobertura');

Casos de uso

Delivery: checar se o CEP do cliente está dentro da área de cobertura do restaurante antes de confirmar o pedido.
Logística: listar os CEPs atendidos por um centro de distribuição e usá-los para rotear pedidos para a transportadora correta.
Imobiliárias e marketplaces: encontrar anúncios próximos a um ponto de interesse sem precisar integrar Google Maps.
Field service: ao receber coordenadas de um técnico em campo, identificar qual CEP e logradouro está mais próximo para registrar a ocorrência.

Limites e paginação

Cada consulta retorna até 200 itens por página, com limite global de 2.000 registros. Para raios grandes em regiões densas (ex: 5.000 metros no centro de São Paulo), o retorno pode ter várias páginas — use page e pageSize para navegar. Os endpoints de geo estão disponíveis somente nos planos pagos.

A documentação completa está disponível em nextapi.com.br/#docs.

Pronto para integrar?

Teste a API agora mesmo sem precisar de cartão de crédito. 100 requisições/mês grátis.

Criar Conta Grátis