Node ViaCep

A wrapper to work with the ViaCep Web API.

Browser Support

This library relies on Fetch API. And this API is supported in the following browsers.

39+ ✔	42+ ✔	29+ ✔	10.1+ ✔	Nope ✘

Dependencies

This library depends on fetch to make requests to the Spotify Web API. For environments that don't support fetch, you'll need to provide a polyfill to browser or polyfill to Node.

more info on how to use node-fech.

Installation

$ npm install node-viacep --save

How to use

ES6

// to import a specific method
import ViaCep from 'node-viacep';
 
const viacep = new ViaCep({
  type: 'json'
})
 

CommonJS

const ViaCep = require('node-viacep').default;
 
const viacep = new ViaCep({
  type: 'json'
})

UMD in Browser

<!-- to import non-minified version -->
<script src="viacep.umd.js"></script>
 
<!-- to import minified version -->
<script src="viacep.umd.min.js"></script>

After that the library will be available to the Global as ViaCep. Follow an example:

import ViaCep from 'node-viacep';
 
global.fetch = require('node-fetch');
 
const viacep = new ViaCep({
  type: 'json'
})
 
const address = viacep.zipCod.getZip('29010250');
 
address
  .then(data => data.json())
  .then(data => console.log(data));

Types and returns

The types to use in constructor

JSON

//use in zipCod and address methods
 
const viacep = new ViaCep({
  type: 'json'
})
 
//return
{ cep: '29010-250',
  logradouro: 'Rua Alberto de Oliveira Santos',
  complemento: '',
  bairro: 'Centro',
  localidade: 'Vitória',
  uf: 'ES',
  unidade: '',
  ibge: '3205309',
  gia: ''
}

XML

//use in zipCod and address methods
const viacep = new ViaCep({
  type: 'xml'
})
 
//return
<?xml version="1.0" encoding="UTF-8"?>
<xmlcep>
  <cep>29010-250</cep>
  <logradouro>Rua Alberto de Oliveira Santos</logradouro>
  <complemento></complemento>
  <bairro>Centro</bairro>
  <localidade>Vitória</localidade>
  <uf>ES</uf>
  <unidade></unidade>
  <ibge>3205309</ibge>
  <gia></gia>
</xmlcep>

PIPED

//just use in zipCod methods
 
const viacep = new ViaCep({
  type: 'piped'
})
 
//return
cep:29010-250|logradouro:Rua Alberto de Oliveira Santos|complemento:|bairro:Centro|localidade:Vitória|uf:ES|unidade:|ibge:3205309|gia:

QUERTY

//just use in zipCod methods
const viacep = new ViaCep({
  type: 'json'
})
 
//return
cep=29010-250&logradouro=Rua+Alberto+de+Oliveira+Santos&complemento=&bairro=Centro&localidade=Vit%C3%B3ria&uf=ES&unidade=&ibge=3205309&gia=

Methods

zipCod methods

Follow the methods that the library provides.

zipCod.getZip(query)

Search for informations about zipcode with provided query. Test in ViaCep Api.

Arguments

Argument	Type	Options
query	string	'Any search query'

Example

this method returns the type specified in the constructor

viacep.zipCod.getZip('29010250')
  .then(data => data.text())
  .then(data => console.log(data));

zipCod.getJson(query)

Search for informations about zipcode with provided query. Test in ViaCep Api.

Arguments

Argument	Type	Options
query	string	'Any search query'

Example

this method returns a json

viacep.zipCod.getJson('29010250')
  .then(data => data.json())
  .then(data => console.log(data));

zipCod.getXml(query)

Search for informations about zipcode with provided query. Test in ViaCep Api.

Arguments

Argument	Type	Options
query	string	'Any search query'

Example

this method returns an xml

viacep.zipCod.getXml('29010250')
  .then(data => data.text())
  .then(data => console.log(data));

zipCod.getPiped(query)

Search for informations about zipcode with provided query. Test in ViaCep Api.

Arguments

Argument	Type	Options
query	string	'Any search query'

Example

this method returns a piped

viacep.zipCod.getPiped('29010250')
  .then(data => data.text())
  .then(data => console.log(data));

zipCod.getQuerty(query)

Search for informations about zipcode with provided query. Test in ViaCep web API.

Arguments

Argument	Type	Options
query	string	'Any search query'

Example

this method returns a querty

viacep.zipCod.getQuerty('29010250')
  .then(data => data.text())
  .then(data => console.log(data));

address methods

address.getJson(ids)

Search for informations about some address with all id's. Test in ViaCep web APi.

Arguments

Argument	Type	Options
ids	Array of strings	['UF', 'city', 'street']

Example

this method returns a json

viacep.address.getJson('ES', 'vitoria', 'alberto de')
  .then(data => data.json())
  .then(data => console.log(data));

address.getXml(ids)

Search for informations about some address with all id's. Test in ViaCep web APi..

Arguments

Argument	Type	Options
ids	Array of strings	['UF', 'city', 'street']

Example

this method returns an xml

viacep.address.getXml('ES', 'vitoria', 'alberto de')
  .then(data => data.text())
  .then(data => console.log(data));

Contributing

Please read CONTRIBUTING.md file for details

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

Adriano Reis

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details