Merge pull request #41 from blakek/data-update-2022-09

Data update for 2022-09

.github/workflows/publish.yml

@@ -11,9 +11,9 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
-          node-version: '16'
-          cache: 'yarn'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "16"
+          cache: "yarn"
+          registry-url: "https://registry.npmjs.org"
       - run: yarn install
       - run: yarn publish
         name: Publish to npm

.github/workflows/run-tests.yml

@@ -8,16 +8,16 @@ jobs:
       fail-fast: true
       matrix:
         node_version:
-          - '14'
-          - '16'
-          - '18'
+          - "14"
+          - "16"
+          - "18"
 
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         name: Use Node.js v${{matrix.node_version}}
         with:
           node-version: ${{matrix.node_version}}
-          cache: 'yarn'
+          cache: "yarn"
       - run: yarn install
       - run: yarn test

README.md

@@ -2,47 +2,62 @@
 
 > A list of US ZIP codes and their geolocations
 
-I needed a list of ZIP codes, and the [US Census Bureau had one][1].
+A list of United States ZIP Codes based on the [US Census Bureau's ZIP Code Tabulation Areas (ZCTAs)][4].
+
+:information_desk_person: Before using ZIP codes, there's helpful points to know:
+
+- USPS ZIP codes are short and memorable, but they aren't very good for geolocation. Their main use is for local mail routes.
+- ZIP codes change with mail routes. They're reused, sometimes for different locations.
+- The ZIP used for mail delivery may not be the closest (or even second closest) ZIP by linear distance. This may be due to terrain, political borders, etc.
+- One physical location could be served by multiple ZIP codes
+
+:package: This package:
+
+uses [ZIP Code Tabulation Areas (ZCTAs)][6]
+: Some ZIP codes used by the USPS are not included, such as those with no or very few residential addresses.
+
+uses the center of the ZCTA polygon
+: This keeps the package smaller, more performant, and simpler to use. ZIP codes aren't very good for geolocation anyway, so we chose to keep the amount of data loaded in memory to a minimum.
+
+stays up-to-date with the Census Bureau's data
+: After new data is published, this package is updated soon. Unlike several other ZIP lists, this one purges outdated information.
 
 ## Usage
 
-Example: get the nearest zip to a geolocation
+Example: get the nearest ZIP to a geolocation
+
+> :information_source: If you need the nearest ZIPs for a geolocation, check out [`geo2zip`][2]. It is much faster than the demo below and uses this package.
 
 ```javascript
-const geolib = require('geolib')
-const usZips = require('us-zips')
+const geolib = require("geolib");
+const usZips = require("us-zips/array");
 
 const somewhere = {
-  lat: 33.1234,
-  lng: -88.4321
-}
+	lat: 33.1234,
+	lng: -88.4321,
+};
 
-geolib.findNearest(somewhere, usZips) // { distance: 12834, key: '39341' }
+geolib.findNearest(somewhere, usZips);
+//» { latitude: 33.088581, longitude: -88.556133, zipCode: "39341" }
 ```
 
-:information_source: If you need the nearest ZIPs for a geolocation, see if
-[`geo2zip`][2] fits your needs. It is much faster than the demo above and uses
-this package as a source.
-
 ## Data Formats
 
 ### Default (Object)
 
-The default export returns an object. The object's keys are each ZIP code and
-values are objects with latitude and longitude properties.
+The default export returns an object. The object's keys are each ZIP code and values are objects with latitude and longitude properties.
 
 ```javascript
 const usZips = require('us-zips')
 
 console.log(usZips['54301'])
-// { latitude: 44.480778, longitude: -88.016063 }
+//» { latitude: 44.480778, longitude: -88.016063 }
 
 // Shape
 {
-  '54301': {
-    latitude: 44.480778,
-    longitude: -88.016063
-  }
+  …
+  '54301': { latitude: 44.480778, longitude: -88.016063 }
+  …
 }
 ```
 
@@ -52,17 +67,17 @@ console.log(usZips['54301'])
 const usZips = require('us-zips/array')
 
 console.log(usZips.find(zip => zip.zipCode === '37214'))
-// { latitude: 36.162189, longitude: -86.670867, zipCode: '37214' }
+//» { latitude: 36.162189, longitude: -86.670867, zipCode: '37214' }
 
 // Shape
 [
-  ...
+  …
   {
     latitude: 36.162189,
     longitude: -86.670867,
     zipCode: '37214'
   },
-  ...
+  …
 ]
 ```
 
@@ -72,63 +87,57 @@ console.log(usZips.find(zip => zip.zipCode === '37214'))
 const usZips = require('us-zips/key-value')
 
 console.log(usZips.find(([key, value]) => key === '10001'))
-// ['10001', { latitude: 40.750634, longitude: -73.997176 }]
+//» ['10001', { latitude: 40.750634, longitude: -73.997176 }]
 
 // Shape
 [
-  ...
-  ['10001', {
-    latitude: 40.750634,
-    longitude: -73.997176
-  }],
-  ...
+  …
+  ['10001', { latitude: 40.750634, longitude: -73.997176 }],
+  …
 ]
 ```
 
 ### Map
 
 ```javascript
-const usZips = require('us-zips/map')
+const usZips = require("us-zips/map");
 
-console.log(usZips.get('90210'))
-// { latitude: 34.100517, longitude: -118.41463 }
+console.log(usZips.get("90210"));
+//» { latitude: 34.100517, longitude: -118.41463 }
 ```
 
 ## Install
 
-With [Yarn](https://yarnpkg.com/en/) or [npm](https://npmjs.org/) installed,
-run:
+With [Yarn](https://yarnpkg.com/en/) or [npm](https://npmjs.org/) installed, run:
 
 ```shell
-yarn add us-zips
+yarn add us-zips@2022.09
 
 # ...or, if using `npm`
-npm install us-zips
+npm install us-zips@2022.09
 ```
 
-:information_source: **NOTE:** Due to ZIP codes always changing, this package
-uses calendar versioning (aka [CalVer][5]). This means each year will have a
-separate "major" version from npm and Yarn's perspective.
+:information_source: **NOTE:** Due to ZIP codes always changing, this package uses calendar versioning (aka [CalVer][5]). This means each year will have a separate "major" version from npm and Yarn's perspective. However, breaking changes could occur on minor versions. We suggest pinning to the minor version you want to use (e.g. `yarn add us-zips@2022.09`).
 
 ## Acknowledgments
 
-Data for ZIP codes and their geolocations was generated from [this file][1],
-which can be downloaded from the [US Census Bureau map data
-page][4].
+Data for ZIP codes and their geolocations was generated from [this file][1], which can be downloaded from the [US Census Bureau map data page][4].
 
 ## See Also
 
 - [`blakek/geo2zip`][2] - get the nearest zip code from a geolocation
 - [`blakek/standardize-geolocation`][3] - takes geolocations of different
   formats and outputs a standardized version
 - [US Census Bureau - map data page][4]
+- [Information about ZCTAs][6]
 
 ## License
 
 MIT
 
-[1]: https://www2.census.gov/geo/docs/maps-data/data/gazetteer/2021_Gazetteer/2021_Gaz_zcta_national.zip
+[1]: https://www2.census.gov/geo/docs/maps-data/data/gazetteer/2022_Gazetteer/2022_Gaz_zcta_national.zip
 [2]: https://github.com/blakek/geo2zip
 [3]: https://github.com/blakek/standardize-geolocation
 [4]: https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.html
 [5]: https://calver.org/
+[6]: https://www.census.gov/programs-surveys/geography/guidance/geo-areas/zctas.html

__tests__/array.js

@@ -1,17 +1,17 @@
-const test = require('ava').default
-const zipCount = require('../zipCount')
-const zipArray = require('../array')
+const test = require("ava").default;
+const zipCount = require("../zipCount");
+const zipArray = require("../array");
 
-test('exports the correct number of zips', t => {
-  t.is(zipArray.length, zipCount)
-})
+test("exports the correct number of zips", (t) => {
+	t.is(zipArray.length, zipCount);
+});
 
-test('exports the expected format', t => {
-  t.true(Array.isArray(zipArray))
+test("exports the expected format", (t) => {
+	t.true(Array.isArray(zipArray));
 
-  t.is(typeof zipArray[0], 'object')
+	t.is(typeof zipArray[0], "object");
 
-  t.truthy(zipArray[0].latitude)
-  t.truthy(zipArray[0].longitude)
-  t.truthy(zipArray[0].zipCode)
-})
+	t.truthy(zipArray[0].latitude);
+	t.truthy(zipArray[0].longitude);
+	t.truthy(zipArray[0].zipCode);
+});

__tests__/key-value.js

@@ -1,17 +1,17 @@
-const test = require('ava').default
-const zipCount = require('../zipCount')
-const zipKeyValue = require('../key-value')
+const test = require("ava").default;
+const zipCount = require("../zipCount");
+const zipKeyValue = require("../key-value");
 
-test('exports the correct number of zips', t => {
-  t.is(zipKeyValue.length, zipCount)
-})
+test("exports the correct number of zips", (t) => {
+	t.is(zipKeyValue.length, zipCount);
+});
 
-test('exports the expected format', t => {
-  t.true(Array.isArray(zipKeyValue))
+test("exports the expected format", (t) => {
+	t.true(Array.isArray(zipKeyValue));
 
-  const [zipCode, location] = zipKeyValue[0]
+	const [zipCode, location] = zipKeyValue[0];
 
-  t.truthy(zipCode)
-  t.truthy(location.latitude)
-  t.truthy(location.longitude)
-})
+	t.truthy(zipCode);
+	t.truthy(location.latitude);
+	t.truthy(location.longitude);
+});

__tests__/map.js

@@ -1,16 +1,16 @@
-const test = require('ava').default
-const zipCount = require('../zipCount')
-const zipMap = require('../map')
+const test = require("ava").default;
+const zipCount = require("../zipCount");
+const zipMap = require("../map");
 
-test('exports the correct number of zips', t => {
-  t.is(zipMap.size, zipCount)
-})
+test("exports the correct number of zips", (t) => {
+	t.is(zipMap.size, zipCount);
+});
 
-test('exports the expected format', t => {
-  t.true(zipMap instanceof Map)
+test("exports the expected format", (t) => {
+	t.true(zipMap instanceof Map);
 
-  const testZip = zipMap.get('38873')
+	const testZip = zipMap.get("38873");
 
-  t.truthy(testZip.latitude)
-  t.truthy(testZip.longitude)
-})
+	t.truthy(testZip.latitude);
+	t.truthy(testZip.longitude);
+});

__tests__/object.js

@@ -1,18 +1,18 @@
-const test = require('ava').default
-const zipCount = require('../zipCount')
-const usZips = require('../object')
+const test = require("ava").default;
+const zipCount = require("../zipCount");
+const usZips = require("../object");
 
-test('exports the correct number of zips', t => {
-  const numberExported = Object.keys(usZips).length
-  t.is(numberExported, zipCount)
-})
+test("exports the correct number of zips", (t) => {
+	const numberExported = Object.keys(usZips).length;
+	t.is(numberExported, zipCount);
+});
 
-test('exports the expected format', t => {
-  t.is(typeof usZips, 'object')
+test("exports the expected format", (t) => {
+	t.is(typeof usZips, "object");
 
-  const testZip = usZips['37214']
+	const testZip = usZips["37214"];
 
-  t.is(typeof testZip, 'object')
-  t.truthy(testZip.latitude)
-  t.truthy(testZip.longitude)
-})
+	t.is(typeof testZip, "object");
+	t.truthy(testZip.latitude);
+	t.truthy(testZip.longitude);
+});

array.d.ts

@@ -1,8 +1,8 @@
-import { Geolocation, ZIPCode } from '.'
+import {Geolocation, ZIPCode} from ".";
 
-export type ZIPCodeRecord = Geolocation & { zipCode: ZIPCode }
-export type ZIPCodeList = ZIPCodeRecord[]
+export type ZIPCodeRecord = Geolocation & {zipCode: ZIPCode};
+export type ZIPCodeList = ZIPCodeRecord[];
 
-declare const defaultExport: ZIPCodeList
+declare const defaultExport: ZIPCodeList;
 
-export default defaultExport
+export default defaultExport;