Essa lib tem como propósito facilitar a vida de desenvolvedores brasileiros que precisam acessar dados de APIs abertas existentes no Brasil. A lib conta com uma classe para cada API, tendo esta classe métodos que referencia os endpoints da API, assim como as tipagens para cada um dos métodos.
- Qualquer API listada aqui está sujeita a limitações e regras que não são de responsabilidade desta lib, para mais informações sobre as limitações e regras de cada API, consulte a documentação oficial da mesma.
- Os sites e repositorios oficiais de cada API estão listados abaixo, para mais informações sobre cada uma delas, consulte a documentação oficial da mesma.
- Esta lib não tem como propósito substituir a documentação oficial de cada API, mas sim facilitar o acesso a mesma.
- A lib funciona tanto no browser quanto no node.
yarn add @brasil-interface/sdks
ou
npm install @brasil-interface/sdks
ou
pnpm install @brasil-interface/sdks
A documentação oficial da API pode ser encontrada aqui. Para usar a API é necessário criar uma conta e gerar um token de acesso, para mais informações sobre seu token de acesso, acesse este link.
Dado um CEP, retorna um objeto com as informações do endereço.
import { CepAbertoAPI } from '@brasil-interface/sdks';
const cepAberto = new CepAbertoAPI('token');
async function main() {
const endereco = await cepAberto.getCepByNumber('01001000');
console.log(endereco); // { cep: '01001-000', logradouro: 'Praça da Sé', complemento: 'lado ímpar', bairro: 'Sé', cidade: { ddd: '11', ibge: '3550308', nome: 'São Paulo' }, estado: { sigla: 'SP' }, altitude: 799.3333333333334, latitude: -23.550519, longitude: -46.633309 }
}
Dadas as coordenadas de latitude e longitude, retorna um objeto com as informações do endereço.
import { CepAbertoAPI } from '@brasil-interface/sdks';
const cepAberto = new CepAbertoAPI('token');
async function main() {
const endereco = await cepAberto.getCepByCoordinates(-23.550519, -46.633309);
console.log(endereco); // { cep: '01001-000', logradouro: 'Praça da Sé', complemento: 'lado ímpar', bairro: 'Sé', cidade: { ddd: '11', ibge: '3550308', nome: 'São Paulo' }, estado: { sigla: 'SP' }, altitude: 799.3333333333334, latitude: -23.550519, longitude: -46.633309 }
}
Dado o nome da cidade, estado, rua e bairro, retorna um objeto com as informações do endereço. A rua e bairro são opcionais.
import { CepAbertoAPI } from '@brasil-interface/sdks';
const cepAberto = new CepAbertoAPI('token');
async function main() {
const endereco = await cepAberto.getCepByAddress('SP', 'São Paulo', 'Rua João Ramalho', 'Perdizes');
console.log(endereco); // { cep: '05008-010', logradouro: 'Rua João Ramalho', complemento: 'até 999/1000', bairro: 'Perdizes', cidade: { ddd: '11', ibge: '3550308', nome: 'São Paulo' }, estado: { sigla: 'SP' }, altitude: 661.3333333333334, latitude: -23.537583, longitude: -46.680511 }
}
Dado o nome do estado, retorna um array com as cidades do estado. O nome do estado deve ser a sigla do estado em caixa alta.
import { CepAbertoAPI } from '@brasil-interface/sdks';
const cepAberto = new CepAbertoAPI('token');
async function main() {
const cidades = await cepAberto.getCitiesByState('SP');
console.log(cidades) // [{ nome: "Adamantina" }, { nome: "Adolfo" }, { nome: "Aguaí" }, { nome: "Águas da Prata" }, ...]
}
Se você possui uma lista de CEPs e deseja atualizar os dados deles, você pode usar este método para atualizar os dados de todos os CEPs de uma vez. O método retorna um array com os CEPs que foram atualizados.
import { CepAbertoAPI } from '@brasil-interface/sdks';
const cepAberto = new CepAbertoAPI('token');
async function main() {
const cepsAtualizados = await cepAberto.updateCeps(["01001-000", "01002-000", "01003-000"]);
console.log(cepsAtualizados) // ["01001-000", "01002-000"]
}
Leia o arquivo CONTRIBUTING.md no repositório principal.