If you need Turkish lira exchange rates, there are plenty of commercial APIs that will sell them to you. For anything touching Turkish accounting, invoicing or reporting, though, the source that matters is the Central Bank of the Republic of Türkiye — TCMB — because its rates are the official reference used for those purposes.
TCMB publishes two things that are useful to developers, and they solve different problems. This guide covers both, plus the handful of details that cause most of the bugs.
Two sources, two purposes
| Source | What it gives | Auth | Use it for |
|---|---|---|---|
| Daily XML feed | One day's rates for all listed currencies | None | Current rates, simple lookups |
| EVDS | Full historical time series | Free API key | Charts, analysis, historical lookups |
The daily XML feed is the simplest possible integration: a single file, no key, no registration. EVDS is the Electronic Data Delivery System, a much broader statistical service that covers a wide range of Turkish economic indicators, of which exchange rates are one.
The rule of thumb: if you need today's rate, use the XML feed. If you need any date other than today, or a series of dates, use EVDS.
The daily XML feed
The feed publishes the current day's rates in XML. For each currency you get several values rather than one number, and understanding them is the first thing to get right.
Rates are published as buying and selling pairs, and separately for cash transactions versus transfers. That gives four values per currency, and they are not interchangeable. Which one applies depends on the nature of the transaction, and for accounting purposes it is determined by regulation and policy rather than by preference.
This is worth escalating rather than deciding alone. A developer picking whichever field looks reasonable introduces a small systematic error into every converted amount, and small systematic errors in financial data are found late and are unpleasant to correct. Ask your finance team which rate applies to your use case and record the answer in your code as a comment.
Note also that cash rates may be absent for some currencies. Code that assumes every field is populated will fail on those entries.
EVDS for historical data
EVDS requires free registration and an API key. In exchange you get access to time series across a wide range of Turkish economic statistics — exchange rates, inflation, interest rates and much more.
For exchange rate work, the important capability is querying a date range and getting back a series. This is what you need for a chart, a historical conversion, or any report that covers a period rather than a moment.
Two things about EVDS commonly surprise first-time users.
The first is that series are identified by codes rather than friendly names, and you need the right code for the right series. Currency, buying versus selling, and frequency are all encoded in the identifier. Look these up through the portal's series browser rather than guessing, and store the codes you use as named constants — an undocumented code string in a query is unmaintainable six months later.
The second is aggregation. EVDS can return daily, weekly, monthly or annual frequencies, and it can aggregate using different methods — average, end of period, and others. A monthly series using average and one using end-of-period produce different numbers, both correct. Be explicit about which you want, and label it wherever the number is displayed.
The weekend problem
This is the bug that appears in almost every first implementation.
TCMB publishes on business days. There is no publication on weekends or public holidays, and on publishing days rates are announced at a set time — request earlier in the day and the current file may still hold the previous day's values.
So "get today's rate" is not a reliable operation. Sometimes there is no today's rate.
Handle it by asking a different question: get the most recent published rate on or before a given date. Walk backwards from the target date until you find a publication, with a sensible limit — a week is more than enough to cover any holiday period — and fail loudly if you exceed it rather than looping indefinitely.
Then, crucially, record which date the rate you used actually came from. If a transaction on Sunday uses Friday's rate, your records should say so. Storing the amount without the rate date makes later reconciliation impossible.
Turkish public holidays include religious holidays that follow the lunar calendar and therefore move each year, so a hard-coded holiday list will silently go stale. Deriving non-publication days from the data itself — if there is no publication, there was no business day — is more robust than maintaining a calendar.
Precision and rounding
Financial conversion is one of the few places where floating point arithmetic will genuinely cost you money.
Use a decimal type rather than a float for both rates and amounts. In JavaScript, that means a decimal library rather than native numbers. The error from float arithmetic is tiny per operation and entirely invisible until totals across thousands of rows fail to reconcile by a few kuruş.
Decide rounding rules once and apply them consistently: how many decimal places, and rounded at which step. Rounding the rate before multiplying gives a different answer than rounding the result, and both may be defensible — but they must not be mixed within one system.
Store the rate you used alongside every converted amount, not just the result. When someone asks why an invoice shows a particular lira figure, the answer must be reconstructable from your records rather than by re-fetching a rate that may since have been revised.
Caching and rate limits
Published rates for a past date never change, which makes this an unusually cache-friendly dataset. Historical values can be cached indefinitely.
Cache aggressively and permanently by currency and date. The only value that needs periodic refreshing is the current day's, and only until the day's publication has happened.
Do not call TCMB on every user request. A conversion feature on a busy page can generate a large volume of identical requests for the same daily file, which is wasteful and inconsiderate toward a public service. Fetch once per publication, store, and serve from your own data.
For EVDS, request the date range you need in a single call rather than looping day by day. Asking for a year of daily rates is one request; asking for each day separately is 365 and will run into limits.
Which rates are published
TCMB publishes rates for a defined set of currencies against the lira. Widely traded currencies are covered; more obscure ones may not be.
If you need a pair that TCMB does not publish, you have two options. Cross-calculate through the lira using two published rates, accepting that the result is derived rather than official. Or use a commercial provider for that pair, accepting that it is not the official reference.
Be explicit in your interface about which is which. A rate labelled as coming from the central bank should genuinely come from there.
For general-purpose currency conversion where official Turkish rates are not a requirement, other providers may be simpler — we cover building a converter end to end in build a currency converter with a free exchange rate API.
A note on scope
TCMB rates are reference rates. They are not the rate you will get from a bank or an exchange bureau, which apply their own spreads.
If your application shows users what they will actually pay, TCMB rates alone will not be accurate and the difference will be noticed. If your application produces accounting records, reports or invoices, TCMB is the right source precisely because it is the official reference.
Being clear about which of these you are doing determines the whole design, and it is worth settling before writing code.
Endpoints and service behaviour in this article reflect the official sources at the time of publication. Verify current behaviour against TCMB's own documentation before relying on it in production.
Related API Deposu entries
Sources
Frequently Asked Questions
›Is the TCMB exchange rate data free?
The daily rates are published publicly as an XML file with no key required. The EVDS time series service is also free but requires registration and an API key.
›Which rate should I use — buying or selling?
It depends on the direction of the transaction from the bank's perspective, and getting it wrong produces small but systematic errors. For accounting and reporting, the applicable rate is determined by regulation and accounting policy, so confirm with your finance team rather than picking one.
›Why is there no rate for today?
TCMB publishes on business days only. Weekends and public holidays have no publication, and the rate is announced at a set time on publishing days, so requesting before that returns the previous day. Your code must fall back to the most recent published date rather than failing.
›What is the difference between the XML feed and EVDS?
The XML feed gives you one day's rates and is the simplest way to get current values. EVDS is a full time series service covering historical data across many economic indicators, and is what you need for charts, analysis or any historical lookup.
›Can I use these rates for invoicing?
TCMB rates are the official reference for many Turkish accounting and tax purposes, which is why they are commonly used. The specific rate and date that apply to a given transaction are determined by regulation, so treat this as a finance question rather than a technical one.