Guide

TurkiyeAPI v2 is a read-only REST API for Türkiye's administrative data. The guide explains how to think about the data model, how the main resources relate to each other, and how to combine endpoints into practical workflows.

Use the guide when you are learning the API or designing an integration. Use the API Reference when you need exact endpoint contracts, field lists, allowed query values, and error codes.

What You Can Build

The API is useful for address forms, location pickers, reporting tools, dashboards, public datasets, and validation workflows that need Turkish administrative units.

Common workflows include:

• Building province -> district -> neighborhood address forms.
• Listing the districts of a selected province.
• Finding municipalities inside a district.
• Loading neighborhoods for a municipality.
• Searching neighborhoods across a broader scope.
• Filtering settlements by population.
• Downloading the full dataset for offline processing.

Guide Sections

Section	What it explains
Getting Started	Base URL, v2 prefix, no-auth access, first request, and response shape
Concepts	Province, district, municipality, neighborhood, village, IDs, slugs, and parent IDs
Administrative Structure	How Türkiye's administrative hierarchy is represented in the API
Common Use Cases	Which endpoint pattern to use for selectors, search screens, detail pages, and bulk data
Filtering, Sorting and Pagination	Shared query parameters and examples for list endpoints
Datasets	When to use live API endpoints and when to download static dataset files
Examples	Real workflows such as districts of İstanbul and neighborhoods by municipality
Migration from v1	v1 to v2 differences for existing integrations
FAQ	Non-reference answers about access, metadata, datasets, and support
Support	Optional donations and sponsorship notes for project sustainability
Privacy Policy	What the public API logs, why logs are used, and how long they are retained
Terms of Use	Acceptable use, rate limits, no-warranty terms, and unofficial project status

API Shape

All v2 settlement resources are available under the same base URL:

https://api.turkiyeapi.dev/v2

The API uses JSON response envelopes:

• List endpoints return a data array and pagination metadata.
• Single-resource endpoints return a data object and dataset metadata.
• Errors return an error object with a stable code, message, and HTTP status.

Official TypeScript Client

@turkiyeapi/client is the official lightweight TypeScript client for TurkiyeAPI v2. It works in modern browsers and Node.js 18+ because it uses fetch.

PREVIEW

This package is currently in pre-1.0.0 development. The public API may change before v1.0.0.

Install it from npm:

npm install @turkiyeapi/client

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

Resource Map

The core resources are:

• provinces: Türkiye's 81 provinces.
• districts: Districts that belong to provinces.
• municipalities: Local governments attached to provinces and districts.
• neighborhoods: Neighborhood records attached to a province, district, and municipality.
• villages: Village records attached to a province and district.

For exact fields and endpoint lists, see the API Reference.