Este projeto busca manter uma base de dados de contribuição coletiva (do inglês, crowdsourcing database) para códigos de endereçamento postal (CEP) do Brasil.

Através de uma estrutura de dados no formato JSON e arquivos com nomenclatura padronizada, esta base de dados pode ser utilizada como dependência em projetos que necessitam de informações atualizadas, relacionadas a CEPs no país.

Todos os arquivos com informações sobre CEPs estão armazenados no diretório data/ e nomeados com o padrão /^[0-9]{8}\.json$/. Este arquivo contém um documento no formato JSON com atributos que descrevem o endereço relacionado ao CEP. Por exemplo, o primeiro código postal do Brasil, segundo a Wikipédia, está armazenado no arquivo data/01001000.json e possui o seguinte conteúdo.

{
    "_id": "01001000",
    "tipo": "Praça",
    "logradouro": "da Sé",
    "bairro": "Sé",
    "cidade": "São Paulo",
    "estado": "SP"
}

Existe a possibilidade de acessar a base de dados remotamente através de requisições HTTP pelo GitHub Pages. Assim, para acessar as informações do CEP 01001000, utilizando a ferramenta de linha de comando curl, pode-se executar o seguinte comando via terminal.

curl https://carteiro.github.io/ceps/data/01001000.json

O funcionamento das requisições trabalha como um pseudo Web Service, onde os dados existentes e atualizados são fornecidos através do protocolo HTTP. Caso determinado CEP não exista na base de dados, o código HTTP de resposta será 404, característica de documento inexistente pelo proprio GitHub Pages.

Você pode contribuir com este projeto, adicionando ou atualizando informações através de Patch Requests (PRs). Caso esteja interessado, por favor, acesse o arquivo CONTRIBUTING.md para mais detalhes sobre o assunto.

A criação deste projeto surgiu com a necessidade de criar uma base de dados atualizada para CEPs, independente de Correios ou qualquer tipo de Web Services.

Muitos projetos necessitam de informações sobre endereços a partir dos CEPs, todavia, nem todos possuem a capacidade de conexão com servidores que centralizam estes dados. Ainda, bases de dados offline podem ser adquiridas de empresas especializadas, porém nem sempre projetos de código-fonte aberto possuem capital para isto.

Tendo isto em mente, o atual projeto busca centralizar uma base de dados, independente de empresas, no formato de contribuição coletiva, onde os próprios usuários podem manter as informações atualizadas, disponibilizando-as em formato padronizado e código-fonte aberto.

Esta base de dados é opensource e está disponível sob a licença MIT, descrita no arquivo LICENSE.