# Şehirler ve kasabalar (SBX-CITY)

171 bin şehir ve kasaba; nüfus, saat dilimi, koordinat ve en yakın şehir araması. Türkiye'nin 974 ilçesi ve 36 bin mahalle/köy posta kodu.

Sürüm: v1.0

## Kimlik doğrulama

API anahtarınızı her istekte Bearer token olarak ya da `apikey` sorgu parametresiyle gönderin:

```
Authorization: Bearer <API_ANAHTARINIZ>
https://api.servicebox.io/v1/cities/...?apikey=<API_ANAHTARINIZ>
```

Anahtar almak için https://servicebox.io/signup adresinden kaydolun ve panelden bir anahtar oluşturun. Bir ajan `POST https://api.servicebox.io/v1/accounts` ve `{"email": "...", "apis": ["cities"]}` ile kendisi kaydolabilir: e-posta sahibi e-postadaki bağlantıyla onaylar, ajan dönen `poll_url` adresini yoklayarak kısa ömürlü bir anahtar alır.

## Temel URL

`https://api.servicebox.io`

## Uç noktalar

### GET /v1/cities/cities

**List cities**

Cities and towns with at least 1,000 inhabitants (about 171,000 worldwide), largest first unless `sort=name`. Filter by country, subdivision, a name search (start of a word, case- and accent-insensitive: `kadikoy` finds Kadıköy) and a minimum population. Turkish places carry their Turkish names.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `country` | query | string | hayır | ISO 3166-1 alpha-2 code. |
| `subdivision` | query | string | hayır | Subdivision id, e.g. TR.34. |
| `q` | query | string | hayır | Name search. |
| `minPopulation` | query | integer | hayır | Minimum population. |
| `sort` | query | string (`population`, `name`) | hayır | `population` (default, largest first) or `name`. |
| `limit` | query | integer | hayır | Items per page, 1–200. |
| `cursor` | query | string | hayır | The `next_cursor` of the previous page, with the same filters. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/cities/cities" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/cities/cities/nearby

**List cities near a point**

Cities within `radiusKm` of a point, nearest first, each with `distanceKm`. Pages through at most the 500 nearest.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `lat` | query | number | evet | Latitude (WGS84). |
| `lon` | query | number | evet | Longitude (WGS84). |
| `radiusKm` | query | number | hayır | Search radius, 0.1–200 km. |
| `minPopulation` | query | integer | hayır | Minimum population. |
| `limit` | query | integer | hayır | Items per page, 1–200. |
| `cursor` | query | string | hayır | The `next_cursor` of the previous page, with the same filters. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/cities/cities/nearby?lat=0&lon=0" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/cities/cities/{id}

**Get a city**

One city by its id.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `id` | path | string | evet |  |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/cities/cities/<id>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/cities/districts

**List districts**

Second-level administrative divisions: Turkey's 974 districts (ilçe) with their Turkish names, counties and similar elsewhere. Give `subdivision` (the districts of one province) or `country`. Sorted by name.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `subdivision` | query | string | hayır | Subdivision id, e.g. TR.34. |
| `country` | query | string | hayır | ISO 3166-1 alpha-2 code. |
| `q` | query | string | hayır | Name search. |
| `limit` | query | integer | hayır | Items per page, 1–200. |
| `cursor` | query | string | hayır | The `next_cursor` of the previous page, with the same filters. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/cities/districts" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/cities/postal-codes

**List postal codes**

Postal codes with the places they serve: for Turkey, about 36,000 neighbourhoods (mahalle) and villages, each with its district and province. Filter by `code`, `district`, `subdivision` or a name search. `country` is required; available for TR.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `country` | query | string | evet | ISO 3166-1 alpha-2 code; TR. |
| `code` | query | string | hayır | A postal code, e.g. 34710. |
| `district` | query | string | hayır | District id, e.g. TR.34.7732454. |
| `subdivision` | query | string | hayır | Subdivision id, e.g. TR.34. |
| `q` | query | string | hayır | Place name search. |
| `limit` | query | integer | hayır | Items per page, 1–200. |
| `cursor` | query | string | hayır | The `next_cursor` of the previous page, with the same filters. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/cities/postal-codes?country=<country>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/cities/timezones

**List timezones**

Every IANA timezone the cities use, with its city count, sorted by name. Free. Not paged: the whole list in one answer.

**Kredi:** ücretsiz (çağrı başına 0 kredi)

Parametre yok.

**Örnek**

```bash
curl "https://api.servicebox.io/v1/cities/timezones" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Hatalar

Hatalar, makinece okunabilir bir `type` taşıyan RFC 9457 `application/problem+json` gövdeleridir.

- `401` — anahtar eksik, bilinmiyor, süresi dolmuş ya da iptal edilmiş.
- `402` — kredi yetersiz: gövde `credits_required` ve `upgrade_url` (https://servicebox.io/pricing) taşır.
- `403` — anahtarın bu API'yi çağırma izni yok.
- `429` — hız sınırı: `retry_after` saniye bekleyin (`Retry-After` başlığıyla da gönderilir); `upgrade_url` daha büyük bir plana yönlendirir.

## Bağlantılar

- OpenAPI belgesi: https://api.servicebox.io/v1/cities/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-CITY
- API sayfası: https://servicebox.io/apis/cities