country-coder

country-coder

📍 ➡️ 🇩🇰 Convert longitude-latitude pairs to ISO 3166-1 codes quickly and locally

What is it?

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:

• 🆎 ISO 3166-1 alpha-2 code (ZA)
• 🔤 ISO 3166-1 alpha-3 code (ZAF)
• 3️⃣ ISO 3166-1 numeric-3 code (710)
• 🌐 Wikidata QID (Q258)
• 🇺🇳 Emoji flag (🇿🇦)

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).

Advantages

Client-side coding has a number of benefits over server-side solutions:

• ✅ 🚅 Performance: get fast, reliable results at scale
• ✅ ✌️ Ease of Use: forget async callbacks, network errors, API keys, and rate limits
• ✅ 🕶 Privacy: keep your location data on-device
• ✅ 📴 Offline Workflows: deploy to connection-challenged environments

Caveats

country-coder prioritizes package size and lookup speed over precision. Thus, it's not suitable for some situations and use cases:

• 🚫 🛂 Disputed Borders: only one country is coded per point, roughly the "de facto controlling country"
• 🚫 🚢 Maritime Borders: only points on land are supported; borders over water are highly generalized
• 🚫 🖋 Complex Borders: land borders are of varying detail and may be imprecise at granular scales
• 🚫 🧩 Country Subdivisions: provinces and similar features under ISO 3166-2 cannot be coded
• 🚫 📇 Naming: feature names are omitted; get them via another package or the Wikidata API
• 🚫 📐 Spatial Operations: a feature's calculated area, bounding box, etc. will likely be inaccurate
• 🚫 🗺 Mapmaking: the border data is not intended for rendering

Installing

npm install country-coder

This library is available in both ES5/CommonJS and ES6 module formats.

const CountryCoder = require('country-coder').CountryCoder;   // CommonJS
// or
import { CountryCoder } from 'country-coder';     // ES6

Quick Start

Simply pass in a [longitude, latitude] to iso1A2Code to get the country code.

const coder = new CountryCoder();
coder.iso1A2Code([-4.5, 54.2]);	 // returns 'GB'

To include non-country regions, pass in region for the level option.

const coder = new CountryCoder();
coder.iso1A2Code([-4.5, 54.2], { level: 'region' });  // returns 'IM'

The same method can convert from other identifiers.

const coder = new CountryCoder();
coder.iso1A2Code('Q145');  // returns 'GB'

Read the full API reference to see everything country-coder can do.

Contributing

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.

API Reference

Methods

• new CountryCoder() constructor
• feature(arg: string | Location, opts?: CodingOptions): RegionFeature?
• iso1A2Code(arg: string | Location, opts?: CodingOptions): string?
• iso1A3Code(arg: string | Location, opts?: CodingOptions): string?
• iso1N3Code(arg: string | Location, opts?: CodingOptions): string?
• wikidataQID(arg: string | Location, opts?: CodingOptions): string?
• emojiFlag(arg: string | Location, opts?: CodingOptions): string?
• features(loc: Location): [RegionFeature]
• iso1A2Codes(loc: Location): [string]
• isInEuropeanUnion(arg: string | Location): boolean

Properties

• borders: RegionFeatureCollection - the base GeoJSON containing all features

Types

• Vec2: [number, number]
• PointGeometry: a GeoJSON Point geometry object
• PointFeature: a GeoJSON feature object with a Point geometry type
• Location: Vec2 | PointGeometry | PointFeature
• CodingOptions
• RegionFeature
• RegionFeatureProperties
• RegionFeatureCollection

Methods

# new CountryCoder() <>

Constructs a new CountryCoder.

const coder = new CountryCoder();

# feature(arg: string | Location, opts?: CodingOptions): RegionFeature? <>

Returns the GeoJSON feature from borders for the given location or identifier and options, if found.

const coder = new CountryCoder();
coder.feature([-4.5, 54.2]);  // returns United Kingdom feature
coder.feature([-4.5, 54.2], { level: 'region' });  // returns Isle of Man feature
coder.feature([0, 90]);       // returns null
coder.feature('GB');          // returns United Kingdom feature
coder.feature('GBR');         // returns United Kingdom feature
coder.feature('826');         // returns United Kingdom feature
coder.feature('Q145');        // returns United Kingdom feature
coder.feature('🇬🇧');          // returns United Kingdom feature
coder.feature('UK');          // returns United Kingdom feature
coder.feature('IM');          // returns Isle of Man feature

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
coder.feature(pointGeoJSON);           // returns United Kingdom feature
coder.feature(pointGeoJSON.geometry);  // returns United Kingdom feature

