@kinkiwi/restcountries-sdk
Version:
Rest countries SDK
156 lines (107 loc) • 4.3 kB
Markdown
> A TypeScript-first SDK for the [REST Countries v3.1 API](https://restcountries.com/), designed with SOLID principles and a clean developer experience.
---
---
- 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:
```bash
npm install @kinkiwi/restcountries-sdk
```
```bash
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:
```ts
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:
```ts
const countries = await client.codes.getByCodes(['US', 'CA', 'MX']);
console.log(countries.map((c) => c.name.common));
```
```ts
const romania = await client.name.getFullText('Romania');
console.log(romania?.population);
```
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:
```ts
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:
```ts
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:
```ts
import { fieldPreset, fields } from '@kinkiwi/restcountries-sdk';
const customFields = [fields.unMember, ...fieldPreset.basic];
const countries = await client.countries.get(customFields);
console.log(countries.length);
```
The SDK uses [Axios](https://axios-http.com/) under the hood to perform HTTP requests. When a request fails, the SDK will throw an error propagated from Axios.
- **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
```ts
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();
```