Como calcular a distância entre CEPs com JavaScript e a APIBrasil

Delivery, e-commerce com entrega própria, empresas de serviço que cobram deslocamento e aplicativos de logística têm a mesma pergunta: qual é a distância entre dois CEPs? Neste tutorial você vai aprender a calcular a distância entre CEPs com JavaScript usando a API Calcula Distância CEP da APIBrasil e, no final, transformar essa distância em uma taxa de entrega.

A API devolve a distância de carro, o tempo estimado de trajeto, as coordenadas de origem e destino e o endereço completo de cada CEP, tudo em uma chamada.

O que a API Calcula Distância CEP devolve

A API fica na categoria Dados e Utilidades e custa R$ 0,03 por consulta em produção, conforme o catálogo.

Campo	Descrição
`distanceRaw`	Distância em metros, como número
`distance`	Distância formatada, como texto
`timeRaw`	Tempo estimado de trajeto, como número
`time`	Tempo formatado, como texto
`origin`, `destination`	Descrição da origem e do destino
`extra.coordsInfo`	Latitude e longitude da origem, do destino e dos pontos da rota
`info`	Endereço de cada CEP: logradouro, bairro, cidade, UF, código IBGE e DDD

O corpo recebe uma lista ceps e o modo de deslocamento. O exemplo do catálogo usa "mode": "driving", ou seja, trajeto de carro.

Pré-requisitos

Node.js 18 ou mais novo.
Bearer Token da APIBrasil, em Credenciais no painel. Veja os primeiros passos se precisar.

Passo 1: a chamada

POST https://gateway.apibrasil.io/api/v2/cep/distancia/calcular
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "tipo": "calcula-distancia-cep",
  "ceps": ["03189010", "03186040"],
  "mode": "driving",
  "homolog": true
}

Repare que a rota desta API é cep/distancia/calcular, diferente do padrão .../credits de outras APIs. Sempre copie a rota exata da página da API na documentação.

Passo 2: a função que calcula a distância

Crie o arquivo distancia.js:

const URL = "https://gateway.apibrasil.io/api/v2/cep/distancia/calcular";

const limparCep = (cep) => {
  const c = String(cep).replace(/\D/g, "");
  if (c.length !== 8) throw new Error(`CEP inválido: ${cep}`);
  return c;
};

export async function distanciaEntreCeps(origem, destino) {
  const resp = await fetch(URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.APIBRASIL_TOKEN}`,
    },
    body: JSON.stringify({
      tipo: "calcula-distancia-cep",
      ceps: [limparCep(origem), limparCep(destino)],
      mode: "driving",
      homolog: process.env.APIBRASIL_HOMOLOG !== "false",
    }),
    signal: AbortSignal.timeout(120_000),
  });

  if (resp.status === 402) throw new Error("Saldo insuficiente na APIBrasil");
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);

  const json = await resp.json();
  if (json.error || !json.data?.ok) {
    throw new Error(json.message || "Não foi possível calcular a distância");
  }

  const d = json.data;
  return {
    km: d.distanceRaw / 1000,
    minutos: Math.round(d.timeRaw / 60),
    textoDistancia: d.distance,
    textoTempo: d.time,
    origem: d.info?.[0],
    destino: d.info?.[1],
    coordenadas: d.extra?.coordsInfo,
  };
}

A função devolve um objeto já pronto para a regra de negócio: quilômetros em número, minutos arredondados e o endereço de cada CEP.

JSON de resposta da API Calcula Distância CEP com distância, tempo e coordenadas — Os campos <code>distanceRaw</code> e <code>timeRaw</code> são numéricos. Os textos formatados vêm em <code>distance</code> e <code>time</code>.

Confira a unidade do timeRaw na resposta real da sua conta antes de usá-lo em cálculo. No exemplo do catálogo, o valor em segundos bate com o tempo formatado.

Passo 3: transforme distância em taxa de entrega

Com a distância em mãos, a regra de frete fica simples. Crie o arquivo frete.js:

import { distanciaEntreCeps } from "./distancia.js";

const TAXA_BASE = 5.0;   // R$
const POR_KM = 2.0;      // R$ por km
const RAIO_MAX_KM = 15;  // não entrega acima disso

const brl = (n) => n.toLocaleString("pt-BR", { style: "currency", currency: "BRL" });

const [origem, destino] = process.argv.slice(2);
const r = await distanciaEntreCeps(origem, destino);

console.log("Origem ..........", r.origem?.cep, "·", `${r.origem?.localidade}/${r.origem?.uf}`);
console.log("Destino .........", r.destino?.cep, "·", `${r.destino?.localidade}/${r.destino?.uf}`);
console.log("Distância .......", r.km.toFixed(2).replace(".", ","), "km", `(≈ ${r.minutos} min de carro)`);

if (r.km > RAIO_MAX_KM) {
  console.log("✖ Fora do raio de entrega");
} else {
  const taxa = TAXA_BASE + Math.ceil(r.km) * POR_KM;
  console.log("Taxa de entrega .", brl(taxa));
}

Lembre de colocar "type": "module" no package.json e rode:

node --env-file=.env frete.js 03189010 03186040

Saída do script JavaScript calculando taxa de entrega a partir da distância entre CEPs — Exemplo de regra de negócio: taxa fixa mais valor por quilômetro, com limite de raio.

Precisa só do endereço? Use a API CEP com IBGE

Se você não precisa de distância, mas quer preencher o endereço a partir do CEP, a API CEP com IBGE (rota consulta/cep/credits, corpo {"tipo":"cep","cep":"31585230"}) é mais indicada. Ela devolve logradouro, bairro, cidade, código IBGE, DDD e coordenadas, e ainda tem endpoints para listar cidades por UF, bairros por cidade e cidades por DDD. Veja o passo a passo em como consultar CEP com JavaScript e preencher o endereço.

Boas práticas

Cache por par de CEPs: a distância entre dois CEPs quase não muda. Guarde o resultado e economize consultas.
Chame pelo back-end: nunca exponha o token no navegador. O front-end chama a sua rota, e a sua rota chama a APIBrasil.
Arredonde a favor do cliente: mostre a taxa já arredondada e explique a regra na tela de checkout.

Perguntas frequentes

É distância em linha reta ou pela rua?

Com mode: "driving", é a distância do trajeto de carro, não a linha reta. As coordenadas em extra.coordsInfo permitem calcular a linha reta se você precisar das duas.