lagoinha

Lagoinha-rs

Rust library that returns addresses from the Brazilian Postal Code (CEP)
using the following APIs: Correios, ViaCEP, Cepla

Readme in Português

Rust project inspired by https://github.com/IgorHalfeld/lagoinha used to retrieve Addresses from the Brazilian Postal Code (CEP)

✔️ - Contributions and reviews are appreciated !

Lagoinha is a package that uses public APIs to fetch addresses using the Brazilian Postal Code (CEP). This package cuncurrenlty calls all the supported APIs and returns the first result.

Diagram:

Why this name ?

It means "little pond". It is a Brazillian meme ! Check the videovídeo!

Instalation

lagoinha-rs = "0.2"

How to use it

use lagoinha;
use async_std;

fn main() {
    let addr = async_std::task::block_on(lagoinha::get_address("CEP_GOES_HERE"));
    println!("{:#?}", addr);
}

The fisrt method should be similar for any async runtime.

Or in a Async function (example using Tokio):

use lagoinha;
use tokio;

#[tokio::main]
async fn main() {
    let addr = lagoinha::get_address("CEP_GOES_HERE", None).await;
    println!("{:#?}", addr);
}

Run Examples

Check the examples folder ! To run them, use the commands below.

# these examples can be run with a specific CEP (or leave blank for default value)
cargo run --example get_address 20940040
cargo run --example get_address_tokio 20940040
cargo run --example standalone_services 20940040

Note on the HTTP Client

This library uses isahc as its http client because:

1. It works in any async backend, and

2. It offers a configuration option for Title-Case headers (necessary for CepLá)

Todo

• Get Started
• Viacep service
• Correios service
• CepLá service
• Separate Two languages in README.md
• Documentation
• Invest in better error handling
• Unhappy path testing
• Validate input
• Different compilation features
• Abstractions: this will allow for mocking, and testing all paths without calls to the APIs
• Allow user to implement custom services, and opt out of any of the defaults