@abdoseadaa/country-flags

TypeScript SDK for the Country Flags API — ISO country codes, SVG flags, city data, and dialling codes.

• Universal: works in Node.js 18+ and modern browsers
• Zero dependencies — uses the native fetch API
• Dual ESM + CJS output with full TypeScript declarations
• Default instance points to https://iso.api.gbstr.io — no config needed

Install

npm install @abdoseadaa/country-flags

Quick start

import ISO from '@abdoseadaa/country-flags';

// List countries
const { data, total } = await ISO.getCountries({ search: 'egypt', limit: 5 });

// Get a flag URL (sync — no HTTP call)
const url = ISO.getFlagUrl('EG');           // https://iso.api.gbstr.io/v1/flags/EG

// Fetch SVG markup
const svg = await ISO.getFlagSvg('EG');

// Cities for a country
const cities = await ISO.getCities('EG', { search: 'cairo' });

// Countries with dialling codes + flag URLs
const phones = await ISO.getPhoneCodes();

// Health check
const health = await ISO.getHealth();

Custom base URL

Point to a self-hosted instance or local dev server:

import { CountryFlagsClient } from '@abdoseadaa/country-flags';

const client = new CountryFlagsClient({ baseUrl: 'http://localhost:54032' });
const { data } = await client.getCountries();

API Reference

ISO (default export)

All methods are also available on CountryFlagsClient instances.

ISO.getHealth()

getHealth(): Promise<HealthResponse>

Returns server status and uptime.

const { status, uptime, timestamp } = await ISO.getHealth();

ISO.getCountries(params?)

getCountries(params?: CountriesParams): Promise<ListResponse<Country>>

| Param | Type | Description | |-------|------|-------------| | limit | number | Max results to return (default: 20) | | skip | number | Results to skip for pagination (default: 0) | | search | string | Search by country name | | region | string | Filter by region (e.g. "Asia", "Europe") |

const { data, total } = await ISO.getCountries({ region: 'Europe', limit: 10 });

ISO.getFlagUrl(code, style?)

getFlagUrl(code: string, style?: string): string

Synchronous — constructs and returns the flag URL without making an HTTP call.

const url = ISO.getFlagUrl('GB');         // https://iso.api.gbstr.io/v1/flags/GB
const flat = ISO.getFlagUrl('GB-ENG');   // sub-national flag

ISO.getFlagSvg(code, style?)

getFlagSvg(code: string, style?: string): Promise<string>

Fetches and returns the raw SVG markup for a flag.

const svg = await ISO.getFlagSvg('US');
document.getElementById('flag')!.innerHTML = svg;

ISO.getCities(code, params?)

getCities(code: string, params?: CitiesParams): Promise<ListResponse<City>>

| Param | Type | Description | |-------|------|-------------| | limit | number | Max results to return (default: 40) | | skip | number | Results to skip for pagination (default: 0) | | search | string | Search by city name |

const { data, total } = await ISO.getCities('DE', { search: 'berlin' });

ISO.getPhoneCodes()

getPhoneCodes(): Promise<ListResponse<PhoneCode>>

Returns all countries that have a dialling code, sorted alphabetically. Each entry includes flagUrl.

const { data } = await ISO.getPhoneCodes();
// data[0] → { code: 'AF', name: 'Afghanistan', callingCode: '+93', flagUrl: '...' }

Types

type CountryCode =
  | 'AF' | 'AX' | 'AL' | 'DZ' | 'AS' | 'AD' | /* ... all 250+ codes */ | 'ZW';

interface Country {
  code: CountryCode;
  name: string;
  region: string;
  subregion: string;
  callingCode: string | null;
  capital: string | null;
  currency: string | null;
  languages: string[];
  flagUrl: string;
}

interface City {
  name: string;
  lat: number;
  lng: number;
  country: CountryCode;
  admin1?: string;
  admin2?: string;
  population?: number;
}

interface PhoneCode {
  code: CountryCode;
  name: string;
  callingCode: string;
  flagUrl: string;
}

interface HealthResponse {
  status: string;
  uptime: number;
  timestamp: string;
}

interface ListResponse<T> {
  data: T[];
  total: number;
}

interface CountriesParams {
  limit?: number;
  skip?: number;
  search?: string;
  region?: string;
}

interface CitiesParams {
  limit?: number;
  skip?: number;
  search?: string;
}

interface ClientOptions {
  baseUrl?: string;
}

License

MIT