# Ülkeler ve eyaletler (SBX-GEO)

250 ülke ve bölge, 3.865 eyalet ve il; ISO kodları, Türkçe adlar, başkentler, telefon kodları, para birimleri ve komşu ülkeler.

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/countries/...?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": ["countries"]}` 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/countries/continents

**List continents**

The seven continents with their country counts, for the `continent` filter. 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/countries/continents" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/countries/countries

**List countries**

Every country and territory in ISO 3166-1, sorted by English name. `q` matches the start of a word of the English or Turkish name, or the ISO code, case- and accent-insensitive (`turk`, `türk`, `TR`).

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `q` | query | string | hayır | Name or code search. |
| `continent` | query | string | hayır | AF, AN, AS, EU, NA, OC or SA. |
| `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/countries/countries" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/countries/countries/{code}

**Get a country**

One country by ISO 3166-1 alpha-2 (`TR`) or alpha-3 (`TUR`) code, case-insensitive.

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

**Parametreler**

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

**Örnek**

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

### GET /v1/countries/subdivisions

**List a country's subdivisions**

First-level administrative divisions (states, provinces, regions) of one country, sorted by name. For Turkey these are the 81 provinces, with their Turkish names.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `country` | query | string | evet | 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/countries/subdivisions?country=<country>" \
  -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/countries/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-GEO
- API sayfası: https://servicebox.io/apis/countries