node package manager


A small wrapper around the Ziptastic ZIP lookup service


Use the Ziptastic API to retrieve city and state information from a zip code.

Install from npm:

npm install ziptastic

The library exposes the ZIP parser function directly. It returns a promise, but will also call a node-style callback if one is passed in.

var ziptastic = require('ziptastic');
var query = {
zip: '10000',
country: 'US'

Using promises:

ziptastic(query).then(function(location) {
// location => {city: "New York City", state: "New York", country: "US"} 

Using callbacks:

ziptastic(query, function(errlocation) {
// location => {city: "New York City", state: "New York", country: "US"} 

The function expects an object with properties zip and country. If no country is provided, it defaults to US. If the options argument is a number or numeric string, the library will assume it is a zip code in the US. All of the following are equivalent to the original query:

ziptastic({zip: '10000'});

You can construct custom instances with your own endpoint if you're running the ziptastic application on your own server. The constructor is stored on the parser function:

var ziptastic = ziptastic.create('');

ziptastic.create returns the parse function bound to an instance with your endpoint. You can also get full access to the instance using:

var ziptastic = new ziptastic.Ziptastic([endpoint]);

The library will automatically convert HTTP status codes >= 400 into errors. Catch them using promises:

ziptastic('100').catch(function(err) {
err instanceof Error // => true 

Or callbacks:

ziptastic('100', function(errlocation) {
err instanceof Error // => true 

The error stores the raw response object from request as err.response for easy debugging.

npm test

MIT License