Series ids and units¶

A series id names one time series, such as the Bank of Russia key rate or Türkiye's monthly exports to Russia. Ids are used in GET /v1/latest?ids=..., GET /v1/series/{id} and the MCP tools latest and get_series.

Ids are lowercase and case-sensitive. An id that does not exist is not an error: GET /v1/series/{id} returns 200 with an empty rows list and /v1/latest leaves it out (FAQ).

Naming convention¶

Ids are dot-separated, from general to specific:

<economy>.<topic>[.<sub-topic> ...][.<unit or variant>]

Part	Values seen	Examples
Economy prefix	`tr` (Türkiye), `ru` (Russia), `eu` (EU gas entry points), `xm` (euro area, ECB), `us`, `cn`	`tr.cpi`, `ru.key_rate`, `eu.entsog.kipi_tr_gr.mcm_d`
Topic	`fx`, `cpi`, `exports_to`, `imports_from`, `gas_imports`, `reserves`, `visitors`, `budget`, ...	`ru.fx.usdrub`
Source tag (sometimes)	Where two publishers cover the same thing, or a source has many series, the source is part of the id: `tuik`, `rosstat`, `thy`, `dhmi`, `straits`, `sberindex`, `entsog`, `mirror`	`tr.tuik.exports_to.ru.usd`, `ru.rosstat.cpi.yoy_pct`
Partner or region	Lowercase ISO 3166 alpha-2 code, or a lowercase name for provinces and regions	`ru`, `kz`, `antalya`, `europe`
Unit or variant suffix	`usd`, `usd_bn`, `rub_bn`, `mcm`, `tonnes`, `pct`, `yoy_pct`, `mom_pct`, `share_pct`, `count`, `passengers`	`tr.exports_to.ru.usd`

Direction is part of the name: exports_to.<partner> is Türkiye's exports to that partner; imports_from.<partner> is imports from it. Under ru.mirror.imports_from.<country> the direction is Russia's imports, measured from the exporting country's side (mirror data).

Series families you will meet:

Prefix	What it is	Count
`tr.house_sales.foreign.*`	House sales to foreigners by nationality and province	181
`ru.sberindex.*`	SberIndex consumer spending, business turnover, prices, labour	98
`tr.straits.*`	Bosphorus and Dardanelles ship transits	72
`tr.dhmi.*`	Airport passengers, flights and cargo	63
`tr.tuik.*`	TÜİK general trade system, by partner	28
`ru.trade_ccy.*`	Currency shares in Russia's foreign-trade settlements	22
`tr.thy.*`	Turkish Airlines traffic	22
`tr.foreign_cos.*`	Foreign-capital companies founded in Türkiye (TOBB)	17
`tr.exports_to.*`	Türkiye's exports by partner, TİM consolidated	13
`ru.mirror.*`	Russia's imports by origin, mirror data	13
`tr.gas_imports.`, `tr.oil_imports.`, `tr.imports_from_ru.*`	Energy imports (EPDK, CREA)	13, 16, 11

Discovering ids¶

GET /v1/series lists series metadata. It matches search against the id and the Turkish and English names, case-insensitively, and can be narrowed by country (ISO-2, such as TR, RU) and category.

Parameter	Type	Default	Meaning
`search`	string	empty	Substring of the id, the Turkish name or the English name
`country`	string	empty	Economy code, `TR`, `RU`, `EU`, `US`, `CN` (case-insensitive)
`category`	string	empty	Exact category, lowercase: `rates`, `fx`, `prices`, `expectations`, `reserves`, `markets`, `trade`, `energy`, `tourism`, `transport`, `aviation`, `real_estate`, `companies`, `consumption`, `business`, `fiscal`, `macro`, `payments`, `labour`, `construction`, `activity`, `external`, `logistics`

curlPythonJavaScript

curl -H "Authorization: Bearer $TRRU_KEY" \
  "https://trru.atapinar.com/v1/series?search=key%20rate&country=RU"

import os, requests

resp = requests.get(
    "https://trru.atapinar.com/v1/series",
    params={"search": "exports_to.ru", "country": "TR"},
    headers={"Authorization": f"Bearer {os.environ['TRRU_KEY']}"},
    timeout=30,
)
for s in resp.json()["data"]["rows"]:
    print(s["series_id"], s["unit"], s["frequency"], s["first_obs"], s["last_obs"])

