https://github.com/simplisticated/zip-monster
The most reliable solution for working with US zip codes. Free replacement for paid APIs.
https://github.com/simplisticated/zip-monster
postal-code united-states zipcode
Last synced: 8 months ago
JSON representation
The most reliable solution for working with US zip codes. Free replacement for paid APIs.
- Host: GitHub
- URL: https://github.com/simplisticated/zip-monster
- Owner: simplisticated
- License: mit
- Created: 2022-06-10T07:33:33.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-21T06:27:10.000Z (over 1 year ago)
- Last Synced: 2025-05-08T17:03:59.905Z (8 months ago)
- Topics: postal-code, united-states, zipcode
- Language: TypeScript
- Homepage:
- Size: 3.91 MB
- Stars: 98
- Watchers: 1
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## 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:
```typescript
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=
```
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:
```typescript
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:
```typescript
{
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:
```typescript
const zipCodes = ZipMonster.find({
zip: "91360"
});
const city = zipCodes[0].city // Thousand Oaks
```
----
### Search by city
You can also search by city:
```typescript
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:
```typescript
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
```typescript
ZipMonster.find({
county: "Vermont"
})
```
or
```typescript
ZipMonster.find({
county: {
value: "vermont",
caseSensitive: false,
wholeMatch: true
}
})
```
----
### Search by state
```typescript
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:
```typescript
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
```
----
### Combine search parameters
You can also combine search parameters with each other:
```typescript
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:
```typescript
// 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**:
```typescript
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](./LICENSE) file for more info.