# EV charging (SBX-SARJ)

Electric-vehicle charging stations across Turkey: socket types, power, prices and availability; search by city, district, brand, socket type, price range or location, plus mobile charging units.

Version: v1.0

## Authentication

Send your API key on every request, either as a Bearer token or as the `apikey` query parameter:

```
Authorization: Bearer <YOUR_API_KEY>
https://api.servicebox.io/v1/ev-charging/...?apikey=<YOUR_API_KEY>
```

Get a key: sign up at https://servicebox.io/en/signup and create one on the dashboard. An agent can sign up itself with `POST https://api.servicebox.io/v1/accounts` and `{"email": "...", "apis": ["ev-charging"]}`: the owner of the mailbox approves by email and the agent collects a short-lived key by polling the returned `poll_url`.

## Base URL

`https://api.servicebox.io`

## Endpoints

### 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).

**Credits:** free (0 credits per call)

No parameters.

**Example**

```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.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```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).

**Credits:** free (0 credits per call)

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `city` | query | string | yes | City id or name, case- and Turkish-character-insensitive. |

**Example**

```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).

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cities` | query | string | yes | Comma-separated city ids or names. |

**Example**

```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).

**Credits:** 2 per call

**Parameters**

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

**Example**

```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).

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `date` | query | string | no | 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. |

**Example**

```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).

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Station id (`id` from a station search). |
| `date` | query | string | no | 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. |

**Example**

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

## Errors

Errors are RFC 9457 `application/problem+json` bodies with a machine-readable `type`.

- `401` — the key is missing, unknown, expired or revoked.
- `402` — not enough credits: the body carries `credits_required` and `upgrade_url` (https://servicebox.io/en/pricing).
- `403` — the key is not allowed to call this API.
- `429` — rate limited: wait `retry_after` seconds (also sent as the `Retry-After` header); `upgrade_url` points to a larger plan.

## Links

- OpenAPI document: https://api.servicebox.io/v1/ev-charging/openapi.json
- Pricing: https://servicebox.io/en/pricing?api=SBX-SARJ
- API page: https://servicebox.io/en/apis/ev-charging