API Documentation - Endpoints & Examples

Installation

Install the SDK using npm, yarn or pnpm:

npm install @countrydataapi/sdk

yarn add @countrydataapi/sdk

pnpm add @countrydataapi/sdk

Quick Start

import { CountryDataApi } from '@countrydataapi/sdk';

const api = new CountryDataApi({
  apiKey: 'your-api-key'
});

// Get all countries
const countries = await api.countries.getAll({ lang: 'en' });
console.log(countries.data);

// Get country by ISO code
const spain = await api.countries.getByCode({ code: 'ES' });
console.log(spain.data[0].country_name); // "Spain"

Configuration

const api = new CountryDataApi({
  apiKey: 'your-api-key',           // Required
  baseUrl: 'https://api.countrydataapi.com', // Optional
  timeout: 30000,                    // Optional (ms)
  defaultLanguage: 'en'              // Optional
});

Countries

// Get all countries
const countries = await api.countries.getAll({
  fields: 'id,country_name,country_flag_svg',
  lang: 'es',
  limit: 50
});

// Get country by name
const spain = await api.countries.getByName({ name: 'Spain' });

// Get country by ISO code (alpha-2, alpha-3, or numeric)
const country = await api.countries.getByCode({ code: 'ES' });

// Get countries by region
const european = await api.countries.getByRegion({ region: 'Europe' });

// Get countries by currency
const euroCountries = await api.countries.getByCurrency({ currency: 'EUR' });

// Get countries by language
const spanishSpeaking = await api.countries.getByLanguage({ language: 'spa' });

// Get countries by timezone
const utcCountries = await api.countries.getByTimezone({ timezone: 'UTC' });

States

// Get all states
const allStates = await api.states.getAll();

// Get states by country
const spanishStates = await api.states.getByCountry({ country: 'Spain' });

// Get states by city
const states = await api.states.getByCity({ city: 'Madrid' });

// Get states by zipcode
const statesByZip = await api.states.getByZipcode({ zipcode: '28001' });

Cities

// Get all cities
const allCities = await api.cities.getAll({ limitToken: 100 });

// Get city by name
const madrid = await api.cities.get({ city: 'Madrid' });

// Get cities by country
const spanishCities = await api.cities.getByCountry({ country: 'Spain' });

// Get cities by state
const madridCities = await api.cities.getByState({ state: 'Madrid' });

Zipcodes

// Get zipcodes by country
const zipcodes = await api.zipcodes.getByCountry({ country: 'Spain' });

// Get zipcodes by state
const stateZipcodes = await api.zipcodes.getByState({ state: 'Madrid' });

// Get zipcodes by region
const europeanZipcodes = await api.zipcodes.getByRegion({ region: 'Europe' });

Select (Optimized for Dropdowns)

These endpoints cost only 1 token regardless of the number of results, making them perfect for populating dropdowns:

// Get countries for dropdown
const countriesSelect = await api.select.countries({ lang: 'es' });
// Returns: [{ id: 'ES', name: 'Spain', code: 'ES', phone_code: '+34', flag: '🇪🇸' }, ...]

// Get states for dropdown
const statesSelect = await api.select.states({ country: 'ES' });
// Returns: [{ id: 'MD', name: 'Madrid' }, ...]

// Get cities for dropdown
const citiesSelect = await api.select.cities({ state: 'Madrid', country: 'ES' });
// Returns: [{ id: '28001', name: 'Madrid' }, ...]

Check Token Status

const status = await api.getStatus();
console.log(`Remaining tokens: ${status.remainingTokens}`);

Request Options

All methods accept these common options:

Error Handling

import {
  CountryDataApi,
  AuthenticationError,
  InsufficientTokensError
} from '@countrydataapi/sdk';

try {
  const countries = await api.countries.getAll();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof InsufficientTokensError) {
    console.error('No tokens remaining');
  } else {
    console.error('API error:', error.message);
  }
}

TypeScript Support

Full TypeScript support with all types exported:

import type {
  Country,
  State,
  City,
  ApiResponse,
  Language
} from '@countrydataapi/sdk';

const response: ApiResponse<Country> = await api.countries.getByCode({
  code: 'ES'
});

const country: Country = response.data[0];
console.log(country.country_name);

React Example

import { useEffect, useState } from 'react';
import { CountryDataApi, Country } from '@countrydataapi/sdk';

const api = new CountryDataApi({ apiKey: 'your-api-key' });

function CountryList() {
  const [countries, setCountries] = useState<Country[]>([]);

  useEffect(() => {
    api.countries.getAll({ limit: 10 })
      .then(response => setCountries(response.data));
  }, []);

  return (
    <ul>
      {countries.map(country => (
        <li key={country.id}>{country.country_name}</li>
      ))}
    </ul>
  );
}

Vue Example

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { CountryDataApi, Country } from '@countrydataapi/sdk';

const api = new CountryDataApi({ apiKey: 'your-api-key' });
const countries = ref<Country[]>([]);

onMounted(async () => {
  const response = await api.countries.getAll({ limit: 10 });
  countries.value = response.data;
});
</script>

<template>
  <ul>
    <li v-for="country in countries" :key="country.id">
      {{ country.country_name }}
    </li>
  </ul>
</template>

Links

• npm Package
• GitHub Repository
• Get API Key