# iso1A2Code(arg: string | Location, opts?: CodingOptions): string? <>

Returns the ISO 3166-1 alpha-2 code for the given location or identifier and options, if found.

const coder = new CountryCoder();
coder.iso1A2Code([-4.5, 54.2]);  // returns 'GB'
coder.iso1A2Code([-4.5, 54.2], { level: 'region' });  // returns 'IM'
coder.iso1A2Code([0, 90]);       // returns null
coder.iso1A2Code('GBR');         // returns 'GB'
coder.iso1A2Code('826');         // returns 'GB'
coder.iso1A2Code('Q145');        // returns 'GB'
coder.iso1A2Code('🇬🇧');          // returns 'GB'
coder.iso1A2Code('UK');          // returns 'GB'
coder.iso1A2Code('IMN');         // returns 'IM'

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
coder.iso1A2Code(pointGeoJSON);           // returns 'GB'
coder.iso1A2Code(pointGeoJSON.geometry);  // returns 'GB'

# iso1A3Code(arg: string | Location, opts?: CodingOptions): string? <>

Returns the ISO 3166-1 alpha-3 code for the given location or identifier and options, if found.

const coder = new CountryCoder();
coder.iso1A3Code([-4.5, 54.2]);  // returns 'GBR'
coder.iso1A3Code([-4.5, 54.2], { level: 'region' });  // returns 'IMN'
coder.iso1A3Code([0, 90]);       // returns null
coder.iso1A3Code('GB');          // returns 'GBR'
coder.iso1A3Code('826');         // returns 'GBR'
coder.iso1A3Code('Q145');        // returns 'GBR'
coder.iso1A3Code('🇬🇧');          // returns 'GBR'
coder.iso1A3Code('UK');          // returns 'GBR'
coder.iso1A3Code('IM');          // returns 'IMN'

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
coder.iso1A3Code(pointGeoJSON);           // returns 'GBR'
coder.iso1A3Code(pointGeoJSON.geometry);  // returns 'GBR'

# iso1N3Code(arg: string | Location, opts?: CodingOptions): string? <>

Returns the ISO 3166-1 numeric-3 code for the given location or identifier and options, if found.

const coder = new CountryCoder();
coder.iso1N3Code([-4.5, 54.2]);  // returns '826'
coder.iso1N3Code([-4.5, 54.2], { level: 'region' });  // returns '833'
coder.iso1N3Code([0, 90]);       // returns null
coder.iso1N3Code('GB');          // returns '826'
coder.iso1N3Code('GBR');         // returns '826'
coder.iso1N3Code('Q145');        // returns '826'
coder.iso1N3Code('🇬🇧');          // returns '826'
coder.iso1N3Code('UK');          // returns '826'
coder.iso1N3Code('IM');          // returns '833'

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
coder.iso1N3Code(pointGeoJSON);           // returns '826'
coder.iso1N3Code(pointGeoJSON.geometry);  // returns '826'

# wikidataQID(arg: string | Location, opts?: CodingOptions): string? <>

Returns the Wikidata QID for the given location or identifier and options, if found.

const coder = new CountryCoder();
coder.wikidataQID([-4.5, 54.2]);  // returns 'Q145'
coder.wikidataQID([-4.5, 54.2], { level: 'region' });  // returns 'Q9676'
coder.wikidataQID([0, 90]);       // returns null
coder.wikidataQID('GB');          // returns 'Q145'
coder.wikidataQID('GBR');         // returns 'Q145'
coder.wikidataQID('826');         // returns 'Q145'
coder.wikidataQID('🇬🇧');          // returns 'Q145'
coder.wikidataQID('UK');          // returns 'Q145'
coder.wikidataQID('IM');          // returns 'Q9676'

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
coder.wikidataQID(pointGeoJSON);           // returns 'Q145'
coder.wikidataQID(pointGeoJSON.geometry);  // returns 'Q145'

# emojiFlag(arg: string | Location, opts?: CodingOptions): string? <>

Returns the emoji flag sequence for the given location or identifier and options, if found.

