Exchange Rates REST API (Version 1.0)

Transcription

1 Exchange Rates REST API (Version 1.0) The new basic domain for A2A services is: For the sake of brevity, the basic domain is omitted from the description of the URLs. So, for example, instead of writing GET we will simply write GET /currencies Or instead of writing GET 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

2 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": " ", "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": " " ] 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, , ,foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro, ALBANIA,Lek,ALL,047,133.59,114.72,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro, ALGERIA,Algerian Dinar,DZD,106, , ,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro, ANGOLA,Adjusted Kwanza,AOA,087, , ,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro, ANTIGUA AND BARBUDA,East Caribbean Dollar,XCD,137,3.1442,2.70,Foreign currency amount for 1 Dollar,Foreign currency amount for 1 Euro,

3 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". 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

4 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": " ", "exchangeconvention": "Foreign currency amount for 1 Euro ", "exchangeconventioncode": "I", "referencedate": " " ] 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, ,foreign currency amount for 1 Euro, ALBANIA,Lek,ALL,047, ,Foreign currency amount for 1 Euro, ALGERIA,Algerian Dinar,DZD,106, ,Foreign currency amount for 1 Euro, ANGOLA,Adjusted Kwanza,AOA,087, ,Foreign currency amount for 1 Euro, ANTIGUA AND BARBUDA,East Caribbean Dollar,XCD,137, ,Foreign currency amount for 1 Euro,

5 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 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

6 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": " ", "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, ,foreign currency amount for 1 Euro,2016,8 ALBANIA,Lek,ALL,047, ,Foreign currency amount for 1 Euro,2016,8 ALGERIA,Algerian Dinar,DZD,106, ,Foreign currency amount for 1 Euro,2016,8 ANGOLA,Adjusted Kwanza,AOA,087, ,Foreign currency amount for 1 Euro,2016,8 ANTIGUA AND BARBUDA,East Caribbean Dollar,XCD,137, ,Foreign currency amount for 1 Euro,2016,8 6

7 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 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

8 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": " ", "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, ,Foreign currency amount for 1 Euro,2016 ALGERIA,Algerian Dinar,DZD,106, ,Foreign currency amount for 1 Euro,2016 ANGOLA,Adjusted Kwanza,AOA,087, ,Foreign currency amount for 1 Euro,2016 ANTIGUA AND BARBUDA,East Caribbean Dollar,XCD,137, ,Foreign currency amount for 1 Euro,2016 8

9 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". enddate Yes No Quotation end date. It is represented in relation to the Central European Time Zone in the format "yyyy-mm-dd". 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

10 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": " ", "avgrate": " ", "exchangeconvention": "Foreign currency amount for 1 Euro ", "referencedate": " ", "avgrate": " ", "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, ,Foreign currency amount for 1 Dollar, Lek,ALL,047, ,Foreign currency amount for 1 Dollar, Lek,ALL,047, ,Foreign currency amount for 1 Dollar, Lek,ALL,047, ,Foreign currency amount for 1 Dollar,

11 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. startyear Yes No Quotation start year. Must be a 4-digit integer in the YYYY format. endmonth Yes No Quotation end month.. Must be an integer between 1 and 12. endyear Yes No Quotation end year. Must be a 4-digit integer in the YYYY 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

12 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": " ", "avgrate": " ", "exchangeconvention": "Foreign currency amount for 1 Euro ", "referencedate": " ", "avgrate": " ", "exchangeconvention": "Foreign currency amount for 1 Euro ", "referencedate": " ", "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, ,Foreign currency amount for 1 Dollar, Lek,ALL,047, ,Foreign currency amount for 1 Dollar, Lek,ALL,047, ,Foreign currency amount for 1 Dollar,

13 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. endyear Yes No Quotation end year. Must be a 4-digit integer in the YYYY 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

14 Examples of responses: Content Type: application/json "resultsinfo": "totalrecords": 2, "currency": "Lek", "isocode": "ALL", "uiccode": "047", "exchangeconventioncode": "I", "rates": "referencedate": "2015", "avgrate": " ", "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, ,Foreign currency amount for 1 Dollar,2015 Lek,ALL,047, ,Foreign currency amount for 1 Dollar,

15 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": " ", "validityenddate": " " ], "isocode": "ADP", "name": "Andorra Peseta", "graph": false, "countries": 15

16 "currencyiso": "AED", "country": "UNITED ARAB EMIRATES", "countryiso": null, "validitystartdate": " ", "validityenddate": null ], "isocode": "AED", "name": "U.A.E. Dirham", "graph": false ] 16