@ideditor/country-coder
Advanced tools
Convert longitude-latitude pairs to ISO 3166-1 codes quickly and locally
š ā”ļø š©š° Convert longitude-latitude pairs to ISO 3166-1 codes quickly and locally
country-coder is a lightweight package that looks up region identifiers for geographic points without calling a server. It can code and convert between several common IDs:
ZA)ZAF)710)710)Q258)Results can optionally include non-country ISO 3166-1 features, such as Puerto Rico (PR) or the Isle of Man (IM). Some unofficial yet exceptionally-reserved or user-assigned ISO codes are also supported, such as the European Union (EU) and Kosovo (XK), as well as M49 regions like Africa (002) or Polynesia (061).
In addition to identifiers, country-coder can provide basic regional information:
Client-side coding has a number of benefits over server-side solutions:
country-coder prioritizes package size and lookup speed over precision. Thus, it's not suitable for some situations and use cases:
npm install @ideditor/country-coder
This library is available in both ES5/CommonJS and ES6 module formats.
const countryCoder = require('@ideditor/country-coder'); // CommonJS import all
const iso1A2Code = require('@ideditor/country-coder').iso1A2Code; // CommonJS import named
// or
import * as countryCoder from '@ideditor/country-coder'; // ES6 import all
import { iso1A2Code } from '@ideditor/country-coder'; // ES6 import named
Simply pass in a [longitude, latitude] to iso1A2Code to get the country code.
iso1A2Code([-4.5, 54.2]); // returns 'GB'
To include non-country territories, pass in territory for the level option.
iso1A2Code([-4.5, 54.2], { level: 'territory' }); // returns 'IM'
The same method can convert from other identifiers.
iso1A2Code('Q145'); // returns 'GB'
Read the full API reference to see everything country-coder can do.
This package is kept intentionally minimal. However, if you find a bug or have an interesting idea for an enhancement, feel free to open an Issue and/or Pull Request.
# feature(query: Location | string | number, opts?: CodingOptions): RegionFeature? <>
Returns the GeoJSON feature from borders for the given location or identifier and options, if found. Note that the geometry of the feature may not contain its full bounds (see aggregateFeature).
feature([-4.5, 54.2]); // returns United Kingdom feature
feature([-4.5, 54.2], { level: 'territory' }); // returns {Isle of Man}
feature([0, 90]); // returns null
feature('GB'); // returns {United Kingdom}
feature('GBR'); // returns {United Kingdom}
feature('826'); // returns {United Kingdom}
feature(826); // returns {United Kingdom}
feature('Q145'); // returns {United Kingdom}
feature('š¬š§'); // returns {United Kingdom}
feature('UK'); // returns {United Kingdom}
feature('IM'); // returns {Isle of Man}
feature('United Kingdom'); // returns {United Kingdom}
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
feature(pointGeoJSON); // returns {United Kingdom}
feature(pointGeoJSON.geometry); // returns {United Kingdom}
# iso1A2Code(query: Location | string | number, opts?: CodingOptions): string? <>
Returns the ISO 3166-1 alpha-2 code for the given location or identifier and options, if found.
iso1A2Code([-4.5, 54.2]); // returns 'GB'
iso1A2Code([-4.5, 54.2], { level: 'territory' }); // returns 'IM'
iso1A2Code([0, 90]); // returns null
iso1A2Code('GBR'); // returns 'GB'
iso1A2Code('826'); // returns 'GB'
iso1A2Code(826); // returns 'GB'
iso1A2Code('Q145'); // returns 'GB'
iso1A2Code('š¬š§'); // returns 'GB'
iso1A2Code('UK'); // returns 'GB'
iso1A2Code('IMN'); // returns 'IM'
iso1A2Code('United Kingdom'); // returns 'GB'
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
iso1A2Code(pointGeoJSON); // returns 'GB'
iso1A2Code(pointGeoJSON.geometry); // returns 'GB'
# iso1A3Code(query: Location | string | number, opts?: CodingOptions): string? <>
Returns the ISO 3166-1 alpha-3 code for the given location or identifier and options, if found.
iso1A3Code([-4.5, 54.2]); // returns 'GBR'
iso1A3Code([-4.5, 54.2], { level: 'territory' }); // returns 'IMN'
iso1A3Code([0, 90]); // returns null
iso1A3Code('GB'); // returns 'GBR'
iso1A3Code('826'); // returns 'GBR'
iso1A3Code(826); // returns 'GBR'
iso1A3Code('Q145'); // returns 'GBR'
iso1A3Code('š¬š§'); // returns 'GBR'
iso1A3Code('UK'); // returns 'GBR'
iso1A3Code('IM'); // returns 'IMN'
iso1A3Code('United Kingdom'); // returns 'GBR'
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
iso1A3Code(pointGeoJSON); // returns 'GBR'
iso1A3Code(pointGeoJSON.geometry); // returns 'GBR'
# iso1N3Code(query: Location | string | number, opts?: CodingOptions): string? <>
Returns the ISO 3166-1 numeric-3 code for the given location or identifier and options, if found. For more comprehensive coverage, see m49Code.
iso1N3Code([-4.5, 54.2]); // returns '826'
iso1N3Code([-4.5, 54.2], { level: 'territory' }); // returns '833'
iso1N3Code([0, 90]); // returns null
iso1N3Code('GB'); // returns '826'
iso1N3Code('GBR'); // returns '826'
iso1N3Code('Q145'); // returns '826'
iso1N3Code('š¬š§'); // returns '826'
iso1N3Code('UK'); // returns '826'
iso1N3Code('IM'); // returns '833'
iso1N3Code('Q15'); // returns null (Africa)
iso1A3Code('United Kingdom'); // returns '826'
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
iso1N3Code(pointGeoJSON); // returns '826'
iso1N3Code(pointGeoJSON.geometry); // returns '826'
# m49Code(query: Location | string | number, opts?: CodingOptions): string? <>
Returns the United Nations M49 code for the given location or identifier and options, if found. These codes are a superset of ISO 3166-1 numeric-3 codes, adding a subdivision (Sark) and transnational regions (e.g. Asia, Central America, Polynesia).
m49Code([-4.5, 54.2]); // returns '826'
m49Code([-4.5, 54.2], { level: 'territory' }); // returns '833'
m49Code([0, 90]); // returns null
m49Code('GB'); // returns '826'
m49Code('GBR'); // returns '826'
m49Code('Q145'); // returns '826'
m49Code('š¬š§'); // returns '826'
m49Code('UK'); // returns '826'
m49Code('IM'); // returns '833'
m49Code('Q15'); // returns '002' (Africa)
m49Code('United Kingdom'); // returns '826'
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
m49Code(pointGeoJSON); // returns '826'
m49Code(pointGeoJSON.geometry); // returns '826'
# wikidataQID(query: Location | string | number, opts?: CodingOptions): string? <>
Returns the Wikidata QID for the given location or identifier and options, if found.
wikidataQID([-4.5, 54.2]); // returns 'Q145'
wikidataQID([-4.5, 54.2], { level: 'territory' }); // returns 'Q9676'
wikidataQID([0, 90]); // returns null
wikidataQID('GB'); // returns 'Q145'
wikidataQID('GBR'); // returns 'Q145'
wikidataQID('826'); // returns 'Q145'
wikidataQID(826); // returns 'Q145'
wikidataQID('š¬š§'); // returns 'Q145'
wikidataQID('UK'); // returns 'Q145'
wikidataQID('IM'); // returns 'Q9676'
wikidataQID('United Kingdom'); // returns 'Q145'
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
wikidataQID(pointGeoJSON); // returns 'Q145'
wikidataQID(pointGeoJSON.geometry); // returns 'Q145'
# emojiFlag(query: Location | string | number, opts?: CodingOptions): string? <>
Returns the emoji flag sequence for the given location or identifier and options, if found.
emojiFlag([-4.5, 54.2]); // returns 'š¬š§'
emojiFlag([-4.5, 54.2], { level: 'territory' }); // returns 'š®š²'
emojiFlag([0, 90]); // returns null
emojiFlag('GB'); // returns 'š¬š§'
emojiFlag('GBR'); // returns 'š¬š§'
emojiFlag('826'); // returns 'š¬š§'
emojiFlag(826); // returns 'š¬š§'
emojiFlag('Q145'); // returns 'š¬š§'
emojiFlag('UK'); // returns 'š¬š§'
emojiFlag('IM'); // returns 'š®š²'
emojiFlag('United Kingdom'); // returns 'š¬š§'
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
emojiFlag(pointGeoJSON); // returns 'š¬š§'
emojiFlag(pointGeoJSON.geometry); // returns 'š¬š§'
# featuresContaining(query: Location | string | number, strict: boolean): [RegionFeature] <>
Returns all the the features of any type that contain or match the given location or identifier, if any. If strict is true then only features that are strictly containing are returned.
featuresContaining([-4.5, 54.2]); // returns [{Isle of Man}, {Northern Europe}, {Europe}, {United Kingdom}]
featuresContaining([0, 51.5]); // returns [{United Kingdom}, {Northern Europe}, {Europe}, {European Union}]
featuresContaining([6.1, 46.2]); // returns [{Switzerland}, {Western Europe}, {Europe}]
featuresContaining([0, 90]); // returns []
featuresContaining('GB'); // returns [{United Kingdom}, {Northern Europe}, {Europe}, {European Union}]
featuresContaining('GBR'); // returns [{United Kingdom}, {Northern Europe}, {Europe}, {European Union}]
featuresContaining('826'); // returns [{United Kingdom}, {Northern Europe}, {Europe}, {European Union}]
featuresContaining(826); // returns [{United Kingdom}, {Northern Europe}, {Europe}, {European Union}]
featuresContaining('Q145'); // returns [{United Kingdom}, {Northern Europe}, {Europe}, {European Union}]
featuresContaining('š¬š§'); // returns [{United Kingdom}, {Northern Europe}, {Europe}, {European Union}]
featuresContaining('UK'); // returns [{United Kingdom}, {Northern Europe}, {Europe}, {European Union}]
featuresContaining('154'); // returns [{Northern Europe}, {Europe}]
featuresContaining('GB', true); // returns [{Northern Europe}, {Europe}, {European Union}]
featuresContaining('154', true); // returns [{Europe}]
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [0, -90] } };
featuresContaining(pointGeoJSON); // returns [{Antarctica}]
featuresContaining(pointGeoJSON.geometry); // returns [{Antarctica}]
# featuresIn(id: string | number, strict: boolean): [RegionFeature] <>
Returns all the the features that match or are contained within the given identifier, if any. If strict is true then only features that are strictly contained are returned.
featuresIn('CN'); // returns [{China}, {Hong Kong}, {Macau}]
featuresIn('CHN'); // returns [{China}, {Hong Kong}, {Macau}]
featuresIn('156'); // returns [{China}, {Hong Kong}, {Macau}]
featuresIn(156); // returns [{China}, {Hong Kong}, {Macau}]
featuresIn('Q148'); // returns [{China}, {Hong Kong}, {Macau}]
featuresIn('šØš³'); // returns [{China}, {Hong Kong}, {Macau}]
featuresIn('China'); // returns [{China}, {Hong Kong}, {Macau}]
featuresIn('CN', true); // returns [{Hong Kong}, {Macau}]
# aggregateFeature(id: string | number): [RegionFeature] <>
Returns a new feature with the properties of the feature matching id and the combined geometry of it and all its component features. This step is not necessary when only accessing a feature's properties.
aggregateFeature('CN'); // returns China, Hong Kong, and Macau as one feature
aggregateFeature('CHN'); // returns China, Hong Kong, and Macau as one feature
aggregateFeature('156'); // returns China, Hong Kong, and Macau as one feature
aggregateFeature(156); // returns China, Hong Kong, and Macau as one feature
aggregateFeature('Q148'); // returns China, Hong Kong, and Macau as one feature
aggregateFeature('šØš³'); // returns China, Hong Kong, and Macau as one feature
aggregateFeature('China'); // returns China, Hong Kong, and Macau as one feature
# isIn(query: Location | string | number, bounds: string | number): boolean <>
Returns true if the feature matching query is, or is within, the feature matching bounds.
isIn([0, 51.5], 'GB'); // returns true
isIn([-4.5, 54.2], 'IM'); // returns true
isIn([-4.5, 54.2], 'GB'); // returns true
isIn([-4.5, 54.2], 'CH'); // returns false
isIn([6.1, 46.2], 'GB'); // returns false
isIn('IM', 'GB'); // returns true
isIn('GB', 'IM'); // returns false
isIn('GB', '150'); // returns true
isIn('GBR', 150); // returns true
isIn('826', 'Q46'); // returns true
isIn('š®š²', 'š¬š§'); // returns true
isIn('United Kingdom', 'Europe'); // returns true
isIn('United Kingdom', 'Africa'); // returns false
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 51.5] } };
isIn(pointGeoJSON, 'GB'); // returns true
isIn(pointGeoJSON.geometry, 'GB'); // returns true
# isInEuropeanUnion(query: Location | string | number): boolean <>
Returns true if the feature with the given location or identifier is found to be part of the European Union. This is a convenience method for isIn(query, 'EU').
isInEuropeanUnion([0, 51.5]); // returns true (Britain)
isInEuropeanUnion([-4.5, 54.2]); // returns false (Isle of Man)
isInEuropeanUnion([6.1, 46.2]); // returns false (Switzerland)
isInEuropeanUnion([0, 90]); // returns false (North Pole)
isInEuropeanUnion('EU'); // returns true
isInEuropeanUnion('GB'); // returns true
isInEuropeanUnion('GBR'); // returns true
isInEuropeanUnion('826'); // returns true
isInEuropeanUnion(826); // returns true
isInEuropeanUnion('Q145'); // returns true
isInEuropeanUnion('š¬š§'); // returns true
isInEuropeanUnion('UK'); // returns true
isInEuropeanUnion('United Kingdom'); // returns true
isInEuropeanUnion('IM'); // returns false
isInEuropeanUnion('CH'); // returns false
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 51.5] } };
isInEuropeanUnion(pointGeoJSON); // returns true (Britain)
isInEuropeanUnion(pointGeoJSON.geometry); // returns true (Britain)
# driveSide(query: Location | string | number): string? <>
Returns the side of the road on which traffic drives for the given location or identifier, if found.
driveSide([0, 51.5]); // returns 'left' (Britain)
driveSide([6.1, 46.2]); // returns 'right' (Switzerland)
driveSide([0, 90]); // returns null (North Pole)
driveSide('EU'); // returns null
driveSide('GB'); // returns 'left'
driveSide('GBR'); // returns 'left'
driveSide('826'); // returns 'left'
driveSide(826); // returns 'left'
driveSide('Q145'); // returns 'left'
driveSide('š¬š§'); // returns 'left'
driveSide('UK'); // returns 'left'
driveSide('United Kingdom'); // returns 'left'
driveSide('CH'); // returns 'right'
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 51.5] } };
driveSide(pointGeoJSON); // returns 'left' (Britain)
driveSide(pointGeoJSON.geometry); // returns 'left' (Britain)
# roadSpeedUnit(query: Location | string | number): string? <>
Returns the unit of speed used on traffic signs for the given location or identifier, if found.
roadSpeedUnit([0, 51.5]); // returns 'mph' (Britain)
roadSpeedUnit([6.1, 46.2]); // returns 'km/h' (Switzerland)
roadSpeedUnit([0, 90]); // returns null (North Pole)
roadSpeedUnit('EU'); // returns null
roadSpeedUnit('GB'); // returns 'mph'
roadSpeedUnit('GBR'); // returns 'mph'
roadSpeedUnit('826'); // returns 'mph'
roadSpeedUnit(826); // returns 'mph'
roadSpeedUnit('Q145'); // returns 'mph'
roadSpeedUnit('š¬š§'); // returns 'mph'
roadSpeedUnit('UK'); // returns 'mph'
roadSpeedUnit('United Kingdom'); // returns 'mph'
roadSpeedUnit('CH'); // returns 'km/h'
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 51.5] } };
roadSpeedUnit(pointGeoJSON); // returns 'mph' (Britain)
roadSpeedUnit(pointGeoJSON.geometry); // returns 'mph' (Britain)
# callingCodes(query: Location | string | number): [string] <>
Returns the full international calling code prefix of phone numbers for the given location or identifier, if any. All prefixes have a country code, with some also including an area code separated by a space character. These are commonly formatted with a preceding plus sign (e.g. +1 242).
callingCodes([0, 51.5]); // returns ['44'] (Britain)
callingCodes([0, 90]); // returns [] (North Pole)
callingCodes('EU'); // returns []
callingCodes('GB'); // returns ['44']
callingCodes('GBR'); // returns ['44']
callingCodes('826'); // returns ['44']
callingCodes(826); // returns ['44']
callingCodes('Q145'); // returns ['44']
callingCodes('š¬š§'); // returns ['44']
callingCodes('UK'); // returns ['44']
callingCodes('United Kingdom'); // returns ['44']
callingCodes('BS'); // returns ['1 242']
callingCodes('JA'); // returns ['1 876', '1 658']
let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 51.5] } };
callingCodes(pointGeoJSON); // returns ['44'] (Britain)
callingCodes(pointGeoJSON.geometry); // returns ['44'] (Britain)
# borders: RegionFeatureCollection
<>
The base GeoJSON feature collection used for feature lookup. While this property is public, modifying it is not recommended and may have unintended effects.
# Vec2
An array of two numbers as [longitude, latitude] referenced to the WGS 84 datum.
[number, number]
# PointGeometry
GeoJSON Point geometry as specified by RFC 7946.
# PointFeature
A GeoJSON Feature with Point geometry as specified by RFC 7946.
# Location
A geographic location in one of the supported formats.
Vec2 | PointGeometry | PointFeature
# CodingOptions
An object containing options used for geocoding.
level: string, for overlapping features, the preferred geographic classification of the one to code. If no feature exists at the specified level, the feature at the next-highest level is coded, if any. The possible values map directly to the level property of RegionFeatureProperties objects.
worldunion: European Unionregion: Africa, Americas, Antarctica, Asia, Europe, Oceaniasubregion: Sub-Saharan Africa, North America, Micronesia, etc.intermediateRegion: Eastern Africa, South America, Channel Islands, etc.country: Ethiopia, Brazil, United States, etc.territory: Puerto Rico, Gurnsey, Hong Kong, etc.subterritory: Sark, Ascension Island, Diego Garcia, etc.# RegionFeature
A GeoJSON feature representing a codable geographic area.
# RegionFeatureProperties
An object containing the attributes of a RegionFeature object.
id: string, a unique ID for this feature specific to country-coderiso1A2: string, ISO 3166-1 alpha-2 codeiso1A3: string, ISO 3166-1 alpha-3 codeiso1N3: string, ISO 3166-1 numeric-3 codem49: string, UN M49 codewikidata: string, Wikidata QIDemojiFlag: string, the emoji flag sequence derived from this feature's ISO 3166-1 alpha-2 codenameEn: string, common name in Englishaliases: [string], additional identifiers which can be used to look up this featurecountry: string, for features entirely within a country, the ISO 3166-1 alpha-2 code for that countrygroups: [string], the ISO 3166-1 alpha-2 or M49 codes of other features this feature is entirely withinmembers: [string], the ISO 3166-1 alpha-2 or M49 codes of other features this feature entirely contains, the inverse of groupslevel: string, the rough geographic classification of this feature
worldunion: European Unionregion: Africa, Americas, Antarctica, Asia, Europe, Oceaniasubregion: Sub-Saharan Africa, North America, Micronesia, etc.intermediateRegion: Eastern Africa, South America, Channel Islands, etc.country: Ethiopia, Brazil, United States, etc.territory: Puerto Rico, Gurnsey, Hong Kong, etc.subterritory: Sark, Ascension Island, Diego Garcia, etc.isoStatus: string, the status of this feature's ISO 3166-1 code(s), if any
official: officially-assignedexcRes: exceptionally-reservedusrAssn: user-assigneddriveSide: string, the side of the road on which traffic drives within this feature
rightleftroadSpeedUnit: string, the speed unit used on traffic signs in this feature
mph: miles per hourkm/h: kilometers per hourcallingCodes: [string], the international calling codes for this feature, sometimes including area codes# RegionFeatureCollection
A GeoJSON feature collection containing RegionFeature objects.
FAQs
Convert longitude-latitude pairs to ISO 3166-1 codes quickly and locally
The npm package @ideditor/country-coder receives a total of 981 weekly downloads. As such, @ideditor/country-coder popularity was classified as not popular.
We found that @ideditor/country-coder demonstrated a not healthy version release cadence and project activity because the last version was released a year ago.Ā It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Safari 18.4 adds support for Iterator Helpers and two other TC39 JavaScript features, bringing full cross-browser coverage to key parts of the ECMAScript spec.
Research
Security News
The Socket Research Team investigates a malicious Python package that enables automated credit card fraud on WooCommerce stores by abusing real checkout and payment flows.
Security News
Python has adopted a standardized lock file format to improve reproducibility, security, and tool interoperability across the packaging ecosystem.