{"info":{"title":"ServiceBox — Gold & Commodities API","version":"1.0.0","description":"Gold by weight and the Turkish coins (çeyrek, yarım, tam, Cumhuriyet…) valued daily in TRY, USD and EUR since 2013, from Narodowy Bank Polski's fine-gold price; daily energy spot prices (Brent, WTI, Henry Hub, gasoline, diesel, jet fuel, propane) from the US EIA; and monthly prices of 67 commodities (metals, energy, grains, softs, fertilizers, timber) from the World Bank. Collections answer `{ items, next_cursor, total }`; page with `limit` (1–200, default 50) and `cursor` (pass back `next_cursor` with the same filters). Errors are RFC 9457 problems. Every answer has an ETag: send it back in `If-None-Match` for a `304` while the data is unchanged.\n\nSources: Narodowy Bank Polski (gold price calculated at NBP; NBP exchange rates); Central Bank of the Republic of Türkiye (USD/TRY); U.S. Energy Information Administration (EIA) spot prices; World Bank Commodity Price Data (The Pink Sheet), licensed under CC BY 4.0. Coin weights: Darphane specifications. Values are intrinsic (fine-gold) values, not dealer prices."},"paths":{"/v1/gold/prices":{"get":{"summary":"Gold prices on a date","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total","meta"],"properties":{"meta":{"type":"object","required":["date","currency","finePerGram","finePerOunce","source","rates"],"properties":{"date":{"type":"string","format":"date"},"rates":{"type":"array","items":{"type":"object","required":["pair","rate","source","date"],"properties":{"date":{"type":"string","format":"date"},"pair":{"type":"string","examples":["USD/TRY"]},"rate":{"type":"number"},"source":{"enum":["nbp","tcmb"],"type":"string"}}}},"source":{"enum":["nbp"],"type":"string"},"currency":{"type":"string"},"finePerGram":{"type":"number"},"finePerOunce":{"type":"number"},"requestedDate":{"type":["string","null"]}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/GoldPrice"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"The prices."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found."},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"query","name":"currency","schema":{"enum":["TRY","USD","EUR"],"type":"string","default":"TRY"},"required":false,"description":"`TRY` (default), `USD` or `EUR`."},{"in":"query","name":"date","schema":{"type":"string","format":"date"},"required":false,"description":"YYYY-MM-DD, since 2013-01-02. A day without a price answers the latest one before it (`meta.date`)."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"The intrinsic value of gram gold (24, 22, 18 and 14 karat), the troy ounce and the Turkish coins (çeyrek, yarım, tam, ikibuçuk, beşli, Cumhuriyet, Ata beşli) on `date` (default: the latest price), from the price of 1 g of fine gold calculated by Narodowy Bank Polski each Polish business day. USD and EUR use NBP's mid rates of that day; TRY goes through USD at TCMB's forex midpoint of the latest bulletin on or before that day (`meta.rates`). These are melt values, without workmanship or a dealer's spread.","operationId":"listGoldPrices","x-sbx-credits":1}},"/v1/gold/products":{"get":{"summary":"List gold products","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/GoldProduct"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"The products."},"304":{"description":"Not modified."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"Gram gold by karat, the troy ounce and the Turkish coins, with their weight and fine-gold content. Free.","operationId":"listGoldProducts","x-sbx-credits":0}},"/v1/gold/commodities":{"get":{"summary":"List commodities","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Commodity"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"The series."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"query","name":"category","schema":{"enum":["energy","precious-metals","base-metals","agriculture","fertilizers","raw-materials"],"type":"string"},"required":false,"description":"Only this category."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"Every commodity series: daily energy spot prices (EIA) and monthly prices of metals, energy, agriculture, fertilizers and raw materials (World Bank), with the span held. Free.","operationId":"listCommodities","x-sbx-credits":0}},"/v1/gold/commodity-prices":{"get":{"summary":"Latest commodity prices","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CommodityLatest"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"The prices."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"query","name":"codes","schema":{"type":"string"},"required":false,"description":"Comma-separated codes from /gold/commodities, e.g. brent,wti,gold. Default: every series."},{"in":"query","name":"category","schema":{"enum":["energy","precious-metals","base-metals","agriculture","fertilizers","raw-materials"],"type":"string"},"required":false,"description":"Only this category."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"Each series' latest price and the one before it, with the change. EIA's daily prices are released weekly (Wednesdays), the World Bank's monthly averages in the first days of each month.","operationId":"listLatestCommodityPrices","x-sbx-credits":1}},"/v1/gold/prices/{product}":{"get":{"summary":"One product over time","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total","meta"],"properties":{"meta":{"type":"object","properties":{"end":{"type":"string"},"name":{"type":"string"},"start":{"type":"string"},"nameTr":{"type":"string"},"source":{"type":"string"},"product":{"type":"string"},"currency":{"type":"string"},"fineGrams":{"type":"number"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/GoldPoint"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"The series."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found."},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"path","name":"product","schema":{"type":"string"},"required":true,"description":"A product id from /gold/products, e.g. gram-24k or ceyrek."},{"in":"query","name":"currency","schema":{"enum":["TRY","USD","EUR"],"type":"string","default":"TRY"},"required":false,"description":"`TRY` (default), `USD` or `EUR`."},{"in":"query","name":"start","schema":{"type":"string","format":"date"},"required":false,"description":"YYYY-MM-DD."},{"in":"query","name":"end","schema":{"type":"string","format":"date"},"required":false,"description":"YYYY-MM-DD. Default: today."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"One product's intrinsic value on every NBP business day between `start` and `end` (default: the last 30 days; at most 366 days), since 2013-01-02.","operationId":"getGoldPriceHistory","x-sbx-credits":1}},"/v1/gold/commodity-prices/{code}":{"get":{"summary":"One commodity over time","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total","meta"],"properties":{"meta":{"type":"object","properties":{"end":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"unit":{"type":"string"},"start":{"type":"string"},"nameTr":{"type":"string"},"source":{"type":"string"},"unitTr":{"type":"string"},"category":{"type":"string"},"currency":{"type":"string"},"frequency":{"type":"string"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/CommodityPoint"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"The series."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found."},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"path","name":"code","schema":{"type":"string"},"required":true,"description":"A code from /gold/commodities, e.g. brent."},{"in":"query","name":"start","schema":{"type":"string"},"required":false,"description":"YYYY-MM-DD (monthly series: also YYYY-MM)."},{"in":"query","name":"end","schema":{"type":"string"},"required":false,"description":"YYYY-MM-DD (monthly series: also YYYY-MM). Default: today."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"One series between `start` and `end`. Daily series: at most 366 days (default: the last 30). Monthly series: YYYY-MM or YYYY-MM-DD, at most 600 months (default: the last 24).","operationId":"getCommodityHistory","x-sbx-credits":1}}},"openapi":"3.1.0","servers":[{"url":"https://api.servicebox.io"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"schemas":{"Bank":{"type":"object","required":["code","ibanBankCode","name"],"properties":{"code":{"type":"string","examples":["0010"]},"name":{"type":"string","examples":["T.C. ZİRAAT BANKASI A.Ş."]},"ibanBankCode":{"type":"string","examples":["00010"]}}},"City":{"type":"object","required":["id","name","asciiName","countryCode","subdivision","population","timezone","elevation","location","isCapital"],"properties":{"id":{"type":"string","examples":["745044"],"description":"GeoNames id."},"name":{"type":"string","examples":["İstanbul"]},"location":{"$ref":"#/components/schemas/Location"},"timezone":{"type":["string","null"],"examples":["Europe/Istanbul"]},"asciiName":{"type":"string","examples":["Istanbul"]},"elevation":{"type":["integer","null"],"description":"Metres."},"isCapital":{"type":"boolean"},"population":{"type":"integer"},"countryCode":{"type":"string","examples":["TR"]},"subdivision":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"FxRate":{"type":"object","required":["code","name","nameTr"],"properties":{"code":{"type":"string","examples":["USD"]},"name":{"type":"string","examples":["US Dollar"]},"rate":{"type":"number","description":"ECB: 1 EUR in this currency."},"unit":{"type":"integer","description":"TCMB: the rates are for this many units (JPY: 100)."},"nameTr":{"type":"string","examples":["ABD doları"]},"forexBuying":{"type":["number","null"]},"forexSelling":{"type":["number","null"]},"banknoteBuying":{"type":["number","null"]},"banknoteSelling":{"type":["number","null"]}},"description":"TCMB answers carry `unit` and the four TRY rates per `unit` units; ECB answers carry `rate` (1 EUR = rate)."},"Country":{"type":"object","required":["code","iso3","isoNumeric","name","nameTr","flag","continent","population","languages","neighbours","subdivisionCount"],"properties":{"tld":{"type":["string","null"],"examples":[".tr"]},"code":{"type":"string","examples":["TR"],"description":"ISO 3166-1 alpha-2."},"flag":{"type":"string","examples":["🇹🇷"]},"iso3":{"type":"string","examples":["TUR"]},"name":{"type":"string","examples":["Turkey"],"description":"English name."},"nameTr":{"type":"string","examples":["Türkiye"],"description":"Turkish name."},"areaKm2":{"type":["number","null"]},"capital":{"type":["string","null"],"examples":["Ankara"]},"currency":{"type":["object","null"],"required":["code","name","nameTr"],"properties":{"code":{"type":"string","examples":["TRY"]},"name":{"type":["string","null"]},"nameTr":{"type":["string","null"]}}},"continent":{"type":"object","required":["code","name"],"properties":{"code":{"enum":["AF","AN","AS","EU","NA","OC","SA"],"type":"string"},"name":{"type":"string"}}},"languages":{"type":"array","items":{"type":"string"},"examples":[["tr-TR","ku","diq","az","av"]]},"isoNumeric":{"type":"string","examples":["792"]},"neighbours":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 codes of bordering countries."},"population":{"type":"integer"},"phonePrefix":{"type":["string","null"],"examples":["+90"]},"postalCodeFormat":{"type":["string","null"],"examples":["#####"]},"subdivisionCount":{"type":"integer"}}},"FxPoint":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date"},"rate":{"type":"number"},"unit":{"type":"integer"},"forexBuying":{"type":["number","null"]},"forexSelling":{"type":["number","null"]},"banknoteBuying":{"type":["number","null"]},"banknoteSelling":{"type":["number","null"]}}},"Problem":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"status":{"type":"integer"}}},"Coverage":{"type":"object","required":["dataVersion","places","ipAddresses"],"properties":{"places":{"type":"object","required":["source","licence","postalCodeCountries"],"properties":{"source":{"type":"string"},"licence":{"type":"string"},"postalCodeCountries":{"type":"array","items":{"type":"string"}}}},"dataVersion":{"type":"string","examples":["20260927"],"description":"The data snapshot, `YYYYMMDD`."},"ipAddresses":{"type":"object","required":["source","licence","level"],"properties":{"level":{"enum":["country"],"type":"string"},"source":{"type":"string"},"licence":{"type":"string"}}}}},"District":{"type":"object","required":["id","name","asciiName","countryCode","subdivision"],"properties":{"id":{"type":"string","examples":["TR.34.7732454"],"description":"Stable id, `<country>.<subdivision code>.<GeoNames id>`."},"name":{"type":"string","examples":["Avcılar"]},"asciiName":{"type":"string","examples":["Avcilar"]},"countryCode":{"type":"string","examples":["TR"]},"subdivision":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"IpLookup":{"type":"object","required":["ip","version","country"],"properties":{"ip":{"type":"string","examples":["88.255.1.1"],"description":"The address, normalized (IPv4-mapped IPv6 as IPv4, IPv6 compressed)."},"country":{"type":["object","null"],"required":["code","name","nameTr"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"nameTr":{"type":"string"}},"description":"Null for reserved, private or unassigned addresses."},"version":{"enum":[4,6],"type":"integer"}}},"Location":{"type":"object","required":["lat","lon"],"properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"Timezone":{"type":"object","required":["id","cityCount"],"properties":{"id":{"type":"string","examples":["Europe/Istanbul"],"description":"IANA timezone name."},"cityCount":{"type":"integer"}}},"Commodity":{"type":"object","required":["code","name","nameTr","category","unit","unitTr","currency","frequency","source","from","to"],"properties":{"to":{"type":["string","null"],"description":"The latest date or month held."},"code":{"type":"string","examples":["brent"]},"from":{"type":["string","null"],"description":"The first date (daily) or month (monthly) held."},"name":{"type":"string","examples":["Crude oil, Brent (Europe spot FOB)"]},"unit":{"type":"string","examples":["USD/bbl"]},"nameTr":{"type":"string","examples":["Ham petrol, Brent (Avrupa spot FOB)"]},"source":{"enum":["eia","worldbank"],"type":"string"},"unitTr":{"type":"string","examples":["USD/varil"]},"category":{"enum":["energy","precious-metals","base-metals","agriculture","fertilizers","raw-materials"],"type":"string"},"currency":{"enum":["USD"],"type":"string"},"frequency":{"enum":["daily","monthly"],"type":"string"}}},"Condition":{"type":["object","null"],"required":["code","name","nameTr","daylight"],"properties":{"code":{"type":"string","examples":["partlycloudy"]},"name":{"type":"string"},"nameTr":{"type":"string"},"daylight":{"type":["boolean","null"]}}},"Continent":{"type":"object","required":["code","name","countryCount"],"properties":{"code":{"enum":["AF","AN","AS","EU","NA","OC","SA"],"type":"string"},"name":{"type":"string"},"countryCount":{"type":"integer"}}},"GoldPoint":{"type":"object","required":["date","intrinsicValue"],"properties":{"date":{"type":"string","format":"date"},"intrinsicValue":{"type":"number"}}},"GoldPrice":{"type":"object","required":["id","name","nameTr","fineGrams","intrinsicValue"],"properties":{"id":{"type":"string","examples":["gram-24k"]},"name":{"type":"string"},"nameTr":{"type":"string"},"fineGrams":{"type":"number"},"intrinsicValue":{"type":"number","description":"The value of the fine gold it contains, in `meta.currency`, 2 decimals. No workmanship or dealer spread: a dealer's price for a coin is higher."}}},"IbanCheck":{"type":"object","required":["iban","formatted","valid","reasons","country","bank"],"properties":{"bank":{"type":["object","null"],"required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"}},"description":"Turkish IBANs: the TCMB payment-systems participant its bank code names; null when unknown."},"iban":{"type":"string","examples":["TR330006100519786457841326"],"description":"Electronic format: no spaces, upper case."},"valid":{"type":"boolean"},"country":{"type":["object","null"],"required":["code","name","nameTr"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"nameTr":{"type":"string"}}},"reasons":{"type":"array","items":{"enum":["format","unknown_country","length","checksum","tr_reserved_digit"],"type":"string"},"description":"Why it is not valid; empty when valid."},"formatted":{"type":"string","examples":["TR33 0006 1005 1978 6457 8413 26"],"description":"Print format, groups of four."}}},"PrayerDay":{"type":"object","required":["date","fajr","sunrise","dhuhr","asr","maghrib","isha"],"properties":{"asr":{"type":["string","null"],"format":"date-time"},"date":{"type":"string","format":"date","examples":["2026-09-27"]},"fajr":{"type":["string","null"],"format":"date-time","examples":["2026-09-27T05:25:00+03:00"]},"isha":{"type":["string","null"],"format":"date-time"},"dhuhr":{"type":["string","null"],"format":"date-time"},"maghrib":{"type":["string","null"],"format":"date-time"},"sunrise":{"type":["string","null"],"format":"date-time"}},"description":"One day's times, ISO 8601 with the place's UTC offset that day, to the minute. In Turkish: fajr = İmsak, sunrise = Güneş, dhuhr = Öğle, asr = İkindi, maghrib = Akşam, isha = Yatsı. A time is null on a day the sun does not rise or set there (polar day or night)."},"FxCurrency":{"type":"object","required":["code","name","nameTr","tcmb","ecb"],"properties":{"ecb":{"type":["object","null"],"properties":{"to":{"type":"string","format":"date"},"from":{"type":"string","format":"date"}}},"code":{"type":"string"},"name":{"type":"string"},"tcmb":{"type":["object","null"],"properties":{"to":{"type":"string","format":"date"},"from":{"type":"string","format":"date"}}},"nameTr":{"type":"string"}}},"HistoryDay":{"type":"object","required":["date","temperatureMean","temperatureMax","temperatureMin","precipitation","humidity","windSpeed"],"properties":{"date":{"type":"string","format":"date"},"humidity":{"type":["number","null"]},"windSpeed":{"type":["number","null"],"description":"m/s at 2 m"},"precipitation":{"type":["number","null"],"description":"mm per day"},"temperatureMax":{"type":["number","null"]},"temperatureMin":{"type":["number","null"]},"temperatureMean":{"type":["number","null"]}}},"PhoneCheck":{"type":"object","required":["input","valid","reasons","e164","national","type"],"properties":{"e164":{"type":["string","null"],"examples":["+905321234567"]},"type":{"enum":["mobile","landline","toll_free","shared_cost","single_number","premium",null],"type":["string","null"]},"input":{"type":"string"},"valid":{"type":"boolean"},"reasons":{"type":"array","items":{"enum":["format","not_turkish","length","unknown_range"],"type":"string"}},"national":{"type":["string","null"],"examples":["0532 123 45 67"]}}},"TaxIdCheck":{"type":"object","required":["id","valid","reasons"],"properties":{"id":{"type":"string"},"valid":{"type":"boolean","description":"The check digit holds: a possible number, not proof that the taxpayer exists."},"reasons":{"type":"array","items":{"enum":["not_digits","length","checksum"],"type":"string"}}}},"GoldProduct":{"type":"object","required":["id","name","nameTr","grossGrams","karat","fineness","fineGrams"],"properties":{"id":{"type":"string","examples":["ceyrek"]},"name":{"type":"string","examples":["Quarter coin (çeyrek)"]},"karat":{"type":"integer"},"nameTr":{"type":"string","examples":["Çeyrek altın"]},"fineness":{"type":"number","description":"Fine-gold share: 22 karat = 22/24."},"fineGrams":{"type":"number","description":"Grams of fine gold."},"grossGrams":{"type":"number","description":"Weight, grams (Darphane specification for the coins)."}}},"HistoryHour":{"type":"object","required":["time","temperature","precipitation","humidity","windSpeed"],"properties":{"time":{"type":"string","format":"date-time"},"humidity":{"type":["number","null"]},"windSpeed":{"type":["number","null"]},"temperature":{"type":["number","null"]},"precipitation":{"type":["number","null"]}}},"PlaceLookup":{"type":"object","required":["location","country","subdivision","district","postalCode","nearestCity"],"properties":{"country":{"type":["object","null"],"required":["code","name","nameTr"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"nameTr":{"type":"string"}},"description":"The nearest city's country; null when no city of 1,000+ inhabitants is within 100 km."},"district":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"description":"The nearest located postal place's district (Turkey), within 5 km."},"location":{"$ref":"#/components/schemas/Location"},"postalCode":{"type":["object","null"],"required":["postalCode","name","distanceKm"],"properties":{"name":{"type":"string"},"distanceKm":{"type":"number"},"postalCode":{"type":"string"}}},"nearestCity":{"type":["object","null"],"required":["id","name","population","distanceKm"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"distanceKm":{"type":"number"},"population":{"type":"integer"}}},"subdivision":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"PostalPlace":{"type":"object","required":["postalCode","name","countryCode","district","subdivision","location"],"properties":{"name":{"type":"string","examples":["Firuzköy"],"description":"The place the code serves; in Turkey a neighbourhood (mahalle) or village. Spelled as the postal source publishes it, which often writes ı as i."},"district":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"location":{"anyOf":[{"$ref":"#/components/schemas/Location"},{"type":"null"}],"description":"The place's own point; null when the source only locates the district."},"postalCode":{"type":"string","examples":["34310"]},"countryCode":{"type":"string","examples":["TR"]},"subdivision":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"Subdivision":{"type":"object","required":["id","code","countryCode","name","asciiName"],"properties":{"id":{"type":"string","examples":["TR.34"],"description":"Stable id, `<country>.<code>`. Not an ISO 3166-2 code."},"code":{"type":"string","examples":["34"]},"name":{"type":"string","examples":["İstanbul"]},"asciiName":{"type":"string","examples":["Istanbul"]},"countryCode":{"type":"string","examples":["TR"]}}},"FxConversion":{"type":"object","required":["from","to","amount","result","rate","date","source","rateType"],"properties":{"to":{"type":"string"},"date":{"type":"string","format":"date","description":"The bulletin used."},"from":{"type":"string"},"rate":{"type":"number","description":"1 `from` in `to`."},"amount":{"type":"number"},"result":{"type":"number"},"source":{"enum":["tcmb","ecb"],"type":"string"},"rateType":{"enum":["mid","buying","selling","reference"],"type":"string"}}},"PrayerMethod":{"type":"object","required":["id","name","fajrAngle","ishaAngle","ishaIntervalMinutes"],"properties":{"id":{"type":"string","examples":["turkey"]},"name":{"type":"string"},"fajrAngle":{"type":"number"},"ishaAngle":{"type":["number","null"]},"ishaIntervalMinutes":{"type":["integer","null"],"description":"Yatsı a fixed time after Akşam (Umm al-Qura, Qatar), instead of an angle."}}},"DailyForecast":{"type":"object","required":["date","temperatureMax","temperatureMin","precipitation","windSpeedMax","condition"],"properties":{"date":{"type":"string","format":"date"},"condition":{"$ref":"#/components/schemas/Condition"},"windSpeedMax":{"type":["number","null"]},"precipitation":{"type":"number","description":"mm over the day"},"temperatureMax":{"type":["number","null"]},"temperatureMin":{"type":["number","null"]}}},"MonthlyNormal":{"type":"object","required":["month","temperatureMean","temperatureHighest","temperatureLowest","precipitation","humidity","windSpeed"],"properties":{"month":{"type":"integer","maximum":12,"minimum":1},"humidity":{"type":["number","null"]},"windSpeed":{"type":["number","null"]},"precipitation":{"type":["number","null"],"description":"mm over the month"},"temperatureMean":{"type":["number","null"],"description":"Mean temperature of the month over 2001–2020, °C."},"temperatureLowest":{"type":["number","null"],"description":"Lowest hourly temperature of that month over 2001–2020 (an extreme, not an average low), °C."},"temperatureHighest":{"type":["number","null"],"description":"Highest hourly temperature of that month over 2001–2020 (an extreme, not an average high), °C."}}},"CommodityPoint":{"type":"object","required":["date","value"],"properties":{"date":{"type":"string","description":"YYYY-MM-DD (daily) or YYYY-MM (monthly)."},"value":{"type":"number"}}},"CurrentWeather":{"type":"object","required":["time","temperature","feelsLike","humidity","pressure","cloudCover","windSpeed","windDirection","condition","location","timezone","city","updatedAt","source"],"properties":{"city":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string"}}},"time":{"type":"string","format":"date-time"},"source":{"type":"string"},"dewPoint":{"type":["number","null"],"description":"°C"},"humidity":{"type":["number","null"],"description":"%"},"location":{"$ref":"#/components/schemas/Location"},"pressure":{"type":["number","null"],"description":"hPa, at sea level"},"timezone":{"type":"string"},"windGust":{"type":["number","null"],"description":"m/s"},"condition":{"$ref":"#/components/schemas/Condition"},"feelsLike":{"type":["number","null"],"description":"°C"},"updatedAt":{"type":"string","format":"date-time","description":"When MET's model run was issued."},"windSpeed":{"type":["number","null"],"description":"m/s"},"cloudCover":{"type":["number","null"],"description":"%"},"temperature":{"type":["number","null"],"description":"°C"},"windDirection":{"type":["number","null"],"description":"Degrees the wind comes from."},"uvIndexClearSky":{"type":["number","null"]},"precipitationNextHour":{"type":["number","null"],"description":"mm"}}},"HourlyForecast":{"type":"object","required":["time","temperature","precipitation","windSpeed","condition"],"properties":{"time":{"type":"string","format":"date-time"},"humidity":{"type":["number","null"]},"condition":{"$ref":"#/components/schemas/Condition"},"feelsLike":{"type":["number","null"]},"windSpeed":{"type":["number","null"]},"cloudCover":{"type":["number","null"]},"temperature":{"type":["number","null"]},"precipitation":{"type":["number","null"],"description":"mm in the hour"},"windDirection":{"type":["number","null"]},"precipitationProbability":{"type":["number","null"],"description":"%"}}},"CommodityLatest":{"type":"object","required":["code","name","nameTr","category","unit","unitTr","currency","frequency","source","date","value","previousDate","previousValue","change","changePercent"],"properties":{"code":{"type":"string"},"date":{"type":"string","description":"YYYY-MM-DD for daily series, YYYY-MM for monthly ones."},"name":{"type":"string"},"unit":{"type":"string"},"value":{"type":"number"},"change":{"type":["number","null"],"description":"`value` − `previousValue`."},"nameTr":{"type":"string"},"source":{"type":"string"},"unitTr":{"type":"string"},"category":{"type":"string"},"currency":{"type":"string"},"frequency":{"enum":["daily","monthly"],"type":"string"},"previousDate":{"type":["string","null"]},"changePercent":{"type":["number","null"],"description":"Percent, 2 decimals."},"previousValue":{"type":["number","null"]}}},"DegreeDaysMonth":{"type":"object","required":["month","heatingDegreeDays","coolingDegreeDays","daysMissing"],"properties":{"month":{"type":"string","examples":["2025-01"]},"daysMissing":{"type":"integer"},"coolingDegreeDays":{"type":"number"},"heatingDegreeDays":{"type":"number"}}},"NationalIdCheck":{"type":"object","required":["id","valid","reasons","kind"],"properties":{"id":{"type":"string"},"kind":{"enum":["citizen","foreign",null],"type":["string","null"],"description":"`foreign` for a YKN (starts with 99)."},"valid":{"type":"boolean","description":"The checksum holds: a possible number, not proof that the person exists."},"reasons":{"type":"array","items":{"enum":["not_digits","length","leading_zero","checksum"],"type":"string"}}}},"HistoryParameter":{"type":"object","required":["id","unit","description"],"properties":{"id":{"type":"string"},"unit":{"type":"string"},"description":{"type":"string"}}}},"responses":{"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 credential","status":502}},"upstream_error":{"value":{"type":"https://servicebox.io/problems/upstream_error","title":"Bad Gateway","detail":"The upstream failed (500)","status":502}}}}},"description":"`upstream_error`: the data source failed. `upstream_auth`: the data source refused ServiceBox's own credential; not your key."},"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":"Upstream request timed out","status":504}}},"description":"The 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."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyQuery":{"in":"query","name":"apikey","type":"apiKey"}}}}