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