# Akaryakıt Fiyatları (SBX-AKY)

81 ilde EPDK akaryakıt fiyatları: bayi ve dağıtıcı bazında benzin ve motorin fiyatları, EPDK lisans bilgileri ve eşleşebilen istasyonlar için doğrulanmış Google Haritalar bilgisi.

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

**List cities**

All EPDK cities (provinces) with their EPDK ids. Not paginated: the whole list in one answer.

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

Parametre yok.

**Örnek**

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

### GET /v1/fuel/districts

**List the districts of a city**

The districts of one city, with the city in `meta.city`. Their ids or names are what `district` on the station price list accepts. Not paginated.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `city` | query | string | evet | EPDK numeric id or name, case- and Turkish-character-insensitive (`34` and `istanbul` name the same city). |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/fuel/districts?city=<city>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/fuel/stations

**List stations with fuel prices**

The dealer stations of one to five districts of a city, each with its fuel prices per litre and its station details. `meta` says what was asked: `mode` (`single` for one district, `selected` for several), the city, the districts, the currency and whether every source page was read (`complete`). A price of `null` means the station does not sell that product. Not paginated: the whole result in one answer.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `city` | query | string | evet | EPDK numeric id or name, case- and Turkish-character-insensitive (`34` and `istanbul` name the same city). |
| `district` | query | string | evet | One to five districts of `city`, comma-separated: EPDK ids (specific to their city) or names, case- and Turkish-character-insensitive. One district gives `meta.mode` `single`, several give `selected`. Missing, or more than five, is a 400: a whole city at once is too slow for the source. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/fuel/stations?city=<city>&district=<district>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/fuel/stations/lookup

**Look up a station by licence**

One exact EPDK dealer licence, enriched with a verified Google Maps place when one can be matched. A licence with no exact EPDK record is a `404 not_found`.

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `license` | query | string | evet | An exact EPDK dealer licence number, e.g. `BAY/000-00/00001`. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/fuel/stations/lookup?license=<license>" \
  -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/fuel/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-AKY
- API sayfası: https://servicebox.io/apis/fuel