|
1 |
| -# geo2zip [](https://travis-ci.org/blakek/geo2zip) |
| 1 | +# geo2zip |
2 | 2 |
|
3 |
| -> Translates latitude / longitude geolocations to the nearest corresponding U.S. zip code |
| 3 | +> 🌎🔍 Quickly find the the nearest U.S. ZIP codes to a latitude/longitude geolocation using k-nearest neighbors |
4 | 4 |
|
5 |
| -Takes a geolocation and returns the nearest US ZIP code. |
| 5 | +[][1] |
6 | 6 |
|
7 |
| -⚠️ **NOTE:** this may not return the actual ZIP code of the location; it returns the ZIP code where the approximate center of the ZIP is nearest the location. |
| 7 | +Takes a geolocation and returns the nearest US ZIP codes. |
| 8 | + |
| 9 | +⚠️ **NOTE:** The top result may not return the _actual_ ZIP code containing the |
| 10 | +location. This library returns the ZIP code where the approximate center of the |
| 11 | +ZIP is nearest the given location. Larger ZIP code areas may show lower in the |
| 12 | +results when searching nearby points because the center can be so far away. If |
| 13 | +you're relying on something as inaccurate as ZIP codes, the top result is likely |
| 14 | +close enough. |
| 15 | + |
| 16 | +Also, ZIP codes change. They change in shape and location. New ones are |
| 17 | +created and old ones are removed. They're even recycled. If you know of a |
| 18 | +reliable, more up-to-date list of ZIP codes, please let us know by opening an |
| 19 | +issue. |
| 20 | + |
| 21 | +**Can I use this in the browser?** Yes but please don't. This is made to run on |
| 22 | +a Node.js server. This depends on a roughly [2 MB list of US ZIP |
| 23 | +codes][2] and sorts those in-memory. Please |
| 24 | +don't do that to my phone. If you're experimenting or know what you're doing, |
| 25 | +use this wherever and however it works for you. |
| 26 | + |
| 27 | +**Isn't sorting and filtering on a 2MB file slow in JavaScript?** No. A lookup |
| 28 | +is created when the main file is imported/required. After the lookup is created, |
| 29 | +you should be able to run the examples in this README millions of times per |
| 30 | +second; showing output would be the limit. The tradeoff is your server may take |
| 31 | +a 1-2 seconds longer to start up initially (e.g. from `npm run start`). |
| 32 | + |
| 33 | +## Install |
| 34 | + |
| 35 | +With [Yarn](https://yarnpkg.com/en/) or [npm](https://npmjs.org/) installed, |
| 36 | +run: |
| 37 | + |
| 38 | +```shell |
| 39 | +yarn add geo2zip |
| 40 | + |
| 41 | +# ...or, if using `npm` |
| 42 | +npm install geo2zip |
| 43 | +``` |
8 | 44 |
|
9 | 45 | ## Usage
|
10 | 46 |
|
11 | 47 | Get the nearest ZIP to a location:
|
12 | 48 |
|
13 | 49 | ```js
|
14 |
| -const geo2zip = require('geo2zip') |
| 50 | +import geo2zip from 'geo2zip' |
15 | 51 |
|
16 |
| -const somewhere = { |
| 52 | +const location = { |
17 | 53 | latitude: 34.659698,
|
18 | 54 | longitude: -88.242903
|
19 | 55 | }
|
20 | 56 |
|
21 |
| -geo2zip(somewhere).then(zip => { |
22 |
| - console.log(zip) // '38873' |
23 |
| -}) |
| 57 | +const closestZip = await geo2zip(location) |
| 58 | + |
| 59 | +console.log(closestZip) // ['38873'] |
24 | 60 | ```
|
25 | 61 |
|
26 |
| -## Install |
| 62 | +Get the closest 5 ZIPs to a location: |
27 | 63 |
|
28 |
| -With [npm](https://npmjs.org/) installed, run |
| 64 | +```js |
| 65 | +import geo2zip from 'geo2zip' |
29 | 66 |
|
| 67 | +const location = { |
| 68 | + latitude: 34.659698, |
| 69 | + longitude: -88.242903 |
| 70 | +} |
| 71 | + |
| 72 | +await geo2zip(location, { limit: 5 }) |
| 73 | +// [ '38873', '38838', '38827', '38859', '38852' ] |
30 | 74 | ```
|
31 |
| -$ npm install geo2zip |
32 |
| -``` |
| 75 | + |
| 76 | +## API |
| 77 | + |
| 78 | +### `geo2zip(location, options)` |
| 79 | + |
| 80 | +#### location |
| 81 | + |
| 82 | +Type: `Object` |
| 83 | + |
| 84 | +A geolocation with valid `latitude` and `longitude` properties. |
| 85 | + |
| 86 | +#### options |
| 87 | + |
| 88 | +Type: `Object` |
| 89 | + |
| 90 | +Properties: |
| 91 | + |
| 92 | +- `limit` - the number of results to return |
| 93 | + - Type: `Number` |
| 94 | + - Default: `1` |
33 | 95 |
|
34 | 96 | ## See Also
|
35 | 97 |
|
36 |
| - * [`blakek/standardize-geolocation`](https://github.com/blakek/standardize-geolocation) - takes geolocations of different formats and outputs a standardized version |
37 |
| - * [`blakek/us-zips`](https://github.com/blakek/us-zips) - a list of US ZIP codes and their geolocations |
| 98 | +- [`standardize-geolocation`][3] - takes geolocations of different formats and |
| 99 | + outputs a standardized version |
| 100 | +- [`sphere-knn`][4] - find the k nearest neighbors for points on a sphere |
| 101 | +- [`us-zips`][2] - a list of US ZIP codes and their geolocations |
38 | 102 |
|
39 | 103 | ## License
|
40 | 104 |
|
41 | 105 | MIT
|
| 106 | + |
| 107 | +[1]: https://travis-ci.org/blakek/geo2zip |
| 108 | +[2]: https://github.com/blakek/us-zips |
| 109 | +[3]: https://github.com/blakek/standardize-geolocation |
| 110 | +[4]: https://github.com/darkskyapp/sphere-knn |
0 commit comments