Skip to content

Commit

Permalink
Update README.md for recent updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@ubeydeozdmr
ubeydeozdmr committed Feb 29, 2024
1 parent 84e83ba commit 3f41610
Showing 1 changed file with 71 additions and 211 deletions.
282 changes: 71 additions & 211 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# Turkiye API

API containing information about Turkey's provinces. It is still under development.
API containing information about Turkey's provinces, districts, neighborhoods and villages.

## Announcement
## Hostnames

After a 1-month outage, deployment based on [cyclic.sh](https://cyclic.sh) was activated again. We will use [turkiyeapi.dev](https://turkiyeapi.dev) as the main domain. But you can still use the following domains:
The API uses [turkiyeapi.dev](https://turkiyeapi.dev) as the main domain. But you can still use the following domains:

- [turkiyeapi.cyclic.app](https://turkiyeapi.cyclic.app)
- [turkiyeapi.herokuapp.com](https://turkiyeapi.herokuapp.com)

## What's new?

- NUTS (_Turkish:_ [İBBS](https://tr.wikipedia.org/wiki/T%C3%BCrkiye%27nin_%C4%B0BBS%27si)) codes added for provinces. (October 11, 2023)
- I'll start working on the [**neighborhoods and towns**](https://github.com/ubeydeozdmr/turkiye-api/issues/13) soon (it won't be easy). I can make this feature available optionally during the development process.
- Neighborhoods and villages have been added to the API. (Experimental)
- Population data has been updated from 2021 to 2023. (2023 data has been released by TUIK, early 2024)

## Sources

Expand All @@ -21,247 +21,107 @@ After a 1-month outage, deployment based on [cyclic.sh](https://cyclic.sh) was a

## Usage of API

### Get all provinces
## Provinces

```bash
https://turkiyeapi.dev/api/v1/provinces
```
### Get All Provinces

You can use this route to get data for all countries.
**Endpoint:** `GET /api/v1/provinces`

[Click here to take a quick look](https://turkiyeapi.dev/api/v1/provinces)
You can use this route to get data for all provinces. The available query parameters are:

| Query | Type | Description |
| -------------- | :-----: | :------------------------------------------------------------------------------------- |
| name | string | It shows all the provinces containing or matching your search query. |
| minPopulation | number | It shows all the provinces with population greater than or equal to your search query. |
| maxPopulation | number | It shows all the provinces with population less than or equal to your search query. |
| isMetropolitan | boolean | It shows all the provinces with metropolitan status equal to your search query. |
| 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 only the fields you want to see. |
| sort | string | It sorts the results by the field you want. |
- `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.
- `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 usage 1:
### Get Exact Province

```bash
https://turkiyeapi.dev/api/v1/provinces?name=ankara
```
**Endpoint:** `GET /api/v1/provinces/:id`

[Click here to try it](https://turkiyeapi.dev/api/v1/provinces?name=ankara)
You can use this route to get data for exact province. The available path variables and query parameters are:

- Example usage 2:
- `id` (Path Variable): ID of province
- `fields` (Query Parameter, string): It shows the fields you want to see in the response.
- `extend` (Query Parameter, boolean): It shows the extended data (neighborhoods and villages) of the province. [Default: false] (This is an experimental feature. It may not work properly.)

```bash
https://turkiyeapi.dev/api/v1/provinces?offset=10&limit=10
```
## Districts

[Click here to try it](https://turkiyeapi.dev/api/v1/provinces?offset=10&limit=10)
### Get All Districts

- Example usage 3:
**Endpoint:** `GET /api/v1/districts`

```bash
https://turkiyeapi.dev/api/v1/provinces?fields=name,areaCode
```
You can use this route to get data for all districts. The available query parameters are:

It will show you only the name and area code of the provinces.
- `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.
- `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.

[Click here to try it](https://turkiyeapi.dev/api/v1/provinces?fields=name,areaCode)
### Get Exact District

### Get exact province
**Endpoint:** `GET /api/v1/districts/:id`

```bash
https://turkiyeapi.dev/api/v1/provinces/:id
```
You can use this route to get data for exact district. The available path variables and query parameters are:

You can use this route to obtain the data of the province whose ID you entered.
- `id` (Path Variable): ID of district
- `fields` (Query Parameter, string): It shows the fields you want to see in the response.

City IDs were created based on license plate numbers. Each license plate number is unique so I thought it appropriate to set this route as a parameter instead of a query.
## Neighborhoods

NOTE: The ability to search by province name has been removed for this route. Try using `/api/v1/provinces?name={your search query}` instead.
### Get All Neighborhoods

| Query | Type | Description |
| ------ | :----: | :---------------------------------------- |
| fields | string | It shows only the fields you want to see. |
**Endpoint:** `GET /api/v1/neighborhoods`

- Example usage 1:
You can use this route to get data for all neighborhoods. This is a recently added endpoint and is experimental. It may not work properly. The available query parameters are:

```bash
https://turkiyeapi.dev/api/v1/provinces/6
```
- `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.
- `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.

It will show you the data of the province whose ID is 6.
### Get Exact Neighborhood

[Click here to try it](https://turkiyeapi.dev/api/v1/provinces/6)
**Endpoint:** `GET /api/v1/neighborhoods/:id`

- Example usage 2:
You can use this route to get data for exact neighborhood. This is a recently added endpoint and is experimental. It may not work properly. The available path variables and query parameters are:

```bash
https://turkiyeapi.dev/api/v1/provinces/6?fields=name,areaCode
```
- `id` (Path Variable): ID of neighborhood
- `fields` (Query Parameter, string): It shows the fields you want to see in the response.

It will show you only the name and area code of the province.
## Villages

[Click here to try it](https://turkiyeapi.dev/api/v1/provinces/6?fields=name,areaCode)
### Get All Villages

- Example response:
**Endpoint:** `GET /api/v1/villages`

```json
{
"status": "OK",
"data": [
{
"id": 6,
"name": "Ankara",
"area": 25632,
"population": 5747325,
"altitude": 905,
"areaCode": [312],
"isMetropolitan": true,
"nuts": {
"nuts1": {
"code": "TR5",
"name": {
"en": "West Anatolia",
"tr": "Batı Anadolu"
}
},
"nuts2": {
"code": "TR51",
"name": "Ankara"
},
"nuts3": "TR511"
},
"maps": {
"googleMaps": "https://goo.gl/maps/Ri3Zh3yBka5RhXdG8",
"openStreetMaps": "https://www.openstreetmap.org/relation/223422"
},
"region": {
"en": "Central Anatolia",
"tr": "Orta Anadolu"
},
"districts": [
// Districts of Ankara
]
}
]
}
```
You can use this route to get data for all villages. This is a recently added endpoint and is experimental. It may not work properly. The available query parameters are:

### Get all districts
- `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.
- `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.

```bash
https://turkiyeapi.dev/api/v1/districts
```
### Get Exact Village

You can use this route to get data for all districts.
**Endpoint:** `GET /api/v1/villages/:id`

[Click here to take a quick look](https://turkiyeapi.dev/api/v1/districts)
You can use this route to get data for exact village. This is a recently added endpoint and is experimental. It may not work properly. The available path variables and query parameters are:

| Query | Type | Description |
| ------------- | :----: | :------------------------------------------------------------------------------------- |
| name | string | It shows all the districts containing or matching your search query. |
| minPopulation | number | It shows all the districts with population greater than or equal to your search query. |
| maxPopulation | number | It shows all the districts with population less than or equal to your search query. |
| 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 only the fields you want to see. |
| sort | string | It sorts the results by the field you want. |

- Example usage 1:

```bash
https://turkiyeapi.dev/api/v1/districts?name=dağ
```

It will show all the districts containing or matching "dağ" in their name.

[Click here to try it](https://turkiyeapi.dev/api/v1/districts?name=dağ)

- Example usage 2:

```bash
https://turkiyeapi.dev/api/v1/districts?minPopulation=100000&maxPopulation=300000
```

It will show all the districts with a population between 100,000 and 300,000.

[Click here to try it](https://turkiyeapi.dev/api/v1/districts?minPopulation=100000&maxPopulation=300000)

- Example usage 3:

```bash
https://turkiyeapi.dev/api/v1/districts?offset=10&limit=10
```

It will show 10 districts starting from the 10th district.

[Click here to try it](https://turkiyeapi.dev/api/v1/districts?offset=10&limit=10)

- Example usage 4:

```bash
https://turkiyeapi.dev/api/v1/districts?fields=name,population
```

It will show only the name and population of the districts.

[Click here to try it](https://turkiyeapi.dev/api/v1/districts?fields=name,population)

- Example response:

```json
{
"status": "OK",
"data": [
{
"name": "Aladağ",
"area": 1340,
"population": 15855,
"province": "Adana"
},
{
"name": "Ceyhan",
"area": 1426,
"population": 159955,
"province": "Adana"
}
// ... and so on
]
}
```

### Get exact district

```bash
https://turkiyeapi.dev/api/v1/districts/:id
```

You can use this route to obtain the data of the province whose ID you entered.

| Query | Type | Description |
| ------ | :----: | :---------------------------------------- |
| fields | string | It shows only the fields you want to see. |

- Example usage 1:

```bash
https://turkiyeapi.dev/api/v1/districts/1832
```

It will show you the data of the district whose ID is 1832.

[Click here to try it](https://turkiyeapi.dev/api/v1/districts/1832)

- Example usage 2:

```bash
https://turkiyeapi.dev/api/v1/districts/1832?fields=id,name
```

It will show you only the id and name of the district.

[Click here to try it](https://turkiyeapi.dev/api/v1/districts/1832?fields=id,name)
- `id` (Path Variable): ID of village
- `fields` (Query Parameter, string): It shows the fields you want to see in the response.

## License

Expand Down

0 comments on commit 3f41610

Please sign in to comment.