postalcode-global

A package to fetch city and state using a ZIP code worldwide. This package uses the python library pgeocode. Please find the supported country list below.

read more about pgeocode

Installation

npm install postalcode-global

Utilities

1. getLocation ==> Promise that returns the state and city when a postal code and country code are provided
2. validatePostalCode ==> checks if the provided postal code matches the country's postal code pattern and returns a boolean
3. postalCodeExistForCountry ==> checks if the country has a postal code rule and returns a boolean

Supported countries

The list of countries available in the GeoNames database, with the corresponding country codes, are given below,

Country Code	Postal Code Format	Country
BY	6 digits	Belarus
CA	A1A 1A1	Canada
CH	4 digits	Switzerland
CL	7 digits	Chile
CO	6 digits	Colombia
CR	5 digits	Costa Rica
CY	4 digits	Cyprus
CZ	5 digits	Czechia
DE	5 digits	Germany
DK	4 digits	Denmark
DO	5 digits	Dominican Republic
DZ	5 digits	Algeria
EE	5 digits	Estonia
ES	5 digits	Spain
FI	5 digits	Finland
FM	5 digits	Federated States of Micronesia
FO	4 digits	Faroe Islands
FR	5 digits	France
GB	AA1 1AA	United Kingdom of Great Britain and Northern Ireland
GF	9 digits	French Guiana
GG	GY1 1AA	Guernsey
GL	4 digits	Greenland
GP	97100-97199	Guadeloupe
GT	5 digits	Guatemala
GU	5 digits	Guam
HR	5 digits	Croatia
HT	4 digits	Haiti
HU	4 digits	Hungary
IE	A65 2XX	Ireland
IM	IM1 1AA	Isle of Man
IN	6 digits	India
IS	3 digits	Iceland
IT	5 digits	Italy
JE	JE1 1AA	Jersey
JP	7 digits	Japan
KR	5 digits	Republic of Korea
LI	4 digits	Liechtenstein
LK	5 digits	Sri Lanka
LT	5 digits	Lithuania
LU	4 digits	Luxembourg
LV	4 digits	Latvia
MC	5 digits	Monaco
MD	6 digits	Republic of Moldova
MH	5 digits	Marshall Islands
MK	4 digits	The former Yugoslav Republic of Macedonia
MP	5 digits	Northern Mariana Islands
MQ	97200-97299	Martinique
MT	VLT 1000	Malta
MW	5 digits	Malawi
MX	5 digits	Mexico
MY	5 digits	Malaysia
NC	5 digits	New Caledonia
NL	4 digits	Netherlands
NO	4 digits	Norway
NZ	4 digits	New Zealand
PE	5 digits	Peru
PH	4 digits	Philippines
PK	5 digits	Pakistan
PL	5 digits	Poland
PM	5 digits	Saint Pierre and Miquelon
PR	5 digits	Puerto Rico
PT	4 digits	Portugal
PW	5 digits	Palau
RE	5 digits	Réunion
RO	6 digits	Romania
RS	5 digits	Serbia
RU	6 digits	Russian Federation
SE	5 digits	Sweden
SG	6 digits	Singapore
SI	4 digits	Slovenia
SJ	4 digits	Svalbard and Jan Mayen Islands
SK	5 digits	Slovakia
SM	5 digits	San Marino
TH	5 digits	Thailand
TR	5 digits	Turkey
UA	5 digits	Ukraine
US	5 digits or 5 digits-4	United States of America
UY	5 digits	Uruguay
VA	5 digits	Holy See
VI	5 digits	United States Virgin Islands
WF	5 digits	Wallis and Futuna Islands
YT	5 digits	Mayotte
ZA	4 digits	South Africa

See Geonames Database for more information.

Usages

1. getLocation

1import {getLocation} from "postalcode-global";
2
3const getCityAndState = async () => {
4    const {state, city } = await getLocation({postalCode: "3200", country: "DK"})
5    .then((data) => return data)
6    .catch((err) => return err);
7}

Response

{
  city: 'Helsinge',
  country: 'DK',
  postal_code: '3200',
  state: 'Capital Region'
}

Error Response if postal code is not identified

{
  city: undefined,
  country: 'DK',
  postal_code: '320000000',
  state: undefined,
  error: `No postal code match found for the country`
}

Error response if postal code or country code is invalid

{
  city: undefined,
  country: 'DQ',
  postal_code: '32r00',
  state: undefined,
  error: `Failed to fetch postal code info. Please check postalcode or country code`
}

---

2. validatePostalCode

1import {validatePostalCode} from "postalcode-global";
2
3validatePostalCode({countryCode: "IN", postalCode: "679330"});
4

Response

true | false

3. postalCodeExistForCountry

1import {postalCodeExistForCountry} from "postalcode-global";
2
3postalCodeExistForCountry({countryCode: "IN"});
4

Response

true | false

Can you contribute?

Yes please.! Please pull a request into the bug/fix branch if you come across any issues in the response, if any regex expression is filtering wrong pattern or anything that needs a fix. If you like to add up a feature or improve an existing feature, please pull a request in the develop branch. Please specify the reason, implementation, reference (if any) and effect of the change in the PR. Thank you and I appreciate your contributions..!