Skip to content

The most reliable solution for working with US zip codes. Free replacement for paid APIs.

License

Notifications You must be signed in to change notification settings

bmiller59/zip-monster

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

At a Glance

ZipMonster is a library that simplifies work with zip codes and addresses in the United States. This solution is a reliable replacement for paid APIs that you can find on the Internet.

How to Get Started

Type in Terminal:

npm install --save @simplisticated/zip-monster

or, if you prefer yarn over npm, type:

yarn add @simplisticated/zip-monster

Then add import instruction to your code:

import ZipMonster from '@simplisticated/zip-monster'

Requirements

It's strongly recommended to add NODE_OPTIONS flag to your .env file:

NODE_OPTIONS=--max-old-space-size=<AVAILABLE RAM SIZE IN MB>

For example, if you have 2GB RAM:

NODE_OPTIONS=--max-old-space-size=2048

Usage

Everything starts from ZipMonster object.

The main method is ZipMonster.find. It's a super flexible way to search the information.


Search by zip code

If you know exactly what zip code you're looking for, simply write:

ZipMonster.find({
    zip: "91360"
})

In response, you will receive an array of ZipInformation objects that correspond to your search request. Each object includes the following data:

{
    stateCode: "CA",
    city: "Thousand Oaks",
    county: "Ventura",
    zip: "91360",
    zipType: "Non-Unique",
    location: {
        latitude: 34.2090940366232,
        longitude: -118.875059125606
    }
}

To get city name, you can write:

const zipCodes = ZipMonster.find({
    zip: "91360"
});
const city = zipCodes[0].city // Thousand Oaks

Search by city

You can also search by city:

ZipMonster.find({
    city: "Thousand Oaks"
})

The expression above will return array of ZipInformation objects related to Thousand Oaks.

Also, you can search by part of city name:

ZipMonster.find({
    city: {
        value: "THOUSAND",
        caseSensitive: false,
        wholeMatch: false
    }
})

which returns zip code information for all cities that contain THOUSAND in the name.


Search by county

ZipMonster.find({
    county: "Vermont"
})

or

ZipMonster.find({
    county: {
        value: "vermont",
        caseSensitive: false,
        wholeMatch: true
    }
})

Search by state

ZipMonster.find({
    stateCode: "CA"
})

Search by location

Let's find cities that are further to north than Palo Alto. That's a very simple task:

const PaloAlto = ZipMonster.find({
    city: "Palo Alto",
    stateCode: "CA",
    withLocationOnly: true
})[0];
const placesFurtherToNorth = ZipMonster.find({
    location: {
        latitude: {
            value: PaloAlto.location!.latitude,
            direction: "to-north"
        }
    }
});
placesFurtherToNorth.length // 21404 places are further to north than Palo Alto

Search by meter radius from location

const inRadius = ZipMonster.find({
    location: {
        latitude: {
            value: PaloAlto.location!.latitude,
            direction: 'radius'
        },
        longitude: {
            value: PaloAlto.location!.longitude,
            direction: "radius"
        },
        radius: 50 * 1000 // 50 km
    }
})

Combine search parameters

You can also combine search parameters with each other:

const result = ZipMonster.find({
    city: {
        value: "THOUSAND",
        caseSensitive: false,
        wholeMatch: false
    },
    county: {
        value: "Vent",
        caseSensitive: false,
        wholeMatch: false
    },
    stateCode: "CA"
})
const city = result[0].city // Thousand Oaks

What about more complicated logic?

Let's find all zip codes between Austin and Oklahoma City:

// Take the first zip code in Austin
const Austin = ZipMonster.find({
    city: "Austin",
    stateCode: "TX",
    withLocationOnly: true
})[0];

// Find places to north and east from Austin
const placesToNorthFromAustin = ZipMonster.find({
    location: {
        latitude: {
            value: Austin.location!.latitude,
            direction: "to-north"
        },
        longitude: {
            value: Austin.location!.longitude,
            direction: "to-east"
        }
    }
});

// Take the first zip code in Oklahoma City
const OklahomaCity = ZipMonster.find({
    city: "Oklahoma City",
    stateCode: "OK",
    withLocationOnly: true
})[0];

// Find places to south and west from Oklahoma City, but stop at Austin
const placesBetweenAustinAndOklahomaCity = ZipMonster.find({
    location: {
        latitude: {
            value: OklahomaCity.location!.latitude,
            direction: "to-south"
        },
        longitude: {
            value: OklahomaCity.location!.longitude,
            direction: "to-west"
        }
    },
    source: placesToNorthFromAustin
});

placesBetweenAustinAndOklahomaCity.length // 79 zip codes found

Other cases

If you don't use any filter with the method, it will return information about all existing zip codes:

const zipCodes = ZipMonster.find();
zipCodes.length // more than 40k zip codes in the array

License

ZipMonster is available under the MIT license. See the LICENSE file for more info.

About

The most reliable solution for working with US zip codes. Free replacement for paid APIs.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 100.0%