REST Countries Typed API Package 🇦🇿 🇵🇪

This package provides an easy and TYPE-SAFE way to interact with the Rest Countries API, which offers detailed information about countries worldwide. You can fetch country data using various parameters like CCA2/CCA3/CIOC/CCN3 codes, capital cities, languages, regions, subregions, translations, demonyms, currencies. Thanks to Alejandro Matos for this API.

Installation

1npm install @yusifaliyevpro/countries

Usage

The package uses latest verison v3.1 of API and exports several utility functions for interacting with the Rest Countries API. All Parameter returns are type-safe. The return type changes if you change fields paramater. I suggest to use CCA3 in the functions because it is very precise. For example only 206 out of 250 countries have CIOC code.

Note: If you don't set the fields parameter, all data will be fetched.

The List of functions:

• getCountries 🗺️
• getCountriesByCodes
• getCountriesByName
• getCountriesByRegion
• getCountriesBySubregion
• getCountriesByLang
• getCountriesByCurrency
• getCountryByCode
• getCountryByCapital
• getCountryByTranslation
• getCountryByDemonym

Additional information:

• defineFields function
• CountryPicker Type
• Fetch Options
• Type Definitions && Available Types
• Available Fields
• Error handling

---

getCountries

Fetches all countries or filters them based on independence status. Note: Some countries do not have an independent value (due to political reasons), so they won't be fetched if you set the independent parameter.

Parameters:

• fields: An array of country fields to retrieve (NOT OPTIONAL - As mandated by Alejandro Matos. see: Issue)
• independent: Filter by independent countries if true (optional - default: all countries).

Example:

1import { getCountries } from "@yusifaliyevpro/countries";
2
3// Fetch all countries and fields
4const countries = await getCountries();
5
6// Fetch all countries with specific fields
7const countries = await getCountries({
8  fields: ["name", "capital"],
9});
10
11// Fetch independent countries with specific fields
12const independentCountries = await getCountries({
13  independent: true,
14  fields: ["name", "capital"],
15});

---

getCountriesByCodes

Fetches countries by given codes.

Parameters:

• codes: Array of country CCA3, CCA2, CCN3, CIOC codes (case-insensitive) (autocomplete).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountriesByCodes } from "@yusifaliyevpro/countries";
2
3// Fetch selected countries with specific fields
4const data = await getCountriesByCodes({
5  codes: ["USA", "AZ", "268", "TR", "170", "FR", "EST"],
6  fields: ["name", "capital", "region"],
7});

---

getCountriesByName

Fetches countries by given codes.

Parameters:

• name: Search by country name (case-insensitive).
• fullText: Search by country’s full name (default: false) (boolean).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountriesByName } from "@yusifaliyevpro/countries";
2
3// Fetch countries which matches this query with specific fields
4const data = await getCountriesByName({
5  name: "deutschland",
6  fields: ["name", "capital", "demonyms", "cioc"],
7});
8
9// It will return null because 'deutschland' is a common name
10const data = await getCountriesByName({
11  name: "deutschland",
12  fullText: true,
13  fields: ["name", "capital", "demonyms", "cioc"],
14});
15
16// Fetch countries which matches this query with specific fields
17const data = await getCountriesByName({
18  name: "aruba",
19  fullText: true,
20  fields: ["name", "capital", "demonyms", "cioc"],
21});

---

getCountriesByRegion

Fetches countries by region name.

Parameters:

• region: Name of region you want to fetch (case-insensitive) (autocomplete).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountriesByRegion } from "@yusifaliyevpro/countries";
2
3// Fetch Countries which are located in America
4const data = await getCountriesByRegion({
5  region: "Americas",
6});

---

getCountriesBySubregion

Fetches countries by subregion name.

Parameters:

• subregion: Name of subregion you want to fetch (case-insensitive) (autocomplete).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountriesBySubregion } from "@yusifaliyevpro/countries";
2
3// Fetch all countries which locates in Central Europe
4// with specific fields
5const data = await getCountriesBySubregion({
6  subregion: "Central Europe",
7  fields: ["capital", "area", "population"],
8});

---

getCountriesByLang

Fetches countries by language.

Parameters:

