# Fuel prices (SBX-AKY)

EPDK fuel prices for all 81 provinces: gasoline and diesel prices per dealer and distributor, with EPDK licence details and verified Google Maps details where a station can be matched.

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

**List cities**

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

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

No parameters.

**Example**

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

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

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `city` | query | string | yes | EPDK numeric id or name, case- and Turkish-character-insensitive (`34` and `istanbul` name the same city). |

**Example**

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

**Credits:** 2 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `city` | query | string | yes | EPDK numeric id or name, case- and Turkish-character-insensitive (`34` and `istanbul` name the same city). |
| `district` | query | string | yes | 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. |

**Example**

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

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `license` | query | string | yes | An exact EPDK dealer licence number, e.g. `BAY/000-00/00001`. |

**Example**

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