const coder = new CountryCoder();
coder.emojiFlag([-4.5, 54.2]);  // returns '🇬🇧'
coder.emojiFlag([-4.5, 54.2], { level: 'region' });  // returns '🇮🇲'
coder.emojiFlag([0, 90]);       // returns null
coder.emojiFlag('GB');          // returns '🇬🇧'
coder.emojiFlag('GBR');         // returns '🇬🇧'
coder.emojiFlag('826');         // returns '🇬🇧'
coder.emojiFlag('Q145');        // returns '🇬🇧'
coder.emojiFlag('UK');          // returns '🇬🇧'
coder.emojiFlag('IM');          // returns '🇮🇲'

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
coder.emojiFlag(pointGeoJSON);           // returns '🇬🇧'
coder.emojiFlag(pointGeoJSON.geometry);  // returns '🇬🇧'

# features(loc: Location): [RegionFeature] <>

Returns all the the features containing the given location.

const coder = new CountryCoder();
coder.features([-4.5, 54.2]);  // returns [{Isle of Man feature}, {United Kingdom feature}]
coder.features([0, 51.5]);     // returns [{United Kingdom feature}, {European Union feature}]
coder.features([6.1, 46.2]);   // returns [{Switzerland feature}]
coder.features([0, 90]);       // returns []

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [6.1, 46.2] } };
coder.features(pointGeoJSON);            // returns [{Switzerland feature}]
coder.features(pointGeoJSON.geometry);   // returns [{Switzerland feature}]

# iso1A2Codes(loc: Location): [string] <>

Returns the ISO 3166-1 alpha-2 codes for all the the features containing the given location.

const coder = new CountryCoder();
coder.iso1A2Codes([-4.5, 54.2]);   // returns ['IM', 'GB']
coder.iso1A2Codes([0, 51.5]);      // returns ['GB', 'EU']
coder.iso1A2Codes([6.1, 46.2]);    // returns ['CH']
coder.iso1A2Codes([0, 90]);        // returns []

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [-4.5, 54.2] } };
coder.iso1A2Codes(pointGeoJSON);           // returns ['IM', 'GB']
coder.iso1A2Codes(pointGeoJSON.geometry);  // returns ['IM', 'GB']

# isInEuropeanUnion(arg: string | Location): boolean <>

Returns true if the feature with the given location or identifier is found to be part of the European Union.

const coder = new CountryCoder();
coder.isInEuropeanUnion([0, 51.5]);    // returns true (Britain)
coder.isInEuropeanUnion([-4.5, 54.2]); // returns false (Isle of Man)
coder.isInEuropeanUnion([6.1, 46.2]);  // returns false (Switzerland)
coder.isInEuropeanUnion([0, 90]);      // returns false (North Pole)
coder.isInEuropeanUnion('EU');         // returns true
coder.isInEuropeanUnion('GB');         // returns true
coder.isInEuropeanUnion('GBR');        // returns true
coder.isInEuropeanUnion('826');        // returns true
coder.isInEuropeanUnion('Q145');       // returns true
coder.isInEuropeanUnion('🇬🇧');         // returns true
coder.isInEuropeanUnion('UK');         // returns true
coder.isInEuropeanUnion('IM');         // returns false
coder.isInEuropeanUnion('CH');         // returns false

let pointGeoJSON = { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 51.5] } };
coder.isInEuropeanUnion(pointGeoJSON);           // returns true (Britain)
coder.isInEuropeanUnion(pointGeoJSON.geometry);  // returns true (Britain)

Properties

# 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.

Types

# 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 division level of the one to get
  • country (default): the "sovereign state" feature
  • region: the lowest-level feature with an official or user-assigned ISO code

# RegionFeature

A GeoJSON feature representing a codable geographic area.

# RegionFeatureProperties

An object containing the attributes of a RegionFeature object.

• iso1A2: string, ISO 3166-1 alpha-2 code
• iso1A3: string, ISO 3166-1 alpha-3 code
• iso1N3: string, ISO 3166-1 numeric-3 code
• wikidata: string, Wikidata QID
• emojiFlag: string, the emoji flag sequence derived from this feature's ISO 3166-1 alpha-2 code
• aliases: [string], additional identifiers which can be used to look up this feature
• country: string, for features entirely within a country, the ISO 3166-1 alpha-2 code for that country
• groups: [string], the ISO 3166-1 alpha-2 codes of other features this feature is entirely within, other than its country
• isoStatus: string, the status of this feature's ISO 3166-1 code(s) if they are not officially-assigned
  • excRes: exceptionally-reserved
  • usrAssn: user-assigned

# RegionFeatureCollection

A GeoJSON feature collection containing RegionFeature objects.