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.
npm install @yusifaliyevpro/countriesThe 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 🗺️getCountriesByCodesgetCountriesByNamegetCountriesByRegiongetCountriesBySubregiongetCountriesByLanggetCountriesByCurrencygetCountryByCodegetCountryByCapitalgetCountryByTranslationgetCountryByDemonym
Additional information:
defineFields functionCountryPicker TypeFetch OptionsType Definitions && Available TypesAvailable FieldsError handling
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.
fields: An array of country fields to retrieve (NOT OPTIONAL - As mandated by Alejandro Matos. see: Issue)independent: Filter by independent countries iftrue(optional - default: all countries).
import { getCountries } from "@yusifaliyevpro/countries";
// Fetch all countries and fields
const countries = await getCountries();
// Fetch all countries with specific fields
const countries = await getCountries({
fields: ["name", "capital"],
});
// Fetch independent countries with specific fields
const independentCountries = await getCountries({
independent: true,
fields: ["name", "capital"],
});Fetches countries by given codes.
codes: Array of country CCA3, CCA2, CCN3, CIOC codes (case-insensitive) (autocomplete).fields(optional): Array of fields to retrieve.
import { getCountriesByCodes } from "@yusifaliyevpro/countries";
// Fetch selected countries with specific fields
const data = await getCountriesByCodes({
codes: ["USA", "AZ", "268", "TR", "170", "FR", "EST"],
fields: ["name", "capital", "region"],
});Fetches countries by given codes.
name: Search by country name (case-insensitive).fullText: Search by country’s full name (default: false) (boolean).fields(optional): Array of fields to retrieve.
import { getCountriesByName } from "@yusifaliyevpro/countries";
// Fetch countries which matches this query with specific fields
const data = await getCountriesByName({
name: "deutschland",
fields: ["name", "capital", "demonyms", "cioc"],
});
// It will return null because 'deutschland' is a common name
const data = await getCountriesByName({
name: "deutschland",
fullText: true,
fields: ["name", "capital", "demonyms", "cioc"],
});
// Fetch countries which matches this query with specific fields
const data = await getCountriesByName({
name: "aruba",
fullText: true,
fields: ["name", "capital", "demonyms", "cioc"],
});Fetches countries by region name.
region: Name of region you want to fetch (case-insensitive) (autocomplete).fields(optional): Array of fields to retrieve.
import { getCountriesByRegion } from "@yusifaliyevpro/countries";
// Fetch Countries which are located in America
const data = await getCountriesByRegion({
region: "Americas",
});Fetches countries by subregion name.
subregion: Name of subregion you want to fetch (case-insensitive) (autocomplete).fields(optional): Array of fields to retrieve.
import { getCountriesBySubregion } from "@yusifaliyevpro/countries";
// Fetch all countries which locates in Central Europe
// with specific fields
const data = await getCountriesBySubregion({
subregion: "Central Europe",
fields: ["capital", "area", "population"],
});Fetches countries by language.
lang: Language of countries you want to fetch (case-insensitive) (autocomplete).fields(optional): Array of fields to retrieve.
import { getCountriesByLang } from "@yusifaliyevpro/countries";
// Fetch countries which speaks Spanish with all fields
const data = await getCountriesByLang({
lang: "Spanish",
});Fetches countries by currency.
currency: Currency of countries you want to fetch (case-insensitive) (autocomplete).fields(optional): Array of fields to retrieve.
import { getCountriesByCurrency } from "@yusifaliyevpro/countries";
// Fetch countries which use Euro with specific fields
const data = await getCountriesByCurrency({
currency: "Euro",
fields: ["car", "capital", "fifa", "cca3"],
});Fetches country data by code.
code: The countryCCA3, CCA2, CCN3 or CIOC code (case-insensitive) (autocomplete).fields(optional): Array of fields to retrieve.
import { getCountryByCode } from "@yusifaliyevpro/countries";
// Fetch Azerbaijan with all fields
const azerbaijan = await getCountryByCode({
code: "AZE",
});
// Fetch Germany with specific fields
const germany = await getCountryByCode({
code: "GER",
fields: ["name", "cca2", "population"],
});Fetches country data based on the capital city.
capital: Capital city name (case-insensitive) (autocomplete).fields(optional): Array of fields to retrieve.
import { getCountryByCapital } from "@yusifaliyevpro/countries";
// Fetch Germany with specific fields
const germany = await getCountryByCapital({
capital: "Berlin",
fields: ["name", "flag", "currencies"],
});Fetches a country by its translation.
translation: Translation of the name of country you want to fetch (case-insensitive).fields(optional): Array of fields to retrieve.
import { getCountryByTranslation } from "@yusifaliyevpro/countries";
// Fetch country which has translation "alemania" with specific fields
const germany = await getCountryByTranslation({
translation: "alemania",
fields: ["car", "capital", "fifa", "cca3"],
});Fetches a country by its demonym.
demonym: Demonym of the citizenship of country you want to fetch (case-insensitive).fields(optional): Array of fields to retrieve.
import { getCountryByDemonym } from "@yusifaliyevpro/countries";
// Fetch the country whose citizens are called "Peruvian" with specific fields
const peru = await getCountryByDemonym({
demonym: "peruvian",
fields: ["car", "capital", "fifa", "cca3"],
});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.
fetchOptions: An object containing any valid options for thefetchAPI (optional).
import { getCountries, getCountryByCode } from "@yusifaliyevpro/countries";
// Example 1: Vanilla JavaScript Use Case
// Note: REST Countries doesn't need API Token or method, just example
const countries = await getCountries(
{ fields: ["name", "capital"] },
{ headers: { Authorization: "Bearer YOUR_API_TOKEN" }, method: "GET" }
);
// Example 2: Next.js with Cache Fetch Options
const germany = await getCountryByCode(
{ code: "GER", fields: ["name", "capital"] },
{ next: { revalidate: 7 * 24 * 3600 }, cache: "force-cache" }
);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 namestld: Top-level domaincca2,ccn3,cca3,cioc: Country codesindependent: Boolean flagstatus: Status of the countryunMember: UN membership statuscurrencies: Currency informationidd: International dialing infocapital: Capital cityaltSpellings: Alternative spellingsregion,subregion: Region infolanguages: Languages spokentranslations: Translations of country namelatlng: Latitude and longitudelandlocked: Boolean flagborders: Bordering countriesarea: Area in square kilometersdemonyms: Demonymsflag: Emoji flagmaps: Google and OpenStreetMap linkspopulation: Population countgini: GINI coefficientfifa: FIFA codecar: Car signs and driving sidetimezones: List of timezonescontinents: List of continentsflags: Object with PNG and SVG flag URLscoatOfArms: Coat of arms imagesstartOfWeek: Start of the weekcapitalInfo: Capital coordinatespostalCode: Postal code format
const country = await getCountryByCode({
code: "TUR",
fields: ["name", "capital", "population"],
});This package exports TypeScript type definitions for working with country data. You can import these types from the dedicated types subpath:
import type { Country, Region, Cca2Code } from "@yusifaliyevpro/countries/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
import { getAllCountries } from "@yusifaliyevpro/countries";
import type { Country, Cca2Code } from "@yusifaliyevpro/countries/types";
// Type-safe country code
const countryCode: Cca2Code = "US";
// Get countries with proper typing
// You don't need to specify Country[], return type will be automaticaly inferred
const countries: Country[] = getAllCountries();
// Type-safe function parameters
// Of course you can use this package's type-safe getCountryByCode method too
function getCountryByCode(code: Cca2Code): Country | undefined {
return countries.find((country) => country.cca2 === code);
}All types provide autocompletion and type checking for better developer experience when working with country data.
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.
import { defineFields, getCountryByCode } from "@yusifaliyevpro/countries";
const countryFields = defineFields(["name", "capital", "population", "region", "cca3", "flags"]);
const country = getCountryByCode({ code: "ger", fields: countryFields });Now countryFields is fully typed and you can reuse it safely across your app.
CountryPicker is a generic type that takes the fields array and returns a country type containing only those fields.
// src/lib/fields.ts - Define countryFields
export const countryFields = defineFields(["name", "capital", "population", "region"]);
// src/app/page.tsx
// Fetch data in Page component
export default function CountryPage() {
const country = await getCountryByCode({ code: "AZ", fields: countryFields });
return (
<main>
<CountryCard country={country} />
</main>
);
}
// src/components/CountryCard.tsx
// Use in component safely
export function CountryCard({ country }: { country: CountryPicker<typeof countryFields> }) {
return <div>{country.name.common}</div>;
}- No need for manual type definition for returned country.
- Type-safe fields: Autocomplete and error checking for fields.
- Reusability: Use same
fieldsand type across app. - Prevents mistakes when accessing fields not fetched.
Errors are handled gracefully, type-safe, and logged to the console.
const data = await getCountryByCode({
code: "XXX",
fields: ["name"],
}); // data will be null and an error message will be logged to console (by library)
const usa = await getCountryByCode({
code: "usa",
fields: ["name", "population"],
});
// TypeScript Error, because you didn't add 'capital' to fields parameter
console.log(usa.capital);
^^^^^^^
// Type error due the 'mykey' is not in the available fields list
const georgia = await getCountryByCode({
code: "geo",
fields: ["name", "mykey"],
});MIT License.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}