US Cities & Zipcode Utilities

A lightweight TypeScript utility library to work with US cities and ZIP codes — perfect for filters, maps, address lookups, and geolocation logic.

Features

• 🔍 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

Installation

npm install @mardillu/us-cities-utils
# or
yarn add @mardillu/us-cities-utils

Usage

import {
  getStates,
  getCities,
  getCity,
  getAllZips,
  searchCities,
  groupCitiesByState,
  getCitiesByCounty,
  getNearestCity
} from '@mardillu/us-cities-utils';

API Reference

getStates(): UsState[]

Returns a list of all US states in { nameAbbr: string, name: string } format.

getCities(stateAbbr: string): UsCity[]

Returns all cities in a given state abbreviation (e.g. 'NY', 'CA').

getCitiesBySateName(state): UsCity[]

Returns all cities in a given state name (e.g. 'New York', 'California').

getZipcodes(stateAbbr): UsCity[]

Returns all cities and zipcodes in a given state abbreviation (e.g. 'NY', 'CA').

getZipcodesBySateName(state): UsCity[]

Returns all cities and zipcodes in a given state name (e.g. 'New York', 'California').

getCity(zip: string): UsCity | undefined

Returns city information for a given ZIP code.

searchCities(query: string): UsCity[]

Returns cities whose names match (or partially match) the search string.

searchCitiesInSate(stateAbbr: string, query: string): UsCity[]

Returns cities whose names match (or partially match) the search string withing the provided state abbreviation.

searchCitiesInSateByStateName(state: string, query: string): UsCity[]

Returns cities whose names match (or partially match) the search string withing the provided state name.

groupCitiesByState(): Record<string, UsCity[]>

Groups all cities in the dataset by their state abbreviation.

getAllZips(): string[]

Returns a list of all ZIP codes in the dataset.

getCitiesByCounty(county: string): UsCity[]

Returns a list of cities belonging to a given county name.

getNearestCity(lat: number, lon: number): UsCity | undefined

Finds and returns the city nearest to the given latitude and longitude using the Haversine formula.

Testing

npm test

Includes robust unit tests for all exported functions and geolocation logic.

Data Format

Each city is in the format:

interface UsCity {
  zip: string;
  name: string;
  state: string;
  stateAbbr: string;
  county: string;
  countCode: string;
  latitude: number;
  longitude: number;
}

Roadmap

• [ ] Add support for Canadian provinces
• [ ] Add caching for nearest city lookup
• [ ] Add fuzzy scoring to searchCities()

Contribution

PRs are welcome! If you'd like to contribute, open an issue or submit a PR.

License

MIT © \Mardillu