wlads / ceps

Brazil's CEP as service

ceps

Fala português?

A (web) service that exposes Correios' individual CEP search page as a consumable API.

It uses cheerio for scraping, Express for HTTP and MongoDB for database.

How it works

When a request is made, the service retrieves from the database the address info of the given CEP.

If the address exists in the database and if the record isn't a month old, responds it. End of the request.

If there isn't such address or if it's more than a month old, scraps a fresh one from Correios website, saves on the database, and then responds it. End of the request.

Usage

You can either npm install ceps -g, clone this repository and run bin/de-busca.js or deploy to Heroku:

The service expects a GET request at /{desired cep}.

For instance, a GET to /30130010 may return:

{
    "cep": "30130010",
    "logradouro": "Praça Sete de Setembro",
    "bairro": "Centro",
    "localidade": "Belo Horizonte",
    "uf": "MG"
}

400 means that the given CEP was malformed or that the required authorization wasn't provided. 403 means that a wrong authorization was provided. 500 means that something bad happened at the server.

And, of course, 200 if everything went smoothly. 204 if the request was OK but nothing was found for the given CEP.

Here's how to request from the cli:

$ curl example.org/30130010 -i -u "username:password"

Configuration

There are two environment variables to set:

• MONGO: a MongoDB connection string;
• AUTH: basic authentication credentials in the format user:pass;
• PORT: port to listen on (optional, assumes 80).

A careful hack

• Correios allows the whole site to be crawled by search bots;
• There is no device for impeding a non-human access (such as a CAPTCHA);
• We don't bulk request (a single request here is a single request there);
• We avoid requesting if possible (we only scrap month old records, else we just use our database).