Exchange Rates – REST API (Version 1.

0)
The new basic domain for A2A services is:
https://tassidicambio.bancaditalia.it/terzevalute-wf-web/rest/v1.0

For the sake of brevity, the basic domain is omitted from the description of the URLs.
So, for example, instead of writing
GET https://tassidicambio.bancaditalia.it/terzevalute-wf-web/rest/v1.0/currencies
we will simply write GET /currencies

Or instead of writing
GET https://tassidicambio.bancaditalia.it/terzevalute-wf-web/rest/v1.0/latestRates?lang={}
we will simply write GET /latestRates?lang={}

The repeatable input parameters will be indicated in the URL in square brackets, for exeample:
GET /dailyRates?referenceDate={}[&baseCurrencyIsoCode={}]&currencyIsoCode={}&lang={}

Latest Rates
It provides the exchange rates, against the euro and the US dollar, on the latest day for which there are
quotations available for all the currencies quoted in the database.
GET /latestRates?lang={}

Media types
The result is available in the following formats: json, pdf, csv, Excel, depending on the HTTP Accept header
parameter:
• Accept: application/json

• Accept: application/pdf

• Accept: text/csv

• Accept: application/vnd.ms-excel

Input Parameters
Name Required Description
lang No The language in which you want the data: "it" or "en" may be used (case insensitive).
If the parameter is not specified or is incorrectly spelled, the results will be provided in the
default language.

http response codes:

200 OK
500 Internal Server Error
503 Service Unavailable
400 Bad Request
408 Request Timeout
404 Not Found

1
Examples of responses:

Content Type: application/json

{
"resultsInfo":
{
"totalRecords": 2,
"timezoneReference": "Dates refer to the Central European Time Zone",
"notice": "Foreign currency amount for 1 euro " },
"latestRates":
[
{
"country": "ALBANIA",
"currency": "Lek",
"isoCode": "ALL",
"uicCode": "047",
"eurRate": "0.0089",
"usdRate": "0.0089",
"usdExchangeConvention": "Foreign currency amount for 1 dollar",
"usdExchangeConventionCode": "C",
"referenceDate": "2017-09-06"
},
{
"country": "ALGERIA",
"currency": "Algerian Dinar",
"isoCode": "DZD",
"uicCode": "106",
"eurRate": "1.0000",
"usdRate": "1.0000",
"usdExchangeConvention": "Foreign currency amount for 1 dollar",
"usdExchangeConventionCode": "C",
"referenceDate": "2017-09-06"
}
]
}

Content Type: text/csv

Filename: latest_rates_yyyyMMdd.csv

Country,Currency,ISO Code,UIC Code,Euro,US dollar,Rate convention against Dollar,Rate convention against Euro,Reference date (CET)
AFGHANISTAN (Islamic State of),Afghani,AFN,115,79.6447,68.3939,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro ,2017-
11-02
ALBANIA,Lek,ALL,047,133.59,114.72,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro ,2017-11-02
ALGERIA,Algerian Dinar,DZD,106,134.1344,115.1863,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro ,2017-11-02
ANGOLA,Adjusted Kwanza,AOA,087,193.132,165.850,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro ,2017-11-02
ANTIGUA AND BARBUDA,East Caribbean Dollar,XCD,137,3.1442,2.70,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro
,2017-11-02

2
Daily Exchange Rates
It provides daily exchange rates for a specific date, against the euro, the US dollar or the Italian lira, for one
or more requested currencies, which are valid and for which the rates for the selected date are available. If
no currency is specified, the service will return all the available currencies. If there are no quotations for the
date and currencies selected, the service will return an empty list with an information message.
GET /dailyRates?referenceDate={}[&baseCurrencyIsoCode={}]&currencyIsoCode={}&lang={}

Media types
The result is available in the following formats: json, pdf, csv, Excel, depending on the HTTP Accept header
parameter:
• Accept: application/json

