@fruitsbytes/country-list-ts
Version:
It contains country information including 2 and 3 character ISO codes, country and capital names, currency information, telephone calling codes, and provinces ( first-tier political subdivisions).
382 lines (308 loc) • 11 kB
Markdown
<p align="center">
<img src="./wiki/banner.png" alt="Showing the title of the repository, Country list , next to the Typsript logo and the fruitsBytes logo" width="800" title="Country list TS banner image">
</p>
# Country List TS
This repository is based from the list of countries provided by [mledoze/countries](https://github.com/mledoze/countries).
It provides various compiled lists, mapped lists and tagged list of the property values. You can also search for a country based on the values in the property.
>⚠ Warning:
>
>Not all entities in this project are independent countries; refer to the independent property to know if the
country is considered a sovereign state.
## Features
- Importable assets
- flags
- geo-json
- topo-json
- Custom flag WebComponent
- List
- of names, capitals, languages, currencies ...
- mapped lists by ISO 3166-1 alpha-2
- with
- Search
## Installation
```shell
npm i
```
### Compatibility table
| Version | JS target | JS lib |
|:-------:|:---------:|:------:|
| 1.0.0 | ES5 | ES2017 |
## Usage
### List
Get list of country record member.
#### Simple list
```typescript
import {ls} from "country-list-ts";
const c = await ls('capital'); // ordered by country name
// Output:
// ["Oranjestad","Kabul","Luanda","The Valley","Mariehamn","Tirana", ... ]
````
It's the same as :
```typescript
import {capitals} from "country-list-ts";
const c = (await capitals()).sort(); // reorder alphabetically
// Output:
// ['Abu Dhabi', 'Abuja', 'Accra', 'Adamstown', 'Addis Ababa', ... ]
```
| function call | alias |
|-------------------------|--------------------------|
| `ls("cca2")` | `cca2s()` |
| `ls("tld") ` | `tlds()` |
| `ls("ccn3")` | `ccn3s() ` |
| `ls("cca3")` | `cca3s()` |
| `ls("cioc")` | `ciocs()` |
| `ls("countryStatus")` | `countryStatuses()` |
| `ls("commonName") ` | `commonNames()` |
| `ls("officialName") ` | `officialNames()` |
| `ls("currencyCode")` | `currencyCodes()` |
| `ls("currencyName")` | `currencyNames()` |
| `ls("currencySymbol")` | `currencySymbols()` |
| `ls("region")` | `regions()` |
| `ls("subRegion")` | `subRegions()` |
| `ls("capital")` | `capitals()` |
| `ls("lang")` | `langs()` |
| `ls("languageName")` | `languageNames()` |
#### Tagged lists
```typescript
import {lsF} from "country-list-ts";
const currencies = await lsF("currencies");
// Output:
// [
// { "currencies":{"AWG":{"name":"Aruban florin","symbol":"ƒ"}},"cca2":"AW"},
// { "currencies":{"AFN":{"name":"Afghan afghani","symbol":"؋"}},"cca2":"AF"},
// ...
//]
```
Here is an example with Angular ngFor:
````typescript
@Component({
selector: 'app-select-country',
template: '<select> ' +
'<option *ngFor="let country of $countryList | async" [ngValue]="country.cca2">' +
'{{country.name.official}}' +
'</option> ' +
'</select>',
styleUrls: ['./select-country.scss']
})
export class SelectCountryComponent {
public $countryList = lsF(); // default list name
}
````
#### Mapped list
```typescript
import {lsM} from "country-list-ts";
const gps = await lsM("latLng");
// Output:
// {"AW":[12.5,-69.96666666],"AF":[33,65],"AO":[-12.5,18.5],"AI":[18.25,-63.16666666],....]
```
Note, for tagged and mapped lists the available property values are:
<p>
name, tld, ccn3, cca3, cioc, independent, idd, countryStatus, currencies, region, subRegion, capitals, languages, translations, latLng, landlocked, borders, area, flag, demonyms, callingCodes
</p>
### All
You can get a list of all the country data:
```typescript
import {all} from "country-list-ts";
/**
* @var {Country[]}
*/
const countries = await all();
```
An example of a Country object :
```typescript
const austria = {
name: {
common: "Austria",
official: "Republic of Austria",
native: {
bar: {
official: "Republik Österreich",
common: "Österreich"
}
}
},
tld: [".at"],
cca2: "AT",
ccn3: "040",
cca3: "AUT",
cioc: "AUT",
independent: true,
status: "officially-assigned",
unMember: true,
currencies: {
EUR: {
name: "Euro",
symbol: "€"
}
},
idd: {
"root": "+4",
"suffixes": ["3"]
},
capital: ["Vienna"],
altSpellings: ["AT", "Osterreich", "Oesterreich"],
region: "Europe",
subregion: "Western Europe",
languages: {
bar: "Austro-Bavarian German"
},
translations: {
cym: {official: "Republic of Austria", common: "Awstria"},
deu: {official: "Republik Österreich", common: "Österreich"},
fra: {official: "République d'Autriche", common: "Autriche"},
hrv: {official: "Republika Austrija", common: "Austrija"},
ita: {official: "Repubblica d'Austria", common: "Austria"},
jpn: {official: "オーストリア共和国", common: "オーストリア"},
nld: {official: "Republiek Oostenrijk", common: "Oostenrijk"},
por: {official: "República da Áustria", common: "Áustria"},
rus: {official: "Австрийская Республика", common: "Австрия"},
spa: {official: "República de Austria", common: "Austria"}
},
latlng: [47.33333333, 13.33333333],
demonyms: {
fra: {
f: "Autrichienne",
m: "Autrichien"
},
spa: {
f: "Austriaco",
m: "Austriaca"
}
},
landlocked: true,
borders: ["CZE", "DEU", "HUN", "ITA", "LIE", "SVK", "SVN", "CHE"],
area: 83871,
callingCodes: ["+43"],
flag: "🇦🇹"
}
```
Definition:
- `name`
- `common` - common name in english
- `official` - official name in english
- `native` - list of all native names
- key: three-letter ISO 639-3 language code
- value: name object
- key: official - official name translation
- key: common - common name translation
- `tld` - country code top-level domain
- `cca2` - code ISO 3166-1 alpha-2
- `cca3` - code ISO 3166-1 alpha-3
- `ccn3` - code ISO 3166-1 numeric
- `cioc` - code International Olympic Committee
- `independent` - ISO 3166-1 independence status (denotes the country is considered a sovereign state)
- `status` - ISO 3166-1 assignment status
- `unMember` - UN Member status
- `currencies` - list of all currencies
- key: ISO 4217 currency code
- value: currency object
- key: `name` name of the currency
- key: `symbol` symbol of the currency
- `idd` - International Direct Dialing info
- `root` - the root geographical code prefix. e.g. +6 for New Zealand, +4 for UK.
- `suffixes` - list of all suffixes assigned to this country. 4 for NZ, 809, 829, and 849 for Dominican Republic.
- `capital` - capital city(ies)
- `altSpellings` - alternative spellings
- `region`
- `subregion`
- `languages` - list of official languages
- key: three-letter ISO 639-3 language code
- value: name of the language in english
- `translations` - list of name translations
- key: three-letter ISO 639-3 language code
- value: name object
- key: official - official name translation
- key: common - common name translation
- `latlng` - latitude and longitude
- `demonyms` - name of residents, translated & gendered
- key: three-letter ISO 639-3 language code
- value: genderized demonym object
- key: `f` (female) or `m` (male)
- value: genderized demonym translation
- `landlocked` - landlocked status, if the country has direct access to ports for its maritime trade
- `borders` - land borders
- `area` - land area in km²
- `flag` - Emoji flag
- `callingCodes` - calling codes
### Search
You can search for a country using the property name:
```typescript
import {find} from "country-list-ts";
/**
* @var {Country}
*/
const haiti = await find("name.common", "Haiti") ;
const {capital} = await find("name.common", "Canada"); // ["Ottawa"]
```
The `find` frunction returns the first Country that satisfies the search value. To get a list use `get`
```typescript
import {get} from "country-list-ts";
/**
* @var {Country[]}
*/
const tropicals = await get("region", "Caribbean") ;
```
Both `find` and `get` are memoized;
### Assets
#### Flags
#### Geo-JSON
#### Topo-JSON
## Extend
For specific use case you can combine it with othe libraries:
### Fuzzy search
[Fuse.js](https://fusejs.io/) is a powerful, lightweight fuzzy-search library, with zero dependencies.
Generally speaking, fuzzy searching (more formally known as approximate string matching) is the technique of finding strings that are approximately equal to a given pattern (rather than exactly
You can use FuseJS for country list suggestion/TypeHead input
````javascript
import {all} from "country-list-ts";
import Fuse from 'fuse.js';
const countries = await all();
const fuse = new Fuse(countries, {
keys: ['cca2', 'cca3', 'name.common']
})
const found = fuse.search('hait');
// Output:
// [
// {
// item: {
// {
// ...
// "tld": [".ht"],
// "cca2": "HT",
// ...
// }
// },
// refIndex: 0
// },
// ...
// ]
````
More examples :
- [Search String Array](https://fusejs.io/examples.html#search-string-array)
- [Search Object Array](https://fusejs.io/examples.html#search-object-array)
- [Nested Search - dot notation](https://fusejs.io/examples.html#nested-search)
- [Weighted Search](https://fusejs.io/examples.html#weighted-search)
- [Extended Search](https://fusejs.io/examples.html#extended-search)
### Phone number
[libphonenumber-js](https://www.npmjs.com/package/libphonenumber-js) is a simpler and smaller rewrite of Google Android's libphonenumber library in javascript.
See the [demo](https://catamphetamine.gitlab.io/libphonenumber-js/).
You can use this library to get the country of a phone number:
```typescript
// my-file.ts
import parsePhoneNumber from 'libphonenumber-js';
import {find} from "country-list-ts";
function getCountryByPhonenumber(phone: string) {
const phoneNumber = parsePhoneNumber(phone);
if (phoneNumber) {
return find("cca2", phoneNumber.country);
}
return undefined;
}
/**
* @var {Country|undefined}
*/
const country = find("+50934524301");
console.log(country?.name?.common, country?.flag); // Haiti 🇭🇹
```
## Licence
MIT