@turkiyeapi/client

Lightweight TypeScript client for TurkiyeAPI v2.

npm install @turkiyeapi/client

Usage

import { TurkiyeAPI } from '@turkiyeapi/client';

const api = new TurkiyeAPI();

const provinces = await api.provinces.list({
  search: 'istanbul',
  fields: ['id', 'name', 'population'],
});

const istanbul = await api.provinces.get(34);
const districts = await api.provinces.districts(34, { limit: 50 });

Factory style is also available:

import { createTurkiyeAPIClient } from '@turkiyeapi/client';

const api = createTurkiyeAPIClient({
  timeout: 5000,
  baseUrl: 'https://api.turkiyeapi.dev',
});

Resources

await api.health();
await api.meta();
await api.openapi();

await api.provinces.list();
await api.provinces.get(34);
await api.provinces.districts(34);
await api.provinces.municipalities(34);
await api.provinces.neighborhoods(34);
await api.provinces.villages(34);

await api.districts.list({ provinceId: 34 });
await api.districts.get(1103);
await api.districts.municipalities(1103);
await api.districts.neighborhoods(1103);
await api.districts.villages(1103);

await api.municipalities.list({ type: 'district_center' });
await api.municipalities.get(1);
await api.municipalities.neighborhoods(1);

await api.neighborhoods.list({ postalCodePrefix: '34' });
await api.neighborhoods.get(1);

await api.villages.list({ provinceId: 34 });
await api.villages.get(1);

await api.datasets.latest('provinces.json');
await api.datasets.version('2025', 'districts.json');

Error Handling

Non-2xx responses throw TurkiyeAPIError.

import { TurkiyeAPI, TurkiyeAPIError } from '@turkiyeapi/client';

const api = new TurkiyeAPI();

try {
  await api.provinces.get(9999);
} catch (error) {
  if (error instanceof TurkiyeAPIError) {
    console.error(error.status, error.code, error.message);
  }
}

TypeScript

The package is written in TypeScript and ships declaration files. Common response and entity types are exported:

import type { ListResponse, Province, District } from '@turkiyeapi/client';

Runtime

The client uses fetch, so it works in modern browsers and Node.js 18+. For older runtimes, pass a custom fetch implementation:

const api = new TurkiyeAPI({ fetch: customFetch });