• Accept: application/pdf

• Accept: text/csv

• Accept: application/vnd.ms-excel

Input Parameters
Name Required Repeatable Description
referenceDate Yes No Quotation date. It is represented in relation to the Central European Time
Zone in the format "yyyy-MM-dd".
If the parameter is not specified or is specified incorrectly, the service will
return a message with the required format.
baseCurrencyIsoCode No Yes The ISO code for the currency for which you want the exchange rate (case
insensitive). In the case of multiple currencies, the parameter must be
repeated. If the parameter is not specified, all the currencies for which the
rate is available on the requested date will be returned. ISO codes that do
not exist will be discarded. If none of the ISO codes inserted exist, an empty
list will be shown.
For ISO codes specified incorrectly, the service will return an error message.
currencyIsoCode Yes No The currency ISO code (case insensitive) against which you want the rates.
It can be "EUR", "USD" or "ITL". If the parameter is not specified, or the
value is not valid, the service will return an error message.
lang No No The language in which you want the data: it can be "it" or "en" (case
insensitive).
If the parameter is not specified, or the value is incorrect, the results will be
provided in the default language.

http response codes:

200 OK
500 Internal Server Error
503 Service Unavailable
400 Bad Request
408 Request Timeout
404 Not Found

3
Example of a response:

Content Type: application/json

{
"resultsInfo":
{
"totalRecords": 1,
"timezoneReference": "Dates refer to the Central European Time Zone"
},
"rates":
[
{
"country": "UNITED ARAB EMIRATES",
"currency": "U.A.E. Dirham",
"isoCode": "AED",
"uicCode": "187",
"avgRate": "4.13942",
"exchangeConvention": "Foreign currency amount for 1 Euro ",
"exchangeConventionCode": "I",
"referenceDate": "2016-08-17"
}
]
}

Content Type: text/csv

Filename: daily_rates_yyyyMM.csv

Country,Currency,ISO Code,UIC Code,Rate,Rate convention,Reference date (CET)

AFGHANISTAN (Islamic State of),Afghani,AFN,115,76.042074,Foreign currency amount for 1 Euro ,2016-08-17
ALBANIA,Lek,ALL,047,136.262894,Foreign currency amount for 1 Euro ,2016-08-17
ALGERIA,Algerian Dinar,DZD,106,122.767026,Foreign currency amount for 1 Euro ,2016-08-17
ANGOLA,Adjusted Kwanza,AOA,087,188.250565,Foreign currency amount for 1 Euro ,2016-08-17
ANTIGUA AND BARBUDA,East Caribbean Dollar,XCD,137,3.04452,Foreign currency amount for 1 Euro ,2016-08-17

4
Average Monthly Exchange Rates
It provides average monthly exchange rates for a specific month/year, against the euro, the US dollar or the
Italian lira, for one or more valid currencies, and for which the rates are available. If there are no quotations
for the month and currencies selected, the service will return an empty list.
GET /monthlyAverageRates?month={}&year={}[&baseCurrencyIsoCode={}]&currencyIsoCode
={}&lang={}

Media types
The result is available in the following formats: json, pdf, csv, Excel, depending on the HTTP Accept header
parameter:
• Accept: application/json

• Accept: application/pdf

• Accept: text/csv

• Accept: application/vnd.ms-excel

Input Parameters
Name Required Repeatable Description
month Yes No Quotation month. Must be an integer between 1 and 12.
If the parameter is not specified or the value is incorrect, the
service will return an http 400 error and a message with the
required format, i.e. an integer between 1 and 12.
year Yes No Quotation year. Must be a 4-digit integer in the YYYY format.
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
If there are no rates for the month/year pair, the service will
return an empty list.
baseCurrencyIsoCode No Yes The currency ISO code for which you want the exchange rate
(case insensitive). In the case of multiple currencies, the
parameter must be repeated. If the parameter is not specified,
all the currencies for which the rate is available on the
requested date will be returned. ISO codes that do not exist will
be discarded. If none of the ISO insert codes exist, an empty list
will be returned.
For ISO codes specified incorrectly, the service will return an
error message.
currencyIsoCode Yes No The ISO code of the currency against which you want the rates.
It can be "EUR", "USD" or "ITL". If the parameter is not specified,
or the value is not valid, the service will return an error
message.
lang No No The language in which you want the data: it can be "it" or "en"
(case insensitive).
If the parameter is not specified, or the value is not valid, the
results will be provided in the default language.

