FAQ

Do I Need an API Key?

No. TurkiyeAPI v2 is public and does not require authentication.

What Is the Base URL?

Use:

https://api.turkiyeapi.dev

v2 endpoints are under:

/v2

For example:

https://api.turkiyeapi.dev/v2/provinces

Is the API Read-Only?

Yes. v2 exposes read-only endpoints for administrative data. It does not provide create, update, or delete endpoints.

Where Can I See the Current Dataset Version?

Call:

curl "https://api.turkiyeapi.dev/v2/meta"

The response includes apiVersion, datasetVersion, lastUpdated, sources, and record counts.

Should I Use API Endpoints or Dataset Files?

Use API endpoints for interactive screens, filtering, sorting, pagination, and single-resource lookups.

Use dataset files when you need the entire dataset locally, such as for analytics, search indexing, offline processing, or scheduled imports.

Why Is postalCode a String?

Postal codes can start with 0. If postal codes were returned as numbers, leading zeros would be lost. Some records can also have null postal codes.

Why Does İstanbul Have Two Phone Area Codes?

İstanbul spans both sides of the Bosphorus. The European side uses 212, and the Asian side uses 216. For consistency, phoneAreaCodes is always an array.

How Do I Report an Issue?

Open an issue in the project repository:

github.com/ubeydeozdmr/turkiye-api

Include the endpoint, query parameters, expected result, actual result, and any relevant response body.

Where Is the Exact Endpoint Documentation?

Use the API Reference for endpoint contracts, query parameters, field lists, includes, response schemas, and error codes.