API Usage | Examples
If you are confused or want an explanation with examples, you can review this page.
This API highlights query params more than path variables.
In this section, we will use queries that are more likely to be used in real life. For real life API usage, we will exemplify via JavaScript.
Example 1: Search provinces
GET
https://turkiyeapi.dev/api/v1/provinces?name={user input}
The end user's connection to your site, app, etc. One of the first things he/she/they will do when he enters is probably to search for any province (or district). In this case, it would be most logical to use this query.
NOTE: Note that this method only deals with the names of provinces (or
districts). For this, use .../api/v1/provinces/34 instead
of .../api/v1/provinces?name=34.
Example usage:
async function getProvinces(input) {
try {
if (input.length > 0) {
const response = await fetch(
`https://turkiyeapi.dev/api/v1/provinces?name=${input}`
);
const data = await response.json();
return data;
}
} catch (error) {
console.error(error);
}
}
// NOTE: This is just an example. You can use this function in your own way.
// You can use the search by name feature not only for provinces but also for districts. Just replace "provinces" with "districts".
After that, let's consider that the user makes the query
"istanbul".
GET
https://turkiyeapi.dev/api/v1/provinces?name=istanbul
Response:
{
"status": "OK",
"data": [
{
"id": 34,
"name": "İstanbul",
"area": 5461,
"population": 15840900,
"areaCode": [
212,
216
],
"isMetropolitan": true,
"maps": {
"googleMaps": "https://goo.gl/maps/wKdwRFM4NW8Wm6ZZ8",
"openStreetMaps": "https://www.openstreetmap.org/relation/223474"
},
"region": {
"en": "Marmara",
"tr": "Marmara"
},
"districts": [
// Districts of İstanbul
]
}
]
}
// "data" returns an array, regardless of whether a single province or multiple provinces are returned when searched.
Example 2: List districts in a specific population range
GET
https://turkiyeapi.dev/api/v1/districts?minPopulation={user input}&maxPopulation={user input}
Example usage:
async function getDistricts(min, max) {
try {
if (min > 0 && max > 0) {
const response = await fetch(
`https://turkiyeapi.dev/api/v1/districts?minPopulation=${min}&maxPopulation=${max}`
);
const data = await response.json();
return data;
}
} catch (error) {
console.error(error);
}
}
// NOTE: This is just an example. You can use this function in your own way.
// NOTE: You can use the search by population feature not only for districts but also for provinces. Just replace "districts" with "provinces".
GET
https://turkiyeapi.dev/api/v1/provinces?minPopulation=100000&maxPopulation=300000
Good, now let's assume that the user wants to list the districts within
a certain population range. In this example, let's assume that the end
user enters
100000 as the minimum population and 300000 as
the maximum population.
Response:
{
"status": "OK",
"data": [
{
"id": 1219,
"name": "Ceyhan",
"area": 1426,
"population": 159955,
"province": "Adana"
},
{
"id": 1486,
"name": "Kozan",
"area": 1903,
"population": 132320,
"province": "Adana"
},
{
"id": 2032,
"name": "Sarıçam",
"area": 770,
"population": 208227,
"province": "Adana"
},
// Other 150 districts
]
}
Example 3: Pagination
GET
https://turkiyeapi.dev/api/v1/provinces?offset={user input}&limit={user input}
Viewing 81 cities (including their districts) or 972 districts at the same time can be annoying for end users with slow connections, as well as your site, app, etc. it can be filled with too much content at once. You can use the pagination method to avoid this.
Example usage:
async function getProvinces(offset, limit) {
try {
if (offset > 0 && limit > 0) {
const response = await fetch(
`https://turkiyeapi.dev/api/v1/provinces?offset=${offset}&limit=${limit}`
);
const data = await response.json();
return data;
}
} catch (error) {
console.error(error);
}
}
let maxProvincePerPage = 10;
let currentPage = 1;
let offset = (currentPage - 1) * maxProvincePerPage;
let limit = maxProvincePerPage;
getProvinces(offset, limit).then((data) => {
console.log(data);
});
GET
https://turkiyeapi.dev/api/v1/provinces?offset=30&limit=10
In this example, let the offset value be
30 and the limit value 10. In
this case, if we decide that there will be 10 provinces on each page,
the provinces 31 to 40 will be listed on page 4 (out of 9).
Response:
{
"status": "OK",
"data": [
{
"id": 31,
"name": "Hatay",
"area": 5524,
"population": 1670712,
"areaCode": [
326
],
"isMetropolitan": true,
"maps": {
"googleMaps": "https://goo.gl/maps/2VkFg1AM9B4Xv9W89",
"openStreetMaps": "https://www.openstreetmap.org/relation/223122"
},
"region": {
"en": "Mediterranean",
"tr": "Akdeniz"
},
"districts": [
// Districts of Hatay
]
},
{
"id": 32,
"name": "Isparta",
"area": 8946,
"population": 445678,
"areaCode": [
246
],
"isMetropolitan": false,
"maps": {
"googleMaps": "https://goo.gl/maps/v8tcHjuuCKyNMn687",
"openStreetMaps": "https://www.openstreetmap.org/relation/223134"
},
"region": {
"en": "Mediterranean",
"tr": "Akdeniz"
},
"districts": [
// Districts of Isparta
]
},
// Other 8 provinces
]
}
Example 4: Fields
GET
https://turkiyeapi.dev/api/v1/provinces?fields={user input}
When you want to obtain only one or more provinces / districts, you can use ID, province / district name, area, population, etc. you get all the data. But do you really need all this data?
Imagine you want to list all provinces. In this case, you need to get the data of these provinces, but on the other hand, each province has its own districts. But you do not need the knowledge of these districts, you only need the knowledge of the cities. In this case you will need to use fields query.
Example usage:
async function getProvinces(fields) {
try {
if (fields) {
const response = await fetch(
`https://turkiyeapi.dev/api/v1/provinces?fields=${fields}`
);
const data = await response.json();
return data;
}
} catch (error) {
console.error(error);
}
}
let fields = "id,name,area,population,areaCode,isMetropolitan,maps,region";
GET
https://turkiyeapi.dev/api/v1/provinces?fields=id,name,area,population,areaCode,isMetropolitan,maps,region
In this example we want to get all fields except districts. In this case, we must write all fields except districts. Notice that there is a comma between each field.
Response:
{
"status": "OK",
"data": [
{
"id": 1,
"name": "Adana",
"area": 13844,
"population": 2263373,
"areaCode": [
322
],
"isMetropolitan": true,
"maps": {
"googleMaps": "https://goo.gl/maps/4yHUNdZuhcBn7rqX8",
"openStreetMaps": "https://www.openstreetmap.org/relation/167216"
},
"region": {
"en": "Mediterranean",
"tr": "Akdeniz"
}
},
{
"id": 2,
"name": "Adıyaman",
"area": 7337,
"population": 632148,
"areaCode": [
416
],
"isMetropolitan": false,
"maps": {
"googleMaps": "https://goo.gl/maps/UqRzeK1ApyPjbhpp6",
"openStreetMaps": "https://www.openstreetmap.org/relation/223141"
},
"region": {
"en": "Southeastern Anatolia",
"tr": "Güneydoğu Anadolu"
}
},
// Other 79 provinces
]
}
Example 5: Sorting
GET
https://turkiyeapi.dev/api/v1/districts?sort={user input}
By default, districts are classified according to the provinces they are affiliated with first, and if the districts are affiliated with the same provinces, they are classified according to their names. We should use sort query to change this order.
Example usage:
async function getDistricts(sort) {
try {
if (sort) {
const response = await fetch(
`https://turkiyeapi.dev/api/v1/districts?sort=${sort}`
);
const data = await response.json();
return data;
}
} catch (error) {
console.error(error);
}
}
let sort = "name";
GET
https://turkiyeapi.dev/api/v1/districts?sort=-population
In this example, let's rank all the districts from the most populated to the least populated.
NOTE: If you've noticed, the ?sort=-population query has a
minus (-) sign before population. This symbol is used to
descend the ascending order. In this example, we will use this sign to
rank from the most populated district to the least populated district.
Response:
{
"status": "OK",
"data": [
// First two districts
{
"id": 2053,
"name": "Esenyurt",
"area": 43,
"population": 977489,
"province": "İstanbul"
},
{
"id": 1231,
"name": "Çankaya",
"area": 483,
"population": 949265,
"province": "Ankara"
},
// Other 968 districts
{
"id": 1379,
"name": "Hamur",
"area": 873,
"population": 1710,
"province": "Ağrı"
},
{
"id": 1994,
"name": "Yalıhüyük",
"area": 94,
"population": 1532,
"province": "Konya"
}
// Last two districts
]
}
Example 6: Complex Queries
GET
https://turkiyeapi.dev/api/v1/districts?name=i&minPopulation=100000&sort=name&offset=10&limit=20
Of course, you can use multiple queries for a single URL. When you send a request, it sorts the cities with a population of at least 100000 with an "i" in their name as an ascending order, and gives you the districts from the 11th to the 30th.
Good luck!