5
http response codes:
200 OK
500 Internal Server Error
503 Service Unavailable
400 Bad Request
408 Request Timeout
404 Not Found

Examples of responses:

Content Type: application/json

{
"resultsInfo":
{
"totalRecords": 2
},
"rates":
[
{
"country": "ALBANIA",
"currency": "Lek",
"isoCode": "ALL",
"uicCode": "047",
"avgRate": "140",
"exchangeConvention": "Foreign currency amount for 1 Euro ",
"exchangeConventionCode": "I",
"year": 2016,
"month": 9
},
{
"country": "ALGERIA",
"currency": "Algerian Dinar",
"isoCode": "DZD",
"uicCode": "106",
"avgRate": "122.522",
"exchangeConvention": "Foreign currency amount for 1 Euro ",
"exchangeConventionCode": "I",
"year": 2016,
"month": 9
}
]
}

Content Type: text/csv

Filename: monthly_average_rates_yyyyMM.csv

Country,Currency,ISO Code,UIC Code,Average Rate,Rate convention,Year,Month

AFGHANISTAN (Islamic State of),Afghani,AFN,115,75.4016,Foreign currency amount for 1 Euro ,2016,8
ALBANIA,Lek,ALL,047,136.547,Foreign currency amount for 1 Euro ,2016,8
ALGERIA,Algerian Dinar,DZD,106,122.679,Foreign currency amount for 1 Euro ,2016,8
ANGOLA,Adjusted Kwanza,AOA,087,186.922,Foreign currency amount for 1 Euro ,2016,8
ANTIGUA AND BARBUDA,East Caribbean Dollar,XCD,137,3.02717,Foreign currency amount for 1 Euro ,2016,8

6
Annual Average Exchange Rates
It provides the annual average rates, against the euro, the US dollar or the Italian lira, for one or more
requested currencies, which are valid and for which the rates for the selected month are available. If no
currency is specified, the service will return all the available currency rates. If there are no quotations for
the year and currencies selected, the service will return an empty list.
GET /annualAverageRates?year={}&[baseCurrencyIsoCode={}]&currencyIsoCode={}&lang={}

Media types
The result is available in the following formats: json, pdf, csv, Excel, depending on the HTTP Accept header
parameter:
• Accept: application/json

• Accept: application/pdf

• Accept: text/csv

• Accept: application/vnd.ms-excel

Input Parameters
Name Required Repeatable Description
year Yes No Quotation year. Must be a 4-digit integer in the YYYY format.
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
If there are no rates available for the year, the service will
return an empty list.
baseCurrencyIsoCode No Yes The ISO code for the currency for which you want the exchange
rate (case insensitive). In the case of multiple currencies, the
parameter must be repeated. If the parameter is not specified,
all the currencies for which the rate is available on the
requested date will be returned. ISO codes that do not exist will
be discarded. If none of the ISO insert codes exist, an empty list
will be returned.
For ISO codes specified incorrectly, the service will return an
error message.
currencyIsoCode Yes No The ISO code of the currency against which you want the rates
(case insensitive). It can be "EUR", "USD" or "ITL". If the
parameter is not specified, or the value is not valid, the service
will return an error message.
lang No No The language in which you want the data: it can be "it" or "en"
(case insensitive).
If the parameter is not specified, or the value is not valid, the
results will be provided in the default language.

http response codes:

