A small wrapper around the Ziptastic ZIP lookup service

npm install ziptastic
10 downloads in the last week
13 downloads in the last month

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

npm loves you