Typed USA States

An array of geographical data for all USA states with full TypeScript support

Visitor stats

Code stats

GitHub code size in bytes GitHub repo size GitHub language count GitHub top language GitHub last commit

Content

This package contains geographical data for all USA states including:

name of the state
abbreviation of the state
territory: whether the state is under the sovereign jurisdiction of the federal government of the United States
the capital city of the state
contiguous: whether the state shares common borders with other states
zipCodes: an array containing string arrays. Each array contains two elements (string) - the start and the end of the zip code range. (The string type is used because TypeScript does not like numbers with leading zero. Pull request are welcome if you find a workaround for this issue.)
area: the area of the state in square miles in the following format:
- year: when was the value last updated
- value: the actual area
population: the population of the state in the following format:
- year: when was the value last updated
- count: the actual population
counties of the state

NB There is no counties information for the following US overseas territories:

American Samoa
Northern Mariana Islands
Puerto Rico
Virgin Islands

If you happen to have any knowledge on the matter, please consider contributing!

Cities

This package provides data for all cities in the US.

You can use this by importing the cities array:

import { usaCities } from 'typed-usa-states';

Each city object contains the following data:

name: the name of the city
state: the state which the city belongs to

Installation

npm i typed-usa-states

# or

yarn add typed-usa-states

Usage

Since the size of the array is pretty big, you can choose which states data to import in your application.

There are several predefined exported arrays with data for the states.

Their content's schema is explained below:

Import the full states data

import { usaStatesFull } from 'typed-usa-states';

Schema:

{
	name: string,
	abbreviation: string,
	territory: boolean,
	capital: string,
	contiguous: boolean,
	zipCodes: [string, string][],
	area: {
		year: number,
		value: number
	},
	population: {
		year: number,
		count: number
	},
	counties: string[]
}

Import only the required data

import { usaStates } from 'typed-usa-states';

Schema:

{
	name: string,
	abbreviation: string,
	territory: boolean,
	capital: string,
	contiguous: boolean
}

Import the required and area data

import { usaStatesWithArea } from 'typed-usa-states';

Schema:

{
	name: string,
	abbreviation: string,
	territory: boolean,
	capital: string,
	contiguous: boolean,
	area: {
		year: number,
		value: number
	}
}

Import the required and counties data

import { usaStatesWithCounties } from 'typed-usa-states';

Schema:

{
	name: string,
	abbreviation: string,
	territory: boolean,
	capital: string,
	contiguous: boolean,
	counties: string[]
}

Import the requied and population data

import { usaStatesWithPopulation } from 'typed-usa-states';

Schema:

{
	name: string,
	abbreviation: string,
	territory: boolean,
	capital: string,
	contiguous: boolean,
	population: {
		year: number,
		count: number
	}
}

Import the required and zipcode data

import { usaStatesWithZipCodes } from 'typed-usa-states';

Schema:

{
	name: string,
	abbreviation: string,
	territory: boolean,
	capital: string,
	contiguous: boolean,
	zipCodes: [string, string][]
}

Import the cities data

import { usaCities } from 'typed-usa-states';

Schema:

{
	city: string;
	state: string;
}

Usage in browser

You can use the module directly in the browser (without any module bundler such as Webpack or Parcel) but you will need to include requirejs.

The usage is not so straight-forward, so please refer to the demo

Module bundlers

typed-usa-states exposes several pretty large arrays.

It is possible that you experience issues with insufficient memory when using create-react-app or Webpack, Parcel, Rollup, etc. or if you are using the package in Docker or other CI environment.

In this case you might want to import the required array directly instead of relying on the module bunlder to resolve it for you.

This means that you need to change your code like this:

- import { usaStates } from 'typed-usa-states';
+ import { usaStates } from 'typed-usa-states/dist/states';

- import { usaCities } from 'typed-usa-states';
+ import { usaCities } from 'typed-usa-states/dist/cities';

- import { usaStatesFull } from 'typed-usa-states';
+ import { usaStatesFull } from 'typed-usa-states/dist/states-full';

- import { usaStatesWithArea } from 'typed-usa-states';
+ import { usaStatesWithArea } from 'typed-usa-states/dist/states-with-area';

- import { usaStatesWithCounties } from 'typed-usa-states';
+ import { usaStatesWithCounties } from 'typed-usa-states/dist/states-with-counties';

- import { usaStatesWithPopulation } from 'typed-usa-states';
+ import { usaStatesWithPopulation } from 'typed-usa-states/dist/states-with-population';

- import { usaStatesWithZipCodes } from 'typed-usa-states';
+ import { usaStatesWithZipCodes } from 'typed-usa-states/dist/states-with-zipcodes';

Typings

The package exports several types which can be used in TypeScript environment. The typings are located in dist/index.d.ts and are being auto detected by TypeScript.