☰

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/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(
         `${BASE_URL}/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/api/v1/provinces?name=istanbul

Response:

 
 {
   "status": "OK",
   "data": [
     {
       "id": 34,
       "name": "İstanbul",
       "area": 5461,
       "population": 15840900,
       "altitude": 25,
       "areaCode": [
         212,
         216
       ],
       "isMetropolitan": true,
       "nuts": {
         "nuts1": {
           "code": "TR1",
           "name": {
             "en": "İstanbul",
             "tr": "İstanbul"
           }
         },
         "nuts2": {
           "code": "TR10",
           "name": "İstanbul"
         },
         "nuts3": "TR100"
       },
       "coordinates": {
         "latitude": 41.01384,
         "longitude": 28.94966
       },
       "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/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(
         `/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/api/v1/districts?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 enters100000 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/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(
         `/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/api/v1/provinces?offset=30&limit=10

In this example, let the offset value be 30 and thelimit 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,
       "altitude": 89,
       "areaCode": [
         326
       ],
       "isMetropolitan": true,
       "nuts": {
         "nuts1": {
           "code": "TR6",
           "name": {
             "en": "Mediterranean",
             "tr": "Akdeniz"
           }
         },
         "nuts2": {
           "code": "TR63",
           "name": "Hatay"
         },
         "nuts3": "TR631"
       },
       "coordinates": {
         "latitude": 36.2,
         "longitude": 36.16667
       },
       "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,
       "altitude": 1058,
       "areaCode": [
         246
       ],
       "isMetropolitan": false,
       "nuts": {
         "nuts1": {
           "code": "TR6",
           "name": {
             "en": "Mediterranean",
             "tr": "Akdeniz"
           }
         },
         "nuts2": {
           "code": "TR61",
           "name": "Antalya"
         },
         "nuts3": "TR612"
       },
       "coordinates": {
         "latitude": 37.76667,
         "longitude": 30.55
       },
       "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/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(
         `/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/api/v1/provinces?fields=id,name,area,population,altitude,areaCode,isMetropolitan,maps,region

In this example we want to get all fields except NUTS and 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,
       "altitude": 25,
       "areaCode": [
         322
       ],
       "isMetropolitan": true,
       "coordinates": {
         "latitude": 37.001667,
         "longitude": 35.328889
       },
       "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,
       "altitude": 701,
       "areaCode": [
         416
       ],
       "isMetropolitan": false,
       "coordinates": {
         "latitude": 37.764722,
         "longitude": 38.278611
       },
       "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/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(
         `/api/v1/districts?sort=${sort}`
       );
       const data = await response.json();
       return data;
     }
   } catch (error) {
     console.error(error);
   }
 }

 let sort = "name";   
       
GET/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/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.

Response:

 
  {
    "status": "OK",
    "data": [
      {
        "id": 2051,
        "name": "Beylikdüzü",
        "area": 39,
        "population": 398122,
        "province": "İstanbul"
      },
      {
        "id": 1195,
        "name": "Bismil",
        "area": 1679,
        "population": 118592,
        "province": "Diyarbakır"
      },
      {
        "id": 1223,
        "name": "Cizre",
        "area": 444,
        "population": 155182,
        "province": "Şırnak"
      },
      {
        "id": 2007,
        "name": "Çiğli",
        "area": 139,
        "population": 209951,
        "province": "İzmir"
      }
      // Other 16 districts
    ]
  }

Good luck!