global-address-validator

A single TypeScript API for validating the relationship between Country → State/Province → City → ZIP/Postal Code.

Designed for address forms like:

• Country
• State / Province
• City
• ZIP / Postal Code

Install

npm install global-address-validator

Example

import { validateAddress } from 'global-address-validator';

const result = await validateAddress({
  country: 'IN',
  state: 'KA',
  city: 'Bengaluru',
  postalCode: '560001',
});

console.log(result.valid);

API

getCountries()
getCountry(countryCode)
getStates(countryCode)
getState(countryCode, stateCode)
getCities(countryCode, stateCode)
searchCities({ country, state, query })
getSupportedPostalCountries()
isPostalCountrySupported(countryCode)
validatePostalCode(countryCode, postalCode, stateCode?)
getPostalCodes(countryCode, postalCode, stateCode?)
searchPostalCodesByCity(countryCode, city, stateCode?)
validateAddress({ country, state, city, postalCode })

Validation behavior

The package distinguishes between:

• VALID — all supplied geographic components match.
• INVALID — one or more supplied components do not match.
• NOT_COVERED — the selected country does not currently have postal-code existence data in the upstream dataset.

It does not claim that an address is deliverable or that Address Line 1/2 physically exists. This package validates geographic components and postal-code relationships.

Data and licensing

Country/state/city data and postal-code data are consumed from the @countrystatecity/* packages. Those packages publish ODbL-licensed data sourced from the Countries States Cities Database. Users distributing or adapting the data must comply with the applicable ODbL terms and attribution requirements.

The package's own wrapper code is MIT licensed.

Important coverage note

Postal-code existence data is not available for every country. A country without postal data returns NOT_COVERED rather than incorrectly reporting the address as invalid.

Security model

The package does not send address data to a remote geocoding API. Validation is performed against the installed dataset. Keep the package and its upstream dependencies updated and use npm's lockfile/provenance and your organization's dependency scanning in production.