• lang: Language of countries you want to fetch (case-insensitive) (autocomplete).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountriesByLang } from "@yusifaliyevpro/countries";
2
3// Fetch countries which speaks Spanish with all fields
4const data = await getCountriesByLang({
5  lang: "Spanish",
6});

---

getCountriesByCurrency

Fetches countries by currency.

Parameters:

• currency: Currency of countries you want to fetch (case-insensitive) (autocomplete).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountriesByCurrency } from "@yusifaliyevpro/countries";
2
3// Fetch countries which use Euro with specific fields
4const data = await getCountriesByCurrency({
5  currency: "Euro",
6  fields: ["car", "capital", "fifa", "cca3"],
7});

---

getCountryByCode

Fetches country data by code.

Parameters:

• code: The country CCA3, CCA2, CCN3 or CIOC code (case-insensitive) (autocomplete).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountryByCode } from "@yusifaliyevpro/countries";
2
3// Fetch Azerbaijan with all fields
4const azerbaijan = await getCountryByCode({
5  code: "AZE",
6});
7
8// Fetch Germany with specific fields
9const germany = await getCountryByCode({
10  code: "GER",
11  fields: ["name", "cca2", "population"],
12});

---

getCountryByCapital

Fetches country data based on the capital city.

Parameters:

• capital: Capital city name (case-insensitive) (autocomplete).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountryByCapital } from "@yusifaliyevpro/countries";
2
3// Fetch Germany with specific fields
4const germany = await getCountryByCapital({
5  capital: "Berlin",
6  fields: ["name", "flag", "currencies"],
7});

---

getCountryByTranslation

Fetches a country by its translation.

Parameters:

• translation: Translation of the name of country you want to fetch (case-insensitive).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountryByTranslation } from "@yusifaliyevpro/countries";
2
3// Fetch country which has translation "alemania" with specific fields
4const germany = await getCountryByTranslation({
5  translation: "alemania",
6  fields: ["car", "capital", "fifa", "cca3"],
7});

---

getCountryByDemonym

Fetches a country by its demonym.

Parameters:

• demonym: Demonym of the citizenship of country you want to fetch (case-insensitive).
• fields (optional): Array of fields to retrieve.

Example:

1import { getCountryByDemonym } from "@yusifaliyevpro/countries";
2
3// Fetch the country whose citizens are called "Peruvian" with specific fields
4const peru = await getCountryByDemonym({
5  demonym: "peruvian",
6  fields: ["car", "capital", "fifa", "cca3"],
7});

---

Fetch Options

The package supports custom fetchOptions to provide additional configurations for the underlying fetch requests. This is useful for scenarios like adding custom headers, enabling caching, or setting timeouts.

Parameters:

• fetchOptions: An object containing any valid options for the fetch API (optional).

Example Usage

1import { getCountries, getCountryByCode } from "@yusifaliyevpro/countries";
2
3// Example 1: Vanilla JavaScript Use Case
4// Note: REST Countries doesn't need API Token or method, just example
5const countries = await getCountries(
6  { fields: ["name", "capital"] },
7  { headers: { Authorization: "Bearer YOUR_API_TOKEN" }, method: "GET" }
8);
9
10// Example 2: Next.js with Cache Fetch Options
11const germany = await getCountryByCode(
12  { code: "GER", fields: ["name", "capital"] },
13  { next: { revalidate: 7 * 24 * 3600 }, cache: "force-cache" }
14);

---

Available Fields

You can specify which fields to retrieve. The fields parameter will give autocomplete suggestions. Full list of available fields:

• name: Object with common, official, and native names
• tld: Top-level domain
• cca2, ccn3, cca3, cioc: Country codes
• independent: Boolean flag
• status: Status of the country
• unMember: UN membership status
• currencies: Currency information
• idd: International dialing info
• capital: Capital city
• altSpellings: Alternative spellings
• region, subregion: Region info
• languages: Languages spoken
• translations: Translations of country name
• latlng: Latitude and longitude
• landlocked: Boolean flag
• borders: Bordering countries
• area: Area in square kilometers
• demonyms: Demonyms
• flag: Emoji flag
• maps: Google and OpenStreetMap links
• population: Population count
• gini: GINI coefficient
• fifa: FIFA code
• car: Car signs and driving side
• timezones: List of timezones
• continents: List of continents
• flags: Object with PNG and SVG flag URLs
• coatOfArms: Coat of arms images
• startOfWeek: Start of the week
• capitalInfo: Capital coordinates
• postalCode: Postal code format

