{"id":19050495,"url":"https://github.com/blakek/geo2zip","last_synced_at":"2026-03-17T01:43:02.292Z","repository":{"id":13893496,"uuid":"75233898","full_name":"blakek/geo2zip","owner":"blakek","description":"🌎🔍 Quickly find the the nearest U.S. ZIP codes to a latitude/longitude geolocation using k-nearest neighbors","archived":false,"fork":false,"pushed_at":"2023-07-18T19:37:32.000Z","size":1100,"stargazers_count":12,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T05:03:27.064Z","etag":null,"topics":["geolocation","hacktoberfest","javascript","latitude","longitude","zipcode","zipcodes"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blakek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-30T22:46:29.000Z","updated_at":"2025-04-07T20:09:56.000Z","dependencies_parsed_at":"2024-06-19T02:07:20.220Z","dependency_job_id":null,"html_url":"https://github.com/blakek/geo2zip","commit_stats":{"total_commits":85,"total_committers":6,"mean_commits":"14.166666666666666","dds":0.7294117647058824,"last_synced_commit":"c5293b62dcb1fb22cc8430c6a19d51994602bba9"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fgeo2zip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fgeo2zip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fgeo2zip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blakek%2Fgeo2zip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blakek","download_url":"https://codeload.github.com/blakek/geo2zip/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249375338,"owners_count":21260158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geolocation","hacktoberfest","javascript","latitude","longitude","zipcode","zipcodes"],"created_at":"2024-11-08T23:15:07.276Z","updated_at":"2026-03-17T01:42:57.218Z","avatar_url":"https://github.com/blakek.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# geo2zip\n\n\u003e 🌎🔍 Quickly find the the nearest U.S. ZIP codes to a latitude/longitude geolocation using k-nearest neighbors\n\n[![Travis](https://img.shields.io/travis/blakek/geo2zip/master.svg)][1]\n\nTakes a geolocation and returns the nearest US ZIP codes.\n\n⚠️ **NOTE:** The top result may not return the _actual_ ZIP code containing the\nlocation. This library returns the ZIP code where the approximate center of the\nZIP is nearest the given location. Larger ZIP code areas may show lower in the\nresults when searching nearby points because the center can be so far away. If\nyou're relying on something as inaccurate as ZIP codes, the top result is likely\nclose enough.\n\nAlso, ZIP codes change. They change in shape and location. New ones are\ncreated and old ones are removed. They're even recycled. If you know of a\nreliable, more up-to-date list of ZIP codes, please let us know by opening an\nissue.\n\n**Can I use this in the browser?** Yes but please don't. This is made to run on\na Node.js server. This depends on a roughly [2 MB list of US ZIP\ncodes][2] and sorts those in-memory. Please\ndon't do that to my phone. If you're experimenting or know what you're doing,\nuse this wherever and however it works for you.\n\n**Isn't sorting and filtering on a 2MB file slow in JavaScript?** No. A lookup\nis created when the main file is imported/required. After the lookup is created,\nyou should be able to run the examples in this README millions of times per\nsecond; showing output would be the limit. The tradeoff is your server may take\na 1-2 seconds longer to start up initially (e.g. from `npm run start`).\n\n## Install\n\nWith [Yarn](https://yarnpkg.com/en/) or [npm](https://npmjs.org/) installed,\nrun:\n\n```shell\nyarn add geo2zip\n\n# ...or, if using `npm`\nnpm install geo2zip\n```\n\n## Usage\n\nGet the nearest ZIP to a location:\n\n```js\nimport geo2zip from \"geo2zip\";\n\nconst location = {\n  latitude: 34.659698,\n  longitude: -88.242903,\n};\n\nconst closestZip = await geo2zip(location);\n\nconsole.log(closestZip); // ['38873']\n```\n\nGet the closest 5 ZIPs to a location:\n\n```js\nimport geo2zip from \"geo2zip\";\n\nconst location = {\n  latitude: 34.659698,\n  longitude: -88.242903,\n};\n\nawait geo2zip(location, { limit: 5 });\n// [ '38873', '38838', '38827', '38859', '38852' ]\n```\n\n## API\n\n### `geo2zip(location, options)`\n\n#### location\n\nType: `Object`\n\nA geolocation with valid `latitude` and `longitude` properties.\n\n#### options\n\nType: `Object`\n\nProperties:\n\n- `limit` - the number of results to return\n  - Type: `Number`\n  - Default: `1`\n\n## See Also\n\n- [`standardize-geolocation`][3] - takes geolocations of different formats and\n  outputs a standardized version\n- [`sphere-knn`][4] - find the k nearest neighbors for points on a sphere\n- [`us-zips`][2] - a list of US ZIP codes and their geolocations\n\n## License\n\nMIT\n\n[1]: https://travis-ci.org/blakek/geo2zip\n[2]: https://github.com/blakek/us-zips\n[3]: https://github.com/blakek/standardize-geolocation\n[4]: https://github.com/darkskyapp/sphere-knn\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakek%2Fgeo2zip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblakek%2Fgeo2zip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblakek%2Fgeo2zip/lists"}