Turkiye API Documentation

What is the purpose of this API?

This API allows you to get data about provinces in Turkey. 🇹🇷

If you want to see API features as Postman documentation, you can click here.

If you want to see API features as Swagger documentation, you can click here.

For explanation of the API in Turkish language, you can click here.

To see example usages, you can click here.

Provinces

Here are the routes related to provinces.

Get All Provinces

GET/api/v1/provinces

You can use this route to get data for all provinces.

Query Params	Type	Description
name	string	It shows all the provinces containing or matching your search query.
minPopulation	number	It shows all the provinces with a population greater than or equal to the value you entered.
maxPopulation	number	It shows all the provinces with a population less than or equal to the value you entered.
minArea	number	It shows all the provinces with a area greater than or equal to the value you entered.
maxArea	number	It shows all the provinces with a area less than or equal to the value you entered.
minAltitude	number	It shows all the provinces with a altitude greater than or equal to the value you entered.
maxAltitude	number	It shows all the provinces with a altitude less than or equal to the value you entered.
isMetropolitan	boolean	It shows all the provinces that are metropolitan or not.
offset	number	Used for pagination. Use this to set a starting point in search results.
limit	number	Used for pagination. Use this to set the maximum number of results to show you.
fields	string	It shows the fields you want to see in the response.
sort	string	It sorts the results in ascending or descending order (Example: -name).

Get Exact Province

GET/api/v1/provinces/:id

You can use this route to get data for exact province.

Path Variables	Description
id	ID of province

Query Params	Type	Description
fields	string	It shows the fields you want to see in the response.
extend	boolean	It shows the extended data (neighborhoods and villages) of the province. [Default: false] This is an experimental feature. It may not work properly.

Districts

Here are the routes related to districts.

Get All Districts

GET/api/v1/districts

You can use this route to get data for all districts.

Query Params	Type	Description
name	string	It shows all the districts containing or matching your search query.
minPopulation	number	It shows all the districts with a population greater than or equal to the value you entered.
maxPopulation	number	It shows all the districts with a population less than or equal to the value you entered.
minArea	number	It shows all the districts with a area greater than or equal to the value you entered.
maxArea	number	It shows all the districts with a area less than or equal to the value you entered.
provinceId	number	It shows all the districts in the province ID you specified.
province	string	It shows all the districts in the province name you specified.
offset	number	Used for pagination. Use this to set a starting point in search results.
limit	number	Used for pagination. Use this to set the maximum number of results to show you.
fields	string	It shows the fields you want to see in the response.
sort	string	It sorts the results in ascending or descending order (Example: -name).

Get Exact District

You can use this route to get data for exact district.

GET/api/v1/districts/:id

You can use this route to get data for all districts.

Path Variables	Description
id	ID of district

Query Params	Type	Description
fields	string	It shows the fields you want to see in the response.

Neighborhoods

Here are the routes related to neighborhoods.

Get All Neighborhoods

GET/api/v1/neighborhoods

You can use this route to get data for all neighborhoods.

Query Params	Type	Description
name	string	It shows all the neighborhoods containing or matching your search query.
minPopulation	number	It shows all the neighborhoods with a population greater than or equal to the value you entered.
maxPopulation	number	It shows all the neighborhoods with a population less than or equal to the value you entered.
provinceId	number	It shows all the neighborhoods in the province ID you specified.
province	string	It shows all the neighborhoods in the province name you specified.
districtId	number	It shows all the neighborhoods in the district ID you specified.
district	string	It shows all the neighborhoods in the district name you specified.
offset	number	Used for pagination. Use this to set a starting point in search results.
limit	number	Used for pagination. Use this to set the maximum number of results to show you.
fields	string	It shows the fields you want to see in the response.
sort	string	It sorts the results in ascending or descending order (Example: -name).

Get Exact Neighborhood

You can use this route to get data for exact neighborhood.

GET/api/v1/neighborhoods/:id

