# Elektrikli Araç Şarj (SBX-SARJ)

Türkiye genelinde elektrikli araç şarj istasyonları: soket tipleri, güç, fiyat ve müsaitlik; il, ilçe, marka, soket tipi, fiyat aralığı ya da konuma göre arama ve mobil şarj üniteleri.

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/ev-charging/...?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": ["ev-charging"]}` 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/ev-charging/brands

**List network brands**

Charging-network brands as `{ id, name, registrationNo }`. Not paginated. Provisional — confirmed by the shape check at registration (docs/launch.md §8).

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

Parametre yok.

**Örnek**

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

### GET /v1/ev-charging/cities

**List cities**

All provinces with their ids and official codes. 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/ev-charging/cities" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/ev-charging/districts

**List the districts of a city**

The districts of one city, with the city in `meta.city`. Not paginated. Provisional — confirmed by the shape check at registration (docs/launch.md §8).

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `city` | query | string | evet | City id or name, case- and Turkish-character-insensitive. |

**Örnek**

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

### GET /v1/ev-charging/mobile-units

**List mobile charging units**

Mobile charging units serving one or more cities, with the applied filter in `meta.filter`. Not paginated. Provisional — confirmed by the shape check at registration (docs/launch.md §8).

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `cities` | query | string | evet | Comma-separated city ids or names. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/ev-charging/mobile-units?cities=%C4%B0STANBUL" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/ev-charging/stations

**Search charging stations**

Stations matching the filters, with the applied filters in `meta.filter`. Not paginated: every match comes in one answer. At least one narrowing filter is required: `text`, `socketTypes`, `networkOperators`, `networkOperatorBrands`, `cities`, `districts` (as ids; district names need `cities`), numeric `latitude` with `longitude`, or numeric `startPrice` with `endPrice`. `available`, `compatibleStations` and `green` do not narrow enough on their own: combine them with another filter. `startPrice` and `endPrice` go together. A search without a narrowing filter, or with only one of the prices, is answered `400` by ServiceBox without calling the source, and is not charged. A coordinate search uses `latitude`, `longitude` and `distance` (kilometres, default 10). Provisional — confirmed by the shape check at registration (docs/launch.md §8).

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `text` | query | string | hayır | Free-text search over station name and address. |
| `socketTypes` | query | string | hayır | Comma-separated socket types: `AC_TYPE2`, `DC_CCS`, `DC_CHADEMO`. |
| `available` | query | boolean | hayır | Boolean filter. Only together with another filter. |
| `compatibleStations` | query | boolean | hayır | Boolean filter. Only together with another filter. |
| `networkOperators` | query | string | hayır | Comma-separated network operator ids. |
| `networkOperatorBrands` | query | string | hayır | Comma-separated brand ids (`id` from `/v1/ev-charging/brands`). |
| `cities` | query | string | hayır | Comma-separated city ids or names. |
| `districts` | query | string | hayır | Comma-separated district ids; district names require `cities`. |
| `green` | query | boolean | hayır | Boolean filter. Only together with another filter. |
| `latitude` | query | number | hayır | Latitude of a coordinate search (WGS84), with `longitude`. |
| `longitude` | query | number | hayır | Longitude of a coordinate search (WGS84), with `latitude`. |
| `distance` | query | number | hayır | Radius of a coordinate search, in kilometres. |
| `startPrice` | query | number | hayır | Lowest price in TL/kWh. Goes together with `endPrice`. |
| `endPrice` | query | number | hayır | Highest price in TL/kWh. Goes together with `startPrice`. |

**Örnek**

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

### GET /v1/ev-charging/stations/price-range

**Get the day's price range**

The lowest and highest charging price per kWh for a date, as a bare object. `0` is free charging, a real price. Provisional — confirmed by the shape check at registration (docs/launch.md §8).

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `date` | query | string | hayır | Day to price, `YYYY-MM-DD`. Defaults to today in Europe/Istanbul. Anything but a real calendar date is a `400`, answered without calling the source and not charged. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/ev-charging/stations/price-range" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/ev-charging/stations/{id}

**Get a charging station**

Full station detail as a bare object: location, E.164 phone, operator, and sockets with connector type, power in kW, price per kWh, price windows and availability windows, plus payment types. An unknown id is a `404 not_found`. Provisional — confirmed by the shape check at registration (docs/launch.md §8).

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

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `id` | path | string | evet | Station id (`id` from a station search). |
| `date` | query | string | hayır | Day to price, `YYYY-MM-DD`. Defaults to today in Europe/Istanbul. Anything but a real calendar date is a `400`, answered without calling the source and not charged. |

**Örnek**

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