Country Data API - TypeScript/JavaScript SDK

Official SDK for the Country Data API, providing easy access to geographical data including countries, states, cities, and postal codes worldwide.

Installation

npm install @countrydataapi/sdk
# or
yarn add @countrydataapi/sdk
# or
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"

// Get states for a country
const states = await api.states.getByCountry({ country: 'Spain' });
console.log(states.data);

// Get cities for a state
const cities = await api.cities.getByState({ state: 'Madrid' });
console.log(cities.data);

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

Configuration

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

API Reference

Countries

// Get all countries
api.countries.getAll(options?)

// Get country by name
api.countries.getByName({ name: 'Spain', ...options })

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

// Get countries by region
api.countries.getByRegion({ region: 'Europe', ...options })

// Get countries by currency
api.countries.getByCurrency({ currency: 'EUR', ...options })

// Get countries by language
api.countries.getByLanguage({ language: 'spa', ...options })

// Get countries by timezone
api.countries.getByTimezone({ timezone: 'Europe/Madrid', ...options })

States

// Get all states
api.states.getAll(options?)

// Get states by country
api.states.getByCountry({ country: 'Spain', ...options })

// Get states by city
api.states.getByCity({ city: 'Madrid', ...options })

// Get states by zipcode
api.states.getByZipcode({ zipcode: '28001', ...options })

Cities

// Get all cities
api.cities.getAll(options?)

// Get city by name
api.cities.get({ city: 'Madrid', ...options })

// Get cities by country
api.cities.getByCountry({ country: 'Spain', ...options })

// Get cities by state
api.cities.getByState({ state: 'Madrid', ...options })

Zipcodes

// Get all zipcodes
api.zipcodes.getAll(options?)

// Get zipcodes by country
api.zipcodes.getByCountry({ country: 'Spain', ...options })

// Get zipcodes by state
api.zipcodes.getByState({ state: 'Madrid', ...options })

// Get zipcodes by region
api.zipcodes.getByRegion({ region: 'Europe', ...options })

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 select
api.select.countries({ lang: 'es' })

// Get states for select
api.select.states({ country: 'ES', lang: 'es' })

// Get cities for select
api.select.cities({ state: 'Madrid', country: 'ES', lang: 'es' })

Request Options

All methods accept these common options:

| Option | Type | Description | |--------|------|-------------| | fields | string | Comma-separated list of fields to return | | lang | 'en' \| 'es' \| 'pt' \| 'fr' \| 'de' \| 'it' | Response language | | limit | number | Maximum number of items to return | | limitToken | number | Maximum tokens to use for this request |

Response Format

All methods return an ApiResponse<T> object:

interface ApiResponse<T> {
  success: boolean;
  data: T[];
  count: number;
  tokens_used: number;
  remaining_tokens?: number;
}

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

This SDK is written in TypeScript and provides full type definitions:

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);

License

MIT

Links

• Documentation
• API Reference
• Get API Key