You can use this route to get data for exact neighborhood.

Path Variables	Description
id	ID of neighborhood

Query Params	Type	Description
fields	string	It shows the fields you want to see in the response.

Villages

Here are the routes related to villages.

Get All Villages

GET/api/v1/villages

You can use this route to get data for all villages.

Query Params	Type	Description
name	string	It shows all the villages containing or matching your search query.
minPopulation	number	It shows all the villages with a population greater than or equal to the value you entered.
maxPopulation	number	It shows all the villages with a population less than or equal to the value you entered.
provinceId	number	It shows all the villages in the province ID you specified.
province	string	It shows all the villages in the province name you specified.
districtId	number	It shows all the villages in the district ID you specified.
district	string	It shows all the villages in the district name you specified.
offset	number	Used for pagination. Use this to set a starting point in search results.
limit	number	Used for pagination. Use this to set the maximum number of results to show you.
fields	string	It shows the fields you want to see in the response.
sort	string	It sorts the results in ascending or descending order (Example: -name).

Get Exact Village

You can use this route to get data for exact village.

GET/api/v1/villages/:id

You can use this route to get data for exact village.

Path Variables	Description
id	ID of village

Query Params	Type	Description
fields	string	It shows the fields you want to see in the response.

Towns

Here are the routes related to towns.

The scope of the v1 version of TurkiyeAPI (without municipal units) is to include provinces, districts, neighborhoods, and villages. However, since towns (a type of municipality) have an important place in the country, two routes have been allocated to them, just like neighborhoods and villages. In short, this is a patch prepared for v1. However, unlike neighborhoods and villages, they are not shown in the "/districts/:id" route, meaning they are isolated within themselves. Nevertheless, in these routes starting with "/towns", the province-district names and IDs to which the towns are connected are specified, meaning you can connect using these if you wish.

Get All Towns

GET/api/v1/towns

You can use this route to get data for all towns.

Query Params	Type	Description
name	string	It shows all the towns containing or matching your search query.
minPopulation	number	It shows all the towns with a population greater than or equal to the value you entered.
maxPopulation	number	It shows all the towns with a population less than or equal to the value you entered.
provinceId	number	It shows all the towns in the province ID you specified.
province	string	It shows all the towns in the province name you specified.
districtId	number	It shows all the towns in the district ID you specified.
district	string	It shows all the towns in the district name you specified.
offset	number	Used for pagination. Use this to set a starting point in search results.
limit	number	Used for pagination. Use this to set the maximum number of results to show you.
fields	string	It shows the fields you want to see in the response.
sort	string	It sorts the results in ascending or descending order (Example: -name).

Get Exact Town

You can use this route to get data for exact town.

GET/api/v1/towns/:id

You can use this route to get data for exact town.

Path Variables	Description
id	ID of town

Query Params	Type	Description
fields	string	It shows the fields you want to see in the response.

Postal Codes (Experimental)

Here are the informations related to postal codes.

The postal codes feature is currently partially missing. Currently, there is only a postal code feature for provinces and districts, and a postal code feature for neighborhoods and villages will come later. However, another important point is that the postal code filtering method can be changed, moved to another location, and postal codes for provinces and districts can be removed after neighborhood & village postal codes are added.

Activate Postal Codes

You can use the following query parameter (you should set it to true) to activate the postal code feature for this routes: Get All Provinces, Get Exact Province, Get All Districts, Get Exact District.

Query Params	Type	Description
activatePostalCodes	boolean	It activates the postal code feature. [Default: false]

Provinces & Districts Postal Codes

You can use the following query parameter to filter the provinces and districts.

Firstly you should activate the postal code feature by setting the "activatePostalCodes" query parameter to true.

Although postal codes consist only of digits, they are still a string type. This is because postal codes can start with zero.

Query Params	Type	Description
postalCode	string	It shows all the provinces/districts containing or matching your postal code.

Turkiye API is an open-source project. Click here for GitHub link! 😻