Turkiye API Documentation
What is the purpose of this API?
This API allows you to get data about provinces, districts, neighborhoods, villages (and more) 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/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. |
| isCoastal | boolean | It shows all the provinces that are coastal or not. |
| 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/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/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/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/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/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/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/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/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/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! 😻