A lightweight TypeScript utility library to work with US cities and ZIP codes — perfect for filters, maps, address lookups, and geolocation logic.
npm install @mardillu/us-cities-utils
A lightweight TypeScript utility library to work with US cities and ZIP codes — perfect for filters, maps, address lookups, and geolocation logic.
---
- 🔍 Get states and cities from a normalized dataset
- 📬 Lookup city data by ZIP code
- 🗺️ Find the nearest city by coordinates (lat/lon)
- 🏙️ Search cities by name (fuzzy search)
- 📌 Filter cities by state, county, or ZIP
- 📦 Pure, fast, and dependency-free
---
``bash``
npm install @mardillu/us-cities-utilsor
yarn add @mardillu/us-cities-utils
---
`ts`
import {
getStates,
getCities,
getCity,
getAllZips,
searchCities,
groupCitiesByState,
getCitiesByCounty,
getNearestCity
} from '@mardillu/us-cities-utils';
---
Returns a list of all US states in { nameAbbr: string, name: string } format.
---
Returns all cities in a given state abbreviation (e.g. 'NY', 'CA').
---
Returns all cities in a given state name (e.g. 'New York', 'California').
---
Returns all cities and zipcodes in a given state abbreviation (e.g. 'NY', 'CA').
---
Returns all cities and zipcodes in a given state name (e.g. 'New York', 'California').
---
Returns city information for a given ZIP code.
---
Returns cities whose names match (or partially match) the search string.
---
Returns cities whose names match (or partially match) the search string withing the provided state abbreviation.
---
Returns cities whose names match (or partially match) the search string withing the provided state name.
---
Groups all cities in the dataset by their state abbreviation.
---
Returns a list of all ZIP codes in the dataset.
---
Returns a list of cities belonging to a given county name.
---
Finds and returns the city nearest to the given latitude and longitude using the Haversine formula.
---
`bash`
npm test
Includes robust unit tests for all exported functions and geolocation logic.
---
Each city is in the format:
`ts`
interface UsCity {
zip: string;
name: string;
state: string;
stateAbbr: string;
county: string;
countCode: string;
latitude: number;
longitude: number;
}
---
* [ ] Add support for Canadian provinces
* [ ] Add caching for nearest city lookup
* [ ] Add fuzzy scoring to searchCities()
---
PRs are welcome! If you'd like to contribute, open an issue or submit a PR.
---
MIT © \Mardillu
``