@kinkiwi/restcountries-sdk

A TypeScript-first SDK for the REST Countries v3.1 API, designed with SOLID principles and a clean developer experience.

Features

• Full TypeScript support with strict types for requests and responses
• Modular architecture with dedicated clients:
  • countries – all countries
  • codes – lookup by one or more alpha codes
  • name – search by name (with optional full-text match)
  • currency – filter by currency code
  • language – filter by spoken language
  • region – filter by region
  • subregion – filter by subregion
  • demonym – filter by demonym
  • translation – filter by translated name
• Optional field filtering using a strongly typed fields enum
• Clean, maintainable implementation based on SOLID and DRY principles
• Axios-based HTTP client with no runtime dependencies
• Designed for easy integration in both Node.js and browser-based TypeScript projects
• Enums with:
  • Region
  • Subregion
  • CountryName
  • CCA2
  • CCN3

Installation

Install the SDK via npm or yarn:

npm install @kinkiwi/restcountries-sdk

yarn add @kinkiwi/restcountries-sdk

Usage Examples

Basic Country Lookup by Code

Fetch a country by its alpha-2 code, selecting only specific fields to reduce response size:

import { RestCountries, fields } from '@kinkiwi/restcountries-sdk';

const client = new RestCountries();

async function example() {
  const country = await client.codes.getByCode('US');

  console.log(country?.name.common); // "United States"
}

example();

Retrieve multiple countries in one request:

const countries = await client.codes.getByCodes(['US', 'CA', 'MX']);

console.log(countries.map((c) => c.name.common));

Search by country name with full-text matching

const romania = await client.name.getFullText('Romania');

console.log(romania?.population);

Filtering by fields

Sometimes we do not wish to retrieve all the fields of a Country, to use the filters we have to pass a fields array as a second parameter to the call:

const romania = await client.name.getFullText('Romania', [fields.name, fields.population]);

console.log(romania?.population);

There is also a fields preset that helps you get common fields like basic, geo and identifiers, like this:

import { fieldPreset } from '@kinkiwi/restcountries-sdk';

/**
 * fieldsPreset.basic = name, region, population
 */
const countries = await client.countries.get(fieldPreset.basic);

console.log(countries.length);

You can combine them with fields you need:

import { fieldPreset, fields } from '@kinkiwi/restcountries-sdk';

const customFields = [fields.unMember, ...fieldPreset.basic];

const countries = await client.countries.get(customFields);

console.log(countries.length);

Error Handling

The SDK uses Axios under the hood to perform HTTP requests. When a request fails, the SDK will throw an error propagated from Axios.

Types of Errors

• Network errors: Issues with connectivity or DNS.
• HTTP errors: Non-2xx HTTP responses (e.g., 404 Not Found, 500 Internal Server Error).
• Timeouts or cancellation: Requests that time out or are aborted.

How Errors Are Exposed

All client methods return Promises and will throw if the request fails. You should use try/catch blocks or .catch() handlers to capture errors.

Example

import { RestCountries, fields } from '@kinkiwi/restcountries-sdk';

const client = new RestCountries();

async function fetchCountry() {
  try {
    const country = await client.codes.getByCode('XYZ', [fields.name]);
  } catch (error) {
    if (axios.isAxiosError(error)) {
      console.error('API request failed:', error.response?.status, error.response?.data);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

fetchCountry();