Dokumentation

Installation

Installieren Sie das SDK mit npm, yarn oder pnpm:

npm install @countrydataapi/sdk

yarn add @countrydataapi/sdk

pnpm add @countrydataapi/sdk

Schnellstart

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

const api = new CountryDataApi({
  apiKey: 'ihr-api-schluessel'
});

// Alle Länder abrufen
const countries = await api.countries.getAll({ lang: 'de' });
console.log(countries.data);

// Land nach ISO-Code abrufen
const germany = await api.countries.getByCode({ code: 'DE' });
console.log(germany.data[0].country_name); // "Deutschland"

Konfiguration

const api = new CountryDataApi({
  apiKey: 'ihr-api-schluessel',      // Erforderlich
  baseUrl: 'https://api.countrydataapi.com', // Optional
  timeout: 30000,                    // Optional (ms)
  defaultLanguage: 'de'              // Optional
});

Länder

// Alle Länder abrufen
const countries = await api.countries.getAll({
  fields: 'id,country_name,country_flag_svg',
  lang: 'de',
  limit: 50
});

// Land nach Name abrufen
const germany = await api.countries.getByName({ name: 'Germany' });

// Land nach ISO-Code abrufen (alpha-2, alpha-3 oder numerisch)
const country = await api.countries.getByCode({ code: 'DE' });

// Länder nach Region abrufen
const european = await api.countries.getByRegion({ region: 'Europe' });

// Länder nach Währung abrufen
const euroCountries = await api.countries.getByCurrency({ currency: 'EUR' });

// Länder nach Sprache abrufen
const germanSpeaking = await api.countries.getByLanguage({ language: 'deu' });

// Länder nach Zeitzone abrufen
const berlinTime = await api.countries.getByTimezone({ timezone: 'Europe/Berlin' });

Bundesländer

// Alle Bundesländer abrufen
const allStates = await api.states.getAll();

// Bundesländer nach Land abrufen
const germanStates = await api.states.getByCountry({ country: 'Germany' });

// Bundesländer nach Stadt abrufen
const states = await api.states.getByCity({ city: 'Berlin' });

// Bundesländer nach Postleitzahl abrufen
const statesByZip = await api.states.getByZipcode({ zipcode: '10115' });

Städte

// Alle Städte abrufen
const allCities = await api.cities.getAll({ limitToken: 100 });

// Stadt nach Name abrufen
const berlin = await api.cities.get({ city: 'Berlin' });

// Städte nach Land abrufen
const germanCities = await api.cities.getByCountry({ country: 'Germany' });

// Städte nach Bundesland abrufen
const berlinCities = await api.cities.getByState({ state: 'Berlin' });

Postleitzahlen

// Postleitzahlen nach Land abrufen
const zipcodes = await api.zipcodes.getByCountry({ country: 'Germany' });

// Postleitzahlen nach Bundesland abrufen
const stateZipcodes = await api.zipcodes.getByState({ state: 'Berlin' });

// Postleitzahlen nach Region abrufen
const europeanZipcodes = await api.zipcodes.getByRegion({ region: 'Europe' });

Select (Optimiert für Dropdown-Menüs)

Diese Endpunkte kosten nur 1 Token unabhängig von der Anzahl der Ergebnisse, perfekt zum Befüllen von Dropdown-Menüs:

// Länder für Dropdown abrufen
const countriesSelect = await api.select.countries({ lang: 'de' });
// Gibt zurück: [{ id: 'DE', name: 'Deutschland', code: 'DE', phone_code: '+49', flag: '🇩🇪' }, ...]

// Bundesländer für Dropdown abrufen
const statesSelect = await api.select.states({ country: 'DE' });
// Gibt zurück: [{ id: 'BE', name: 'Berlin' }, ...]

// Städte für Dropdown abrufen
const citiesSelect = await api.select.cities({ state: 'Berlin', country: 'DE' });
// Gibt zurück: [{ id: '10115', name: 'Berlin' }, ...]

Token-Status prüfen

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

Anfrage-Optionen

Alle Methoden akzeptieren diese gemeinsamen Optionen:

Fehlerbehandlung

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

try {
  const countries = await api.countries.getAll();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Ungültiger API-Schlüssel');
  } else if (error instanceof InsufficientTokensError) {
    console.error('Keine Tokens mehr verfügbar');
  } else {
    console.error('API-Fehler:', error.message);
  }
}

TypeScript-Unterstützung

Vollständige TypeScript-Unterstützung mit allen exportierten Typen:

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

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

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

React-Beispiel

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

const api = new CountryDataApi({ apiKey: 'ihr-api-schluessel' });

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-Beispiel

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

const api = new CountryDataApi({ apiKey: 'ihr-api-schluessel' });
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-Paket
• GitHub-Repository
• API-Schlüssel erhalten