Example with fields:

1const country = await getCountryByCode({
2  code: "TUR",
3  fields: ["name", "capital", "population"],
4});

---

Type Definitions

This package exports TypeScript type definitions for working with country data. You can import these types from the dedicated types subpath:

1import type { Country, Region, Cca2Code } from "@yusifaliyevpro/countries/types";

Available Types

Note: If a long time has passed since the last update, the type data may be outdated.

• Country: Comprehensive type for country objects with properties like name, codes, currencies, languages, etc.
• Cca2Code: ISO 3166-1 alpha-2 country codes (two-letter) (accept any string ✅)
• Cca3Code: ISO 3166-1 alpha-3 country codes (three-letter) (accept any string ✅)
• Ccn3Code: ISO 3166-1 numeric country codes (accept any string ✅)
• CiocCode: International Olympic Committee country codes (accept any string ✅)
• Capital: Capital city names (accept any string ✅)
• Region: World regions (e.g., "Africa", "Americas")
• Subregion: World subregions (e.g., "Northern Africa", "South America") (accept any string ✅)
• Lang: Language codes (accept any string ✅)
• Currency: Currency codes (accept any string ✅)
• SupportedLanguages: Languages supported for translations

Example Usage

1import { getAllCountries } from "@yusifaliyevpro/countries";
2import type { Country, Cca2Code } from "@yusifaliyevpro/countries/types";
3
4// Type-safe country code
5const countryCode: Cca2Code = "US";
6
7// Get countries with proper typing
8// You don't need to specify Country[], return type will be automaticaly inferred
9const countries: Country[] = getAllCountries();
10
11// Type-safe function parameters
12// Of course you can use this package's type-safe getCountryByCode method too
13function getCountryByCode(code: Cca2Code): Country | undefined {
14  return countries.find((country) => country.cca2 === code);
15}

All types provide autocompletion and type checking for better developer experience when working with country data.

---

defineFields

defineFields is a helper function that lets you define your fields array with autocomplete and type checking, and automatically infers a special type for those fields. Of course you can pass fields parameter directly and it will give you type-checking too. But sometimes you can need to export fields to use in another file.

Example:

1import { defineFields, getCountryByCode } from "@yusifaliyevpro/countries";
2
3const countryFields = defineFields(["name", "capital", "population", "region", "cca3", "flags"]);
4
5const country = getCountryByCode({ code: "ger", fields: countryFields });

Now countryFields is fully typed and you can reuse it safely across your app.

---

CountryPicker<typeof fields>

CountryPicker is a generic type that takes the fields array and returns a country type containing only those fields.

⚡ Example Full Usage

1// src/lib/fields.ts - Define countryFields
2export const countryFields = defineFields(["name", "capital", "population", "region"]);
3
4// src/app/page.tsx
5// Fetch data in Page component
6export default function CountryPage() {
7  const country = await getCountryByCode({ code: "AZ", fields: countryFields });
8  return (
9    <main>
10      <CountryCard country={country} />
11    </main>
12  );
13}
14
15// src/components/CountryCard.tsx
16// Use in component safely
17export function CountryCard({ country }: { country: CountryPicker<typeof countryFields> }) {
18  return <div>{country.name.common}</div>;
19}

---

✅ Benefits

• No need for manual type definition for returned country.
• Type-safe fields: Autocomplete and error checking for fields.
• Reusability: Use same fields and type across app.
• Prevents mistakes when accessing fields not fetched.

---

Error Handling

Errors are handled gracefully, type-safe, and logged to the console.

Example:

1const data = await getCountryByCode({
2  code: "XXX",
3  fields: ["name"],
4}); // data will be null and an error message will be logged to console (by library)
5
6const usa = await getCountryByCode({
7  code: "usa",
8  fields: ["name", "population"],
9});
10
11// TypeScript Error, because you didn't add 'capital' to fields parameter
12console.log(usa.capital);
13                ^^^^^^^
14// Type error due the 'mykey' is not in the available fields list
15const georgia = await getCountryByCode({
16  code: "geo",
17  fields: ["name", "mykey"],
18});

---

License

MIT License.