const url = new URL("https://trru.atapinar.com/v1/series");
url.search = new URLSearchParams({ search: "exports_to.ru", country: "TR" });
const resp = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TRRU_KEY}` } });
for (const s of (await resp.json()).data.rows) console.log(s.series_id, s.unit, s.first_obs, s.last_obs);

Tips:

search is a substring match, so one word is better than a phrase. A real call, search=policy rate&country=RU, finds only ru.policy_rate_bis, not ru.key_rate, whose English name is "Bank of Russia key rate". Try key rate, or search by the id fragment key_rate.
With no filters the call returns all 693 series (under the 2000-row cap), about 230 KB. Cache it or filter.
Names are in Turkish (name_tr) and English (name_en).

Reading series metadata¶

A real response (GET /v1/series?search=policy%20rate&country=RU):

{
  "data": {
    "rows": [
      {
        "series_id": "ru.policy_rate_bis",
        "name_tr": "Rusya MB politika faizi (BIS, aylık)",
        "name_en": "Bank of Russia policy rate (BIS, monthly)",
        "unit": "%",
        "frequency": "monthly",
        "country": "RU",
        "category": "rates",
        "first_obs": "2015-01-01",
        "last_obs": "2026-09-01",
        "source_id": "evds"
      }
    ],
    "row_count": 1,
    "truncated": false
  },
  "meta": {
    "sources": [
      {"source_id": "evds", "fetched_at": "2026-11-13T17:30:29.379365+00:00", "as_of": "2026-09-01"}
    ],
    "request_id": "469f72f2464243f7856b5e1a4edb6828",
    "truncated": false
  }
}

Field	Type	Meaning
`series_id`	string	The id to use in other calls
`name_tr`, `name_en`	string	Human-readable names
`unit`	string	Unit of the value: `%`, `USD`, `USD bn`, `RUB bn`, `RUB per USD`, `TRY per USD`, `persons`, `count`, `index`, `tonnes`, `million Sm3` ... Read it before comparing series.
`frequency`	string	`daily`, `weekly`, `monthly`, `quarterly` or `annual`
`country`	string	Economy code of the series
`category`	string	Topic group, for filtering
`first_obs`, `last_obs`	date	First and last observation date in the store
`source_id`	string	Which source feeds it; see Coverage and freshness

How dates behave:

Daily series have no rows on days the publisher is closed.
Monthly, quarterly and annual observations are dated on the first day of the period: 2026-10-01 is October 2026; quarterly 2026-04-01 is the second quarter.
Weekly series use the date the publisher gives for the week.
Stock figures, such as ru.reserves.*, are stocks on the first day of the month.

Twenty useful ids¶

Verified against the live API on 2026-11-13. "Latest" is the value returned by GET /v1/latest at that time and the date it is for; it will have moved by the time you read this.

Series id	Meaning	Unit	Freq.	Starts	Latest
`ru.key_rate`	Bank of Russia key rate	%	daily	2015-01-12	14.0 (2026-11-13)
`ru.ruonia`	RUONIA overnight rate	%	daily	2015-01-12	13.92 (2026-11-12)
`tr.policy_rate`	CBRT policy rate (BIS monthly series)	%	monthly	2015-01-01	37.0 (2026-09-01)
`tr.aofm`	CBRT weighted average funding cost	%	daily	2015-01-02	36.0 (2026-11-13)
`ru.fx.usdrub`	USD/RUB, CBR official rate	RUB per USD	daily	2015-01-01	82.9803 (2026-11-13)
`ru.fx.tryrub`	TRY/RUB, CBR official rate	RUB per TRY	daily	2015-01-01	1.65355 (2026-11-13)
`tr.fx.usdtry`	USD/TRY, CBRT buying rate	TRY per USD	daily	2015-10-30	50.1691 (2026-11-13)
`tr.fx.rubtry`	RUB/TRY, CBRT buying rate	TRY per RUB	daily	2015-10-30	0.60298 (2026-11-13)
`ru.mkt.imoex`	MOEX Russia Index	index	daily	2015-01-05	2505.95 (2026-11-12)
`ru.rosstat.cpi.yoy_pct`	Russia CPI, year on year	%	monthly	2015-01-01	6.35 (2026-09-01)
`tr.cpi`	Türkiye CPI headline index (2003=100)	index	monthly	2015-01-01	4481.04 (2026-10-01)
`tr.exports_to.ru.usd`	Türkiye exports to Russia, TİM consolidated	USD	monthly	2011-02-01	457,415,414.52 (2026-10-01)
`tr.tuik.exports_to.ru.usd`	Türkiye exports to Russia, TÜİK	USD	monthly	2013-01-01	532,932,147 (2026-09-01)
`tr.tuik.imports_from.ru.usd`	Türkiye imports from Russia, TÜİK	USD	monthly	2013-01-01	1,847,917,103 (2026-09-01)
`tr.visitors.ru`	Russian visitors to Türkiye (TCMB/EVDS)	persons	monthly	2015-01-01	945,784 (2026-09-01)
`tr.border.arrivals.ru`	Russian arrivals at the border (KTB border statistics)	persons	monthly	2016-01-01	979,647 (2026-09-01)
`tr.gas_imports.ru.mcm`	Türkiye natural gas imports from Russia (EPDK)	million Sm3	monthly	2014-01-01	967.76 (2026-09-01)
`tr.imports_from_ru.crude_oil.usd`	Türkiye imports of Russian crude oil (CREA)	USD	monthly	2021-01-01	270,141,611.89 (2026-10-01)
`ru.reserves.total.usd_bn`	Bank of Russia international reserves, total	USD bn	monthly	2000-01-01	720.912 (2026-11-01)
`ru.urals.usd_bbl`	Urals crude price, monthly average for the tax base	USD/bbl	monthly	2003-02-01	101.46 (2026-10-01)

Other series worth knowing: ru.mirror.imports_from.cn.usd (China's exports to Russia, monthly mirror), ru.trade_ccy.imports.rub_share_pct (share of the ruble in Russia's import settlements), eu.entsog.turkstream_strandzha2.mcm_d (daily gas flow through TurkStream's Strandzha 2 entry), tr.house_sales.foreign.ru (house sales to Russian citizens), tr.thy.total.passengers (Turkish Airlines passengers).

Note

Two series can look like the same thing and differ: tr.visitors.ru (945,784 for September 2026) and tr.border.arrivals.ru (979,647 for the same month) come from different publishers with different definitions; tr.exports_to.ru.usd (TİM) and tr.tuik.exports_to.ru.usd (TÜİK) likewise. Pick one and stay with it; see the FAQ.

Reading observations and resampling¶

curl -H "Authorization: Bearer $TRRU_KEY" \
  "https://trru.atapinar.com/v1/series/ru.key_rate?start=2026-01-01&resample=month"

GET /v1/series/{series_id}:

Parameter	Type	Default	Meaning
`series_id`	path, string	required	Exactly one series id
`start`	date `YYYY-MM-DD`	none	First date, inclusive
`end`	date `YYYY-MM-DD`	none	Last date, inclusive
`resample`	string	empty (raw)	`week`, `month`, `quarter` or `year`. Any other value returns `400`.

Rows are in long format, oldest first, at most 2000 per call. With no start, a long daily series is cut off after the oldest 2000 rows and flagged truncated: true (Responses and sources).

With resample, you get one row per period holding the last observation inside that period. Real rows:

{
  "rows": [
    {"series_id": "ru.key_rate", "period": "2026-01-01", "obs_date": "2026-01-30", "value": 16.0},
    {"series_id": "ru.key_rate", "period": "2026-02-01", "obs_date": "2026-02-27", "value": 15.5}
  ]
}

(Two of the eleven rows returned; the rest is omitted.)

period is the first day of the week (Monday), month, quarter or year; obs_date is the date of the observation that was picked.
Resampling takes the last value, not the average and not the sum. For a stock or a rate (key rate, reserves, exchange rate at period end) that is what you want. For a flow (monthly exports in USD), resample=quarter returns the last month of the quarter, not the quarterly total. Fetch the monthly rows and sum them yourself.
The current, incomplete period is included; its row holds the latest value so far.
resample can be combined with start and end; the window is applied before resampling.