{"info":{"title":"ServiceBox — Akaryakıt Fiyatları API","version":"1.0.0","description":"EPDK dealer fuel prices for all 81 Turkish provinces, per city and district. Each item of the station price list is a dealer's station with its prices per litre in Turkish lira and the station details: the EPDK licence merged with a verified Google Maps place when one matches. Cities and districts accept an EPDK id or a name, case- and Turkish-character-insensitive. Answers follow the ServiceBox response style: collections answer `{ items, next_cursor, total }` (plus `meta` for query context); every list of this API comes whole in one answer, so `next_cursor` is always null. Every answer carries `X-SBX-Response-Style: 1`. Responses carry an ETag; send it back in If-None-Match on the same URL to revalidate cheaply."},"paths":{"/v1/fuel/cities":{"get":{"tags":["Reference"],"summary":"List cities","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AreaList"},"example":{"items":[{"id":"1","name":"ADANA"}],"total":81,"next_cursor":null}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"}},"description":"EPDK cities."},"304":{"$ref":"#/components/responses/NotModified"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"All EPDK cities (provinces) with their EPDK ids. Not paginated: the whole list in one answer.","operationId":"listCities","x-sbx-credits":0}},"/v1/fuel/stations":{"get":{"tags":["Prices"],"summary":"List stations with fuel prices","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"},"example":{"meta":{"city":{"id":"1","name":"ADANA"},"mode":"single","complete":true,"currency":"TRY","districts":[{"id":"1","name":"ALADAĞ"}],"fetchedAt":"2026-09-21T20:41:28.657Z"},"items":[{"dealer":"Dealer legal name (BAY/...)","station":{"city":"ADANA","name":"Official station name","phone":null,"rating":null,"address":"Official EPDK facility address","license":{"number":"BAY/...","status":"Yürürlükte","endDate":"2030-02-01","category":"ISTASYONLU","subtitle":"AKARYAKIT","legalName":"Official legal name","startDate":"2020-02-01","distributor":"Official distributor"},"website":null,"district":"ALADAĞ","location":null,"mapsAddress":null,"ratingCount":null,"googleMapsUri":null},"distributor":"Distributor legal name","pricesPerLitre":{"diesel":97.65,"gasoline95":81.78,"dieselOther":null,"gasolineOther":null}}],"total":4,"next_cursor":null}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"}},"description":"The stations of the requested districts with their prices."},"304":{"$ref":"#/components/responses/NotModified"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/District"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.","operationId":"listPrices","x-sbx-credits":2}},"/v1/fuel/districts":{"get":{"tags":["Reference"],"summary":"List the districts of a city","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistrictList"},"example":{"meta":{"city":{"id":"1","name":"ADANA"}},"items":[{"id":"1","name":"ALADAĞ"},{"id":"2","name":"CEYHAN"}],"total":16,"next_cursor":null}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"}},"description":"The districts of the city."},"304":{"$ref":"#/components/responses/NotModified"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.","operationId":"listDistricts","x-sbx-credits":0}},"/v1/fuel/stations/lookup":{"get":{"tags":["Stations"],"summary":"Look up a station by licence","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Station"},"example":{"city":"ADANA","name":"Official station name","phone":null,"rating":null,"address":"Official EPDK facility address","license":{"number":"BAY/...","status":"Yürürlükte","endDate":"2030-02-01","category":"ISTASYONLU","subtitle":"AKARYAKIT","legalName":"Official legal name","startDate":"2020-02-01","distributor":"Official distributor"},"website":null,"district":"ALADAĞ","location":null,"mapsAddress":null,"ratingCount":null,"googleMapsUri":null}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"}},"description":"The station."},"304":{"$ref":"#/components/responses/NotModified"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"$ref":"#/components/parameters/License"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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`.","operationId":"getStation","x-sbx-credits":1}}},"openapi":"3.1.0","servers":[{"url":"https://api.servicebox.io"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"headers":{"ETag":{"schema":{"type":"string"},"description":"Opaque entity tag of this representation (`W/\"…-t<version>\"`). Send it back in `If-None-Match` on the same URL to revalidate; after a change to the answer's shape you get one full 200 with a new tag."}},"schemas":{"Area":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","description":"EPDK numeric id, as a string. District ids are specific to their city."},"name":{"type":"string","description":"Name, uppercase, as EPDK spells it."}},"description":"An EPDK city or district."},"License":{"type":"object","required":["number","status","legalName","startDate","endDate","distributor","category","subtitle"],"properties":{"number":{"type":"string","description":"EPDK licence number (`BAY/...`)."},"status":{"type":["string","null"],"description":"Licence status as EPDK states it, e.g. `Yürürlükte`."},"endDate":{"type":["string","null"],"format":"date","description":"Licence end date, `YYYY-MM-DD`; null when EPDK's date is missing or impossible."},"category":{"type":["string","null"],"description":"Licence category, e.g. `ISTASYONLU`."},"subtitle":{"type":["string","null"],"description":"Licence subtitle, e.g. `AKARYAKIT`."},"legalName":{"type":["string","null"],"description":"Official legal name of the licence holder."},"startDate":{"type":["string","null"],"format":"date","description":"Licence start date, `YYYY-MM-DD`; null when EPDK's date is missing or impossible."},"distributor":{"type":["string","null"],"description":"Official distributor."}},"description":"The station's EPDK licence record."},"Problem":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri","description":"A URI identifying the problem type."},"title":{"type":"string","description":"Short, human-readable summary of the problem type."},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence."},"status":{"type":"integer","description":"HTTP status code."},"upstream_status":{"type":"integer","description":"The upstream's HTTP status, on problems caused by an upstream answer."}},"description":"RFC 9457 problem detail."},"Station":{"type":"object","required":["name","address","mapsAddress","city","district","location","googleMapsUri","phone","website","rating","ratingCount","license"],"properties":{"city":{"type":["string","null"],"description":"City (province), uppercase."},"name":{"type":["string","null"],"description":"Official station name."},"phone":{"type":["string","null"],"description":"Phone of the matched place in E.164 (`+90…`), or null."},"rating":{"type":["number","null"],"description":"Google Maps rating, or null."},"address":{"type":["string","null"],"description":"Official EPDK facility address."},"license":{"oneOf":[{"$ref":"#/components/schemas/License"},{"type":"null"}],"description":"The EPDK licence, or null."},"website":{"type":["string","null"],"description":"Website of the matched place, or null."},"district":{"type":["string","null"],"description":"District, uppercase."},"location":{"$ref":"#/components/schemas/Location"},"mapsAddress":{"type":["string","null"],"description":"Address of the matched Google Maps place, or null."},"ratingCount":{"type":["integer","null"],"description":"Number of Google Maps ratings, or null."},"googleMapsUri":{"type":["string","null"],"description":"Google Maps link of the matched place, or null."}},"description":"The EPDK licence merged with a verified Google Maps place when one matches. Without a match the Maps-derived fields are null."},"AreaList":{"type":"object","required":["items","next_cursor","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Area"}},"total":{"type":"integer","description":"How many there are."},"next_cursor":{"type":["string","null"],"description":"Always null: the whole list comes in one answer."}}},"Location":{"type":["object","null"],"required":["lat","lon"],"properties":{"lat":{"type":"number","description":"Latitude, WGS 84."},"lon":{"type":"number","description":"Longitude, WGS 84."}},"description":"Coordinates of the matched Google Maps place, or null when no place matched or the coordinates are unusable."},"PriceRow":{"type":"object","required":["dealer","distributor","pricesPerLitre","station"],"properties":{"dealer":{"type":"string","description":"Dealer legal name, as EPDK lists it."},"station":{"oneOf":[{"$ref":"#/components/schemas/Station"},{"type":"null"}],"description":"The merged station, or null when neither an EPDK licence nor a verified Maps place is available."},"distributor":{"type":["string","null"],"description":"Distributor legal name."},"pricesPerLitre":{"type":"object","required":["gasoline95","diesel","gasolineOther","dieselOther"],"properties":{"diesel":{"type":["number","null"],"description":"Diesel. A price of `null` means the station does not sell that product."},"gasoline95":{"type":["number","null"],"description":"95-octane gasoline. A price of `null` means the station does not sell that product."},"dieselOther":{"type":["number","null"],"description":"The dealer's other diesel product. A price of `null` means the station does not sell that product."},"gasolineOther":{"type":["number","null"],"description":"The dealer's other gasoline product. A price of `null` means the station does not sell that product."}},"description":"Prices per litre in `meta.currency` (TRY)."}},"description":"One dealer station with its fuel prices."},"PriceList":{"type":"object","required":["items","next_cursor","total","meta"],"properties":{"meta":{"type":"object","required":["mode","city","districts","currency","complete","fetchedAt"],"properties":{"city":{"$ref":"#/components/schemas/Area"},"mode":{"enum":["single","selected"],"type":"string","description":"`single` for one district, `selected` for several."},"complete":{"type":"boolean","description":"Whether every source page was read."},"currency":{"type":"string","const":"TRY","description":"Currency of every price."},"districts":{"type":"array","items":{"$ref":"#/components/schemas/Area"},"description":"The requested districts."},"fetchedAt":{"type":["string","null"],"format":"date-time","description":"When the prices were read from EPDK (ISO 8601), or null."}},"description":"What was asked."},"items":{"type":"array","items":{"$ref":"#/components/schemas/PriceRow"}},"total":{"type":"integer","description":"How many stations EPDK lists for the query."},"next_cursor":{"type":["string","null"],"description":"Always null: the whole result comes in one answer."}}},"DistrictList":{"type":"object","required":["items","next_cursor","total","meta"],"properties":{"meta":{"type":"object","required":["city"],"properties":{"city":{"$ref":"#/components/schemas/Area"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/Area"}},"total":{"type":"integer","description":"How many there are."},"next_cursor":{"type":["string","null"],"description":"Always null: the whole list comes in one answer."}},"description":"The districts of one city. The envelope follows the upstream's answer as sampled; confirmed at registration."}},"responses":{"NotFound":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/not_found","title":"Not Found","detail":"No EPDK station has this licence number.","status":404}}},"description":"`not_found`: no EPDK station has this licence number. Charged like any answered lookup."},"BadGateway":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_auth":{"value":{"type":"https://servicebox.io/problems/upstream_auth","title":"Bad Gateway","detail":"The upstream refused ServiceBox's own credential; this is not about your API key. Retry later.","status":502,"upstream_status":401}},"upstream_error":{"value":{"type":"https://servicebox.io/problems/upstream_error","title":"Bad Gateway","detail":"The upstream failed (500)","status":502,"upstream_status":500}},"upstream_shape":{"value":{"type":"https://servicebox.io/problems/upstream_shape","title":"Bad Gateway","detail":"The upstream's answer did not match its documented shape; you were not charged. Retry later.","status":502}}}}},"description":"`upstream_error`: the upstream data source failed. `upstream_auth`: the upstream refused ServiceBox's own credential; not your key. `upstream_shape`: the upstream's answer did not match its documented shape; you were not charged."},"BadRequest":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/bad_request","title":"Bad Request","detail":"city is required","status":400,"upstream_status":400}}},"description":"Missing, malformed or unknown query input, e.g. no `district`, more than five districts, or an unknown city."},"NotModified":{"headers":{"ETag":{"$ref":"#/components/headers/ETag"}},"description":"The representation has not changed since the ETag in `If-None-Match`. No body."},"Unauthorized":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/unauthorized","title":"Unauthorized","detail":"Missing or invalid API key/bearer token","status":401}}},"description":"Missing or invalid credentials."},"GatewayTimeout":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/upstream_timeout","title":"Gateway Timeout","detail":"The upstream did not answer within 5000 ms","status":504}}},"description":"The upstream data source timed out."},"PaymentRequired":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/payment_required","title":"Payment Required","detail":"Insufficient credits for this request","status":402}}},"description":"Insufficient credits."},"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/rate_limited","title":"Too Many Requests","detail":"Rate limit exceeded, retry after backing off","status":429}}},"description":"Rate limit exceeded."},"ServiceUnavailable":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/service_unavailable","title":"Service Unavailable","detail":"The upstream is unavailable","status":503}}},"description":"The upstream is temporarily unavailable."}},"parameters":{"City":{"in":"query","name":"city","schema":{"type":"string"},"required":true,"description":"EPDK numeric id or name, case- and Turkish-character-insensitive (`34` and `istanbul` name the same city)."},"License":{"in":"query","name":"license","schema":{"type":"string"},"required":true,"description":"An exact EPDK dealer licence number, e.g. `BAY/000-00/00001`."},"District":{"in":"query","name":"district","schema":{"type":"string"},"required":true,"description":"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."},"IfNoneMatch":{"in":"header","name":"If-None-Match","schema":{"type":"string"},"description":"ETag from a previous response to the same URL. When it still matches, the answer is 304 with no body."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyQuery":{"in":"query","name":"apikey","type":"apiKey"}}}}