200 OK
500 Internal Server Error
503 Service Unavailable
400 Bad Request
408 Request Timeout
404 Not Found

7
Examples of responses:

Content Type: application/json

{
"resultsInfo":
{
"totalRecords": 2
},
"rates":
[
{
"country": "ALBANIA",
"currency": "Lek",
"isoCode": "ALL",
"uicCode": "047",
"avgRate": "140",
"exchangeConvention": "Foreign currency amount for 1 Euro ",
"exchangeConventionCode": "I",
"year": 2016
},
{
"country": "ALGERIA",
"currency": "Algerian Dinar",
"isoCode": "DZD",
"uicCode": "106",
"avgRate": "122.522",
"exchangeConvention": "Foreign currency amount for 1 Euro ",
"exchangeConventionCode": "I",
"year": 2016
}
]
}

Content Type: text/csv

Filename: annual_average_rates_yyyy.csv

Country,Currency,ISO Code,UIC Code,Rate,Rate convention,Year

AFGHANISTAN (Islamic State of),Afghani,AFN,115,75.074,Foreign currency amount for 1 Euro ,2016
ALBANIA,Lek,ALL,047,137.317,Foreign currency amount for 1 Euro ,2016
ALGERIA,Algerian Dinar,DZD,106,121.097,Foreign currency amount for 1 Euro ,2016
ANGOLA,Adjusted Kwanza,AOA,087,182.079,Foreign currency amount for 1 Euro ,2016
ANTIGUA AND BARBUDA,East Caribbean Dollar,XCD,137,2.98864,Foreign currency amount for 1 Euro ,2016

8
Daily Exchange rates - Time Series
It provides daily exchange rates for a currency with reference to a specific date range. The foreign currency
may be the euro, the US dollar or the Italian lira. If no rate is available for the range provided, the service
will return an empty list. The end date may not be earlier than the start date, otherwise the service will
return an error message.

Queries can be made about historical data from 1918 onwards.

GET /dailyTimeSeries?startDate={}&endDate={}&baseCurrencyIsoCode={}&currencyIsoCode
={}&lang={}

Media types
The result is available in the following formats: json, pdf, csv, Excel, depending on the HTTP Accept header
parameter:
• Accept: application/json

• Accept: application/pdf

• Accept: text/csv

• Accept: application/vnd.ms-excel

Input Parameters
Name Required Repeatable Description
startDate Yes No Quotation start date. It is represented in relation to the Central
European Time Zone in the format "yyyy-MM-dd".
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
endDate Yes No Quotation end date. It is represented in relation to the Central
European Time Zone in the format "yyyy-MM-dd".
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
baseCurrencyIsoCode Yes No The ISO code for the currency for which you want the exchange
rate (case insensitive). If the ISO insert code does not exist, an
empty list will be returned.
If the parameter is specified incorrectly, the service will return
an error message.
currencyIsoCode Yes No The ISO code (case insensitive) for the currency against which
you want the rates. It can be "EUR", "USD" or "ITL". If the
parameter is not specified, or the value specified is not valid,
the service will return an error message.
lang No No The language in which you want the data: it can be "it" or "en"
(case insensitive).
If the parameter is not specified, or the value is incorrect, the
results will be provided in the default language.

http response codes:

200 OK
500 Internal Server Error
503 Service Unavailable
400 Bad Request
408 Request Timeout
404 Not Found

9
Examples of responses:

Content Type: application/json

{
"resultsInfo":
{
"totalRecords": 2,
"timezoneReference": "Dates refer to the Central European Time Zone",
"currency": "Lek",
"isoCode": "ALL",
"uicCode": "047",
"exchangeConventionCode": "I"
},
"rates":
[
{
"referenceDate": "2016-05-02",
"avgRate": "138.812",
"exchangeConvention": "Foreign currency amount for 1 Euro "
},
{
"referenceDate": "2016-05-03",
"avgRate": "138.349",
"exchangeConvention": "Foreign currency amount for 1 Euro "
}
]
}

