node package manager


Ziptastic Build Status NPM version

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

Getting Started

Install from npm:

npm install ziptastic

Executing Queries

ziptastic(options, [callback]) -> promise

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(err, location) {
    // 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'});

Custom Instances

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]);

Handling Errors

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(err, location) {
    err instanceof Error // => true 

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


npm test


MIT License