Como foi feito

Nada aqui fica guardado em servidor. O seu navegador chama as APIs públicas, que liberam chamadas de qualquer site (CORS), e monta o mapa e a tabela na hora. São três chamadas:

1. Um CEP (uma chamada por CEP)

GET https://cep.awesomeapi.com.br/json/01001000
{
  "cep": "01001000", "address_type": "Praça", "address_name": "da Sé",
  "address": "Praça da Sé", "state": "SP", "district": "Sé",
  "lat": "-23.5500806", "lng": "-46.6340827", "city": "São Paulo",
  "city_ibge": "3550308", "ddd": "11"
}

2. O contorno dos estados

GET https://servicodados.ibge.gov.br/api/v3/malhas/paises/BR
    ?formato=application/vnd.geo+json&intrarregiao=UF&qualidade=minima

3. O contorno de um município (só no modo "Aproximar")

GET https://servicodados.ibge.gov.br/api/v3/malhas/municipios/3550308
    ?formato=application/vnd.geo+json&qualidade=intermediaria

As regras das APIs que o dashboard respeita

  • O CEP tem 8 dígitos. A API aceita com ou sem hífen (01001-000 e 01001000 dão o mesmo resultado). Com 7 ou 9 dígitos, ou com letras, responde 400 (CEP invalido). O dashboard confere o formato antes de chamar, tira os repetidos e consulta no máximo 100 por vez.
  • CEP que não existe volta 404 (O CEP 99999999 nao foi encontrado). Ele aparece na tabela como "não encontrado" e fica fora do mapa: um CEP ruim não derruba a consulta dos outros.
  • Cidade de CEP único vem sem rua e sem bairro. Em 37925-000 (Piumhi/MG), logradouro e bairro voltam vazios e a coordenada é a da cidade.
  • Latitude e longitude vêm como texto ("-23.5500806") e são aproximadas: localizam o logradouro, não o imóvel. O dashboard converte para número e trata vazio ou zero como "sem coordenada".
  • Os dados têm ruído. Em 76980-000, por exemplo, o tipo de logradouro vem preenchido com o nome da cidade. A tabela mostra o que a API devolve, sem corrigir.
  • Sem chave e sem limite documentado. As respostas saem de cache (Cloudflare, 7 dias) e 30 chamadas simultâneas passaram sem bloqueio nos testes. Mesmo assim, o dashboard faz no máximo 6 chamadas ao mesmo tempo.
  • city_ibge liga o CEP às malhas do IBGE. É o código do município: os 2 primeiros dígitos são a UF e o primeiro, a região. A malha municipal aceita um município por chamada (3550308|3304557 responde 400) e um código que não existe responde 500; o modo "Aproximar" desenha o contorno de até 30 municípios.

Os cálculos

  • Maior distância: fórmula de haversine, a linha reta sobre a esfera da Terra (raio de 6.371 km), entre todos os pares de CEPs com coordenada. Não é a distância por estrada.
  • Mapa: projeção equirretangular corrigida pelo cosseno da latitude central. Basta para o Brasil inteiro, mas não é a projeção oficial do IBGE.
  • Tempo da consulta: do primeiro pedido à última resposta. CEP repetido na mesma visita sai da memória do navegador, sem nova chamada.

Documentação oficial: AwesomeAPI, API de CEP e IBGE, API de malhas geográficas.