Content Type: text/csv

Filename: <baseCurrencyIsoCode>_daily_time_series.csv

Currency,ISO Code,UIC Code,Rate,Rate convention,Reference date (CET)

Lek,ALL,047,125.868534,Foreign currency amount for 1 Dollar,2015-05-04
Lek,ALL,047,126.011245,Foreign currency amount for 1 Dollar,2015-05-05
Lek,ALL,047,124.50872,Foreign currency amount for 1 Dollar,2015-05-06
Lek,ALL,047,124.33535,Foreign currency amount for 1 Dollar,2015-05-07

10
Monthly Exchange rates - Time Series
It provides monthly exchange rates for a currency for a specific month range. The foreign currency may be
the euro, the US dollar or the Italian lira. If no rate is available for the range provided, the service will return
an empty list. The start month/year pair must not be after the end month/year pair, otherwise the service
will return an error message.

Queries can be made about historical data from 1918 onwards.

GET
/monthlyTimeSeries?startMonth={}&startYear={}&endMonth={}&endYear={}&baseCurrencyIsoCode=
{}&currencyIsoCode={}&lang={}

Media types
The result is available in the following formats: json, pdf, csv, Excel, depending on the HTTP Accept header
parameter:
• Accept: application/json

• Accept: application/pdf

• Accept: text/csv

• Accept: application/vnd.ms-excel

Input Parameters
Name Required Repeatable Description
startMonth Yes No Quotation start month. Must be an integer between 1 and 12.
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
startYear Yes No Quotation start year. Must be a 4-digit integer in the YYYY
format.
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
endMonth Yes No Quotation end month.. Must be an integer between 1 and 12.
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
endYear Yes No Quotation end year. Must be a 4-digit integer in the YYYY
format.
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
If the endMonth/endYear comes before the
startMonth/startYear the service will return an error message.
baseCurrencyIsoCode Yes No The ISO code for the currency for which you want the exchange
rate (case insensitive). If the ISO insert code does not exist, an
empty list will be returned.
If the parameter is specified incorrectly, the service will return
an error message.
currencyIsoCode Yes No The ISO code of the currency against which you want the rates.
It can be "EUR", "USD" or "ITL". If the parameter is not specified,
or the value is not valid, the service will return an error
message.
lang No No The language in which you want the data: it can be "it" or "en"
(case insensitive).
If the parameter is not specified, or the value is not valid, the
results will be provided in the default language.

11
http response codes:
200 OK
500 Internal Server Error
503 Service Unavailable
400 Bad Request
408 Request Timeout
404 Not Found

Examples of responses:

Content Type: application/json

{
"resultsInfo":
{
"totalRecords": 3,
"currency": "Lek",
"isoCode": "ALL",
"uicCode": "047",
"exchangeConventionCode": "I"
},
"rates":
[
{
"referenceDate": "2015-11",
"avgRate": "138.123",
"exchangeConvention": "Foreign currency amount for 1 Euro "
},
{
"referenceDate": "2015-12",
"avgRate": "137.585",
"exchangeConvention": "Foreign currency amount for 1 Euro "
},
{
"referenceDate": "2016-01",
"avgRate": "138.21",
"exchangeConvention": "Foreign currency amount for 1 Euro "
}
]
}

Content Type: text/csv

Filename: <baseCurrencyIsoCode>_monthly_time_series.csv

Currency,ISO Code,UIC Code,Rate,Rate convention,Reference date (CET)

Lek,ALL,047,128.6655,Foreign currency amount for 1 Dollar,2015-11
Lek,ALL,047,126.5039,Foreign currency amount for 1 Dollar,2015-12
Lek,ALL,047,127.2700,Foreign currency amount for 1 Dollar,2016-01

12
Annual Average Exchange Rates - Time Series
It provides annual average exchange rates for a currency and for a specific year range. The foreign currency
may be the euro, the US dollar or the Italian lira. If no rate is available for the range provided, the service
will return an empty list. The start year must not be after the end year, otherwise the service will return an
error message.

It is possible to make queries about historical data from 1918 onwards.

GET /annualTimeSeries?startYear={}&endYear={}&baseCurrencyIsoCode={}&currencyIsoCode
={}&lang={}

Media types
The result is available in the following formats: json, pdf, csv, Excel, depending on the HTTP Accept header
parameter:
• Accept: application/json

• Accept: application/pdf

• Accept: text/csv

• Accept: application/vnd.ms-excel

Input Parameters
Name Required Repeatable Description
startYear Yes No Quotation start year. Must be a 4-digit integer in the YYYY
format.
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
endYear Yes No Quotation end year. Must be a 4-digit integer in the YYYY
format.
If the parameter is not specified or is specified incorrectly, the
service will return a message with the required format.
If the endYear comes before the startYear, the service will
return an error message.
baseCurrencyIsoCode Yes No The ISO code for the currency for which you want the exchange
rate (case insensitive). If the ISO insert code does not exist, an
empty list will be returned.
If the parameter is specified incorrectly, the service will return
an error message.
currencyIsoCode Yes No The ISO code for the currency against which you want the
rates(case insensitive). It can be "EUR", "USD" or "ITL". If the
parameter is not specified, or the value is not valid, the service
will return an error message.
lang No No The language in which you want the data: it can be "it" or "en"
(case insensitive).
If the parameter is not specified, or the value is not valid, the
results will be provided in the default language.

http response codes:

200 OK
500 Internal Server Error
503 Service Unavailable
400 Bad Request
408 Request Timeout
404 Not Found

13
Examples of responses:

Content Type: application/json

{
"resultsInfo":
{
"totalRecords": 2,
"currency": "Lek",
"isoCode": "ALL",
"uicCode": "047",
"exchangeConventionCode": "I"
},
"rates":
[
{
"referenceDate": "2015",
"avgRate": "137.585",
"exchangeConvention": "Foreign currency amount for 1 Euro "
},
{
"referenceDate": "2016",
"avgRate": "138.21",
"exchangeConvention": "Foreign currency amount for 1 Euro "
}
]
}

Content Type: text/csv

Filename: <baseCurrencyIsoCode>_annual_time_series.csv

Currency, ISO Code, UIC Code,Rate,Rate convention,Reference date (CET)

Lek,ALL,047,125.9701,Foreign currency amount for 1 Dollar,2015
Lek,ALL,047,124.1039,Foreign currency amount for 1 Dollar,2016

14
List of Currencies
Returns a list of all currencies, including expired currencies.
GET /currencies?lang={}

Media types
The result is available in json format with the HTTP Accept header parameter:
• Accept: application/json

Input Parameters
Name Required Repeatable Description
lang No No The language in which you want the data: it can be "it" or "en"
(case insensitive).
If the parameter is not specified, or the value is not valid, the
results will be provided in the default language.

http response codes:

200 OK
500 Internal Server Error
503 Service Unavailable
400 Bad Request
408 Request Timeout
404 Not Found

Examples of responses:

Content Type: application/json

{
"resultsInfo":
{
"totalRecords": 2,
"timezoneReference": "Dates refer to the Central European Time Zone"
},
"currencies":
[
{
"countries":
[
{
"currencyISO": "ADP",
"country": "ANDORRA",
"countryISO": "AD",
"validityStartDate": "1999-02-01",
"validityEndDate": "2003-10-31"
}
],
"isoCode": "ADP",
"name": "Andorra Peseta",
"graph": false
},
{
"countries":
[
{

15
 "currencyISO": "AED",
"country": "UNITED ARAB EMIRATES",
"countryISO": null,
"validityStartDate": "1981-06-15",
"validityEndDate": null
}
],
"isoCode": "AED",
"name": "U.A.E. Dirham",
"graph": false
} ]
}

16