Villages

Villages are the administrative units that come after districts among Turkey's administrative divisions. Each district is divided into one or more villages. There are more than 18,000 villages in Turkey. By default, the API lists all villages first by the provinces they belong to, then by the districts they belong to, and then by their names.

INFO

The provinces that villages belong to are not metropolitan municipalities. (isMetropolitan: false)

The entry URL for villages is: /api/v1/villages.

Village Properties

Village resources have the following properties:

• provinceId: Province ID that the village belongs to
• districtId: District ID that the village belongs to
• id: Village ID
• province: Name of the province that the village belongs to
• district: Name of the district that the village belongs to
• name: Village name
• population: Village population

Getting Multiple Village Data

To get all villages, you only need to use the village URL. For example, you can use a URL like /api/v1/villages to get all villages.

https://turkiyeapi.dev/api/v1/villages

curl

curl https://turkiyeapi.dev/api/v1/villages

fetch

fetch('https://turkiyeapi.dev/api/v1/villages')
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error('Error fetching data:', error));

If your request is successful, the API will return a response like this:

Sample Response

{
  "status": "OK",
  "data": [
    {
      "provinceId": 2,
      "districtId": 1105,
      "id": 37777,
      "province": "Adıyaman",
      "district": "Merkez",
      "name": "100.yıl",
      "population": 60
    },
    {
      "provinceId": 2,
      "districtId": 1105,
      "id": 631,
      "province": "Adıyaman",
      "district": "Merkez",
      "name": "Ağaçkonak",
      "population": 170
    }
    // Other villages...
  ]
}

Getting Single Village Data

To get data for a single village, you can create a URL like /api/v1/villages/{id} using the village ID. For example, you can use the URL /api/v1/villages/37777 to get the village with ID 37777.

https://turkiyeapi.dev/api/v1/villages/37777

curl

curl https://turkiyeapi.dev/api/v1/villages/37777

fetch

fetch('https://turkiyeapi.dev/api/v1/villages/37777')
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error('Error fetching data:', error));

If your request is successful, the API will return a response like this:

Sample Response

{
  "status": "OK",
  "data": {
    "provinceId": 2,
    "districtId": 1105,
    "id": 37777,
    "province": "Adıyaman",
    "district": "Merkez",
    "name": "100.yıl",
    "population": 60
  }
}

Querying

To query the API, you can add query parameters to the URL. For example, you can use the provinceId parameter to get villages in a specific province.

INFO

For examples of this, you can visit the Sample API Calls page.

For /villages:

Query Parameters	Type	Description
name	string	Shows all villages containing or matching your search query.
minPopulation	number	Shows all villages with population greater than or equal to your value.
maxPopulation	number	Shows all villages with population less than or equal to your value.
provinceId	number	Shows villages belonging to a specific province. This parameter filters by province ID.
province	string	Shows villages belonging to a specific province. This parameter uses the province name.
districtId	number	Shows villages belonging to a specific district. This parameter filters by district ID.
district	string	Shows villages belonging to a specific district. This parameter uses the district name.
offset	number	Determines which record to start from. Default value is 0.
limit	number	Determines how many records to retrieve. Default value is 10.
fields	string	Determines which fields to retrieve. For example, fields=id,name,population retrieves ID, name and population fields.
sort	string	Determines which field to sort by. For example, sort=name sorts by the name field.

For /villages/{id}:

Path Variable	Description
id	ID of the village to retrieve.

Query Parameters	Type	Description
fields	string	Determines which fields to retrieve. For example, fields=id,name,population retrieves ID, name and population fields.