libphonenumber-geo-search

Geographic search library for area codes, cities, states and countries. Provides functionality to search area codes by city name and find cities by area code prefix.

Installation

npm install libphonenumber-geo-search

Peer Dependencies

This library requires libphonenumber-geo-carrier for geocoding data:

npm install libphonenumber-geo-carrier

Usage

import { GeoSearch } from 'libphonenumber-geo-search';

const geo = new GeoSearch();

Search Area Codes by City Name

Find area codes by city name or city name prefix (minimum 2 characters):

// Find all area codes for cities starting with "New" in US
const areaCodes = geo.searchAreaCodes({
  country: 'US',
  city: 'New'
});
// Returns:
// [
//   { code: "201", name: "Newark", state: "NJ" },
//   { code: "212", name: "New York", state: "NY" },
//   { code: "504", name: "New Orleans", state: "LA" },
//   ...
// ]

// Filter by state
const nyAreaCodes = geo.searchAreaCodes({
  country: 'US',
  state: 'NY',
  city: 'New'
});
// Returns only New York state results

// Works for other countries too
const ukAreaCodes = geo.searchAreaCodes({
  country: 'GB',
  city: 'Lon'
});
// Returns: [{ code: "20", name: "London" }, ...]

Search Cities by Area Code

Find cities by area code or area code prefix (minimum 1 digit):

// Find all cities with area codes starting with "21"
const cities = geo.searchCitiesByAreaCode({
  country: 'US',
  areaCode: '21'
});
// Returns:
// [
//   { areaCode: "210", city: "San Antonio", state: "TX", country: "US" },
//   { areaCode: "212", city: "New York", state: "NY", country: "US" },
//   { areaCode: "213", city: "Los Angeles", state: "CA", country: "US" },
//   ...
// ]

// Exact area code match
const nyc = geo.searchCitiesByAreaCode({
  country: 'US',
  areaCode: '212'
});
// Returns only cities with area code 212

// Single digit prefix search
const allTwos = geo.searchCitiesByAreaCode({
  country: 'US',
  areaCode: '2'
});
// Returns all cities with area codes 200-299

// Works for other countries
const ukCities = geo.searchCitiesByAreaCode({
  country: 'GB',
  areaCode: '20'
});
// Returns: [{ areaCode: "20", city: "London", country: "GB" }, ...]

Search States/Provinces

Search for US states and Canadian provinces:

// Get all states for a country
const usStates = geo.searchStates({ a2: 'US' });
// Returns all 50 US states

// Search by name prefix
const newStates = geo.searchStates({ a2: 'US', name: 'New' });
// Returns:
// [
//   { name: "New Hampshire", code: "NH", country: "US" },
//   { name: "New Jersey", code: "NJ", country: "US" },
//   { name: "New Mexico", code: "NM", country: "US" },
//   { name: "New York", code: "NY", country: "US" }
// ]

// Search by state code
const state = geo.searchStates({ code: 'NY' });
// Returns: [{ name: "New York", code: "NY", country: "US" }]

// Canadian provinces
const caProvinces = geo.searchStates({ a2: 'CA' });
// Returns all 13 Canadian provinces/territories

API Reference

GeoSearch

Main class for geographic searches.

Constructor

new GeoSearch(options?: GeoSearchOptions)

Options:

• geocodesPath (optional): Path to libphonenumber-geo-carrier resources. Defaults to node_modules/libphonenumber-geo-carrier.

Methods

searchAreaCodes(filters: SearchAreaCodesFilters): AreaCode[]

Search for area codes by city name.

Parameters:

• country (required): ISO 3166-1 alpha-2 country code (e.g., "US", "CA", "GB")
• state (optional): State/province code for US/CA (e.g., "NY", "ON")
• city (optional): City name or prefix (minimum 2 characters, case-insensitive)

Returns: Array of AreaCode objects sorted by code, then by city name.

searchCitiesByAreaCode(filters: SearchCitiesByAreaCodeFilters): CityByAreaCode[]

Search for cities by area code.

Parameters:

• country (required): ISO 3166-1 alpha-2 country code
• areaCode (required): Area code or prefix (minimum 1 digit)

Returns: Array of CityByAreaCode objects sorted by area code, then by city name.

searchStates(filters?: SearchStatesFilters): State[]

Search for states/provinces (US and Canada only).

Parameters:

• a2 (optional): Country code (ISO 3166-1 alpha-2)
• a3 (optional): Country code (ISO 3166-1 alpha-3)
• code (optional): State/province code
• name (optional): State name prefix (minimum 2 characters)

Returns: Array of State objects sorted by country, then by name.

Types

interface AreaCode {
  code: string;      // Area code (e.g., "212")
  name: string;      // City name (e.g., "New York")
  state?: string;    // State code for US/CA (e.g., "NY")
}

interface CityByAreaCode {
  areaCode: string;  // Area code (e.g., "212")
  city: string;      // City name (e.g., "New York")
  state?: string;    // State code for US/CA (e.g., "NY")
  country: string;   // Country code (e.g., "US")
}

interface State {
  name: string;      // State name (e.g., "New York")
  code: string;      // State code (e.g., "NY")
  country: string;   // Country code (e.g., "US")
}

interface GeoSearchOptions {
  geocodesPath?: string;  // Path to geocodes data
}

Utility Functions

The library also exports utility functions for working with states:

import {
  getCountryByState,
  getStateInfo,
  isStateInCountry,
  STATES_BY_COUNTRY,
  COUNTRIES_WITH_STATES
} from 'libphonenumber-geo-search';

// Get country by state code
getCountryByState('NY');  // Returns: "US"
getCountryByState('ON');  // Returns: "CA"

// Get state info
getStateInfo('NY');
// Returns: { name: "New York", code: "NY", country: "US" }

// Check if state belongs to country
isStateInCountry('US', 'NY');  // Returns: true
isStateInCountry('CA', 'NY');  // Returns: false

// Access raw state data
STATES_BY_COUNTRY['US'];  // Array of US states
STATES_BY_COUNTRY['CA'];  // Array of Canadian provinces

Supported Countries

• US/CA with states: Full support including state/province information
• Other countries: Area code and city search without state information

The library uses libphonenumber-geo-carrier BSON data files which support most countries with geographic phone numbering.

License

MIT