Introduction
Welcome to the Kurs API! You can use our HTTP JSON API to get information on Serbian Dinar currency exchange rates based on official data from National Bank of Serbia.
More information about Exchange rate of Serbian Dinar can be found on National Bank of Serbia (NBS) web site.
Kurs uses NBS web services to acquire data about rates and provides API to access this data in more developer friendly way. Rates data is fetched every day at 8 AM. If the rate is not published, which is the case on weekdays and holidays, rate from the last known day will be used for that day.
All dates are relative to the NBS timezone Europe/Belgrade.
Beside the API, a simple conversion form can be found on Kurs web page.
Authentication
Kurs API is publicly available. No authentication is needed.
Currencies
Get a specific Currency
curl "https://kurs.resenje.org/api/v1/currencies/usd"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd')
response.json()
The above command returns JSON structured like this:
{
"code": "USD",
"number": 840,
"country": "United States of America",
"since": "2002-05-15",
"until": "2016-12-30"
}
This endpoint retrieves a specific currency information.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
Get all Currencies
curl "https://kurs.resenje.org/api/v1/currencies"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies')
response.json()
The above command returns JSON structured like this:
{
"currencies": [
{
"code": "EUR",
"number": 978,
"country": "EMU of European Union",
"since": "2002-05-15",
"until": "2016-12-30"
},
{
"code": "USD",
"number": 840,
"country": "United States of America",
"since": "2002-05-15",
"until": "2016-12-30"
}
]
}
This endpoint retrieves all currencies.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/usd
Daily Rates
Daily rates are unmodified values of currency exchange rates provided by NBS.
Get current currency Rate
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/today"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/today')
response.json()
The above command returns JSON structured like this:
{
"code": "USD",
"date": "2017-01-04",
"date_from": "2017-01-04",
"number": 1,
"parity": 1,
"cash_buy": 117.7702,
"cash_sell": 119.4306,
"exchange_buy": 118.2446,
"exchange_middle": 118.6004,
"exchange_sell": 118.9562
}
This endpoint retrieves a current rate for specific currency.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/today
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
Get a specific daily Rate
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/2016-01-25"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/2016-01-25')
response.json()
The above command returns the same JSON structure like in the previous API call.
This endpoint retrieves a rate on a specific date for a currency.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/<YEAR>-<MONTH>-<DAY>
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
| YEAR | Year of a requested date |
| MONTH | Month of a requested date |
| DAY | Day of a requested date |
Get currency daily Rates
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/2016-12-25/count/3"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/2016-12-25/count/3')
response.json()
The above command returns JSON structured like this:
{
"rates": [
{
"code": "USD",
"date": "2016-12-25",
"date_from": "2016-12-23",
"number": 248,
"parity": 1,
"cash_buy": 117.5197,
"cash_sell": 119.1765,
"exchange_buy": 117.9931,
"exchange_middle": 118.3481,
"exchange_sell": 118.7031
},
{
"code": "USD",
"date": "2016-12-26",
"date_from": "2016-12-26",
"number": 249,
"parity": 1,
"cash_buy": 117.2566,
"cash_sell": 118.9098,
"exchange_buy": 117.729,
"exchange_middle": 118.0832,
"exchange_sell": 118.4374
},
{
"code": "USD",
"date": "2016-12-27",
"date_from": "2016-12-27",
"number": 250,
"parity": 1,
"cash_buy": 117.3222,
"cash_sell": 118.9762,
"exchange_buy": 117.7948,
"exchange_middle": 118.1492,
"exchange_sell": 118.5036
}
],
"count": 3,
"sort": 1,
"start": "2016-12-25",
"end": "2016-12-27"
}
This endpoint retrieves a list for currency rates starting from a specific date up to a date that is a defined by the number of days ahead of that date.
If the number of days is negative, then the list will be in a revers order, the first element in that list will be the rate for a requested date followed by earlier days up to the requested number of days.
Maximum number of days is 1000.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/<YEAR>-<MONTH>-<DAY>/count/<COUNT>
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
| YEAR | Year of a requested date |
| MONTH | Month of a requested date |
| DAY | Day of a requested date |
| COUNT | Number of days (ban be negative for a reverse order) |
Weekly Rates
Weekly rates are average, minimum and maximum currency rates for an ISO 8601 week calculated from daily rates. Every day of a week is treated as a data point regardless if the rate is published on that day or it is used from the previous one, like in case of weekends and holidays.
Get Rate for this week
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/this-week"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/this-week')
response.json()
The above command returns JSON structured like this:
{
"code": "USD",
"week": "2017w01",
"parity": 1,
"cash_buy_avg": 117.0428,
"cash_buy_max": 117.7702,
"cash_buy_min": 116.3154,
"cash_sell_avg": 118.6929,
"cash_sell_max": 119.4306,
"cash_sell_min": 117.9552,
"exchange_buy_avg": 117.5143,
"exchange_buy_max": 118.2446,
"exchange_buy_min": 116.7839,
"exchange_middle_avg": 117.8679,
"exchange_middle_max": 118.6004,
"exchange_middle_min": 117.1353,
"exchange_sell_avg": 118.2215,
"exchange_sell_max": 118.9562,
"exchange_sell_min": 117.4867
}
This endpoint retrieves a current week rate for specific currency.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/this-week
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
Get a specific weekly Rate
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/2016w42"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/2016w42')
response.json()
The above command returns the same JSON structure like in the previous API call.
This endpoint retrieves a week currency rate for a specific week.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/<YEAR>w<WEEK>
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
| YEAR | Year |
| WEEK | Week number |
Get currency weekly Rates
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/2016w09/count/2"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/2016w09/count/2')
response.json()
The above command returns JSON structured like this:
{
"rates": [
{
"code": "USD",
"week": "2016w09",
"parity": 1,
"cash_buy_avg": 112.1525,
"cash_buy_max": 112.8101,
"cash_buy_min": 111.7602,
"cash_sell_avg": 113.7337,
"cash_sell_max": 114.4005,
"cash_sell_min": 113.3358,
"exchange_buy_avg": 112.6043,
"exchange_buy_max": 113.2645,
"exchange_buy_min": 112.2104,
"exchange_middle_avg": 112.9431,
"exchange_middle_max": 113.6053,
"exchange_middle_min": 112.548,
"exchange_sell_avg": 113.2819,
"exchange_sell_max": 113.9461,
"exchange_sell_min": 112.8856
},
{
"code": "USD",
"week": "2016w10",
"parity": 1,
"cash_buy_avg": 110.5564,
"cash_buy_max": 111.5851,
"cash_buy_min": 109.6736,
"cash_sell_avg": 112.115,
"cash_sell_max": 113.1583,
"cash_sell_min": 111.2198,
"exchange_buy_avg": 111.0017,
"exchange_buy_max": 112.0346,
"exchange_buy_min": 110.1154,
"exchange_middle_avg": 111.3357,
"exchange_middle_max": 112.3717,
"exchange_middle_min": 110.4467,
"exchange_sell_avg": 111.6697,
"exchange_sell_max": 112.7088,
"exchange_sell_min": 110.778
}
],
"count": 2,
"sort": 1,
"start": "2016w09",
"end": "2016w10"
}
This endpoint retrieves a list for currency weekly rates starting from a specific week up to a week that is a defined by the number of weeks ahead of that week.
If the number of weeks is negative, then the list will be in a revers order, the first element in that list will be the rate for a requested week followed by earlier months up to the requested number of months.
Maximum number of months is 1000.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/<YEAR>-<WEEK>/count/<COUNT>
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
| YEAR | Year of a requested date |
| WEEK | Week number of a requested date |
| COUNT | Number of days (ban be negative for a reverse order) |
Monthly Rates
Monthly rates are average, minimum and maximum currency rates for a month calculated from daily rates. Every day of a month is treated as a data point regardless if the rate is published on that day or it is used from the previous one, like in case of weekends and holidays.
Get Rate for this month
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/this-month"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/this-month')
response.json()
The above command returns JSON structured like this:
{
"code": "USD",
"month": "2017-01",
"parity": 1,
"cash_buy_avg": 116.6791,
"cash_buy_max": 117.7702,
"cash_buy_min": 116.3154,
"cash_sell_avg": 118.3241,
"cash_sell_max": 119.4306,
"cash_sell_min": 117.9552,
"exchange_buy_avg": 117.1491,
"exchange_buy_max": 118.2446,
"exchange_buy_min": 116.7839,
"exchange_middle_avg": 117.5016,
"exchange_middle_max": 118.6004,
"exchange_middle_min": 117.1353,
"exchange_sell_avg": 117.8541,
"exchange_sell_max": 118.9562,
"exchange_sell_min": 117.4867
}
This endpoint retrieves a current month rate for specific currency.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/this-month
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
Get a specific monthly Rate
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/2016-01"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/2016-02')
response.json()
The above command returns the same JSON structure like in the previous API call.
This endpoint retrieves a month currency rate for a specific month.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/<YEAR>-<MONTH>
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
| YEAR | Year |
| MONTH | Month number |
Get currency monthly Rates
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/2016-05/count/2"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/2016-05/count/2')
response.json()
The above command returns JSON structured like this:
{
"rates": [
{
"code": "USD",
"month": "2016-05",
"parity": 1,
"cash_buy_avg": 107.9527,
"cash_buy_max": 110.2697,
"cash_buy_min": 105.9571,
"cash_sell_avg": 109.4746,
"cash_sell_max": 111.8243,
"cash_sell_min": 107.4509,
"exchange_buy_avg": 108.3875,
"exchange_buy_max": 110.7139,
"exchange_buy_min": 106.3839,
"exchange_middle_avg": 108.7137,
"exchange_middle_max": 111.047,
"exchange_middle_min": 106.704,
"exchange_sell_avg": 109.0398,
"exchange_sell_max": 111.3801,
"exchange_sell_min": 107.0241
},
{
"code": "USD",
"month": "2016-06",
"parity": 1,
"cash_buy_avg": 109.2903,
"cash_buy_max": 112.1438,
"cash_buy_min": 107.4718,
"cash_sell_avg": 110.8312,
"cash_sell_max": 113.7248,
"cash_sell_min": 108.987,
"exchange_buy_avg": 109.7306,
"exchange_buy_max": 112.5955,
"exchange_buy_min": 107.9047,
"exchange_middle_avg": 110.0608,
"exchange_middle_max": 112.9343,
"exchange_middle_min": 108.2294,
"exchange_sell_avg": 110.3909,
"exchange_sell_max": 113.2731,
"exchange_sell_min": 108.5541
}
],
"count": 2,
"sort": 1,
"start": "2016-05",
"end": "2016-06"
}
This endpoint retrieves a list for currency monthly rates starting from a specific month up to a month that is a defined by the number of months ahead of that month.
If the number of months is negative, then the list will be in a revers order, the first element in that list will be the rate for a requested month followed by earlier months up to the requested number of months.
Maximum number of months is 1000.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/<YEAR>-<MONTH>/count/<COUNT>
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
| YEAR | Year of a requested date |
| MONTH | Month of a requested date |
| COUNT | Number of days (ban be negative for a reverse order) |
All Daily Rates
This API endpoints return Daily Rates for all Currencies.
Get all current Rates
curl "https://kurs.resenje.org/api/v1/rates/today"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/rates/today')
response.json()
The above command returns JSON structured like this:
{
"rates": [
{
"code": "EUR",
"date": "2017-01-03",
"date_from": "2016-12-30",
"number": 253,
"parity": 1,
"cash_buy": 122.608,
"cash_sell": 124.3366,
"exchange_buy": 123.1019,
"exchange_middle": 123.4723,
"exchange_sell": 123.8427
},
{
"code": "USD",
"date": "2017-01-03",
"date_from": "2016-12-30",
"number": 253,
"parity": 1,
"cash_buy": 116.3154,
"cash_sell": 117.9552,
"exchange_buy": 116.7839,
"exchange_middle": 117.1353,
"exchange_sell": 117.4867
}
]
}
This endpoint retrieves current rates for all currencies.
HTTP Request
GET https://kurs.resenje.org/api/v1/rates/today
Get all Rates on a specific date
curl "https://kurs.resenje.org/api/v1/rates/2016-01-25"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/rates/2016-01-25')
response.json()
The above command returns the same JSON structure like in the previous API call.
This endpoint retrieves a rate on a specific date for a currency.
HTTP Request
GET https://kurs.resenje.org/api/v1/rates/<YEAR>-<MONTH>-<DAY>
URL Parameters
| Parameter | Description |
|---|---|
| YEAR | Year of a requested date |
| MONTH | Month of a requested date |
| DAY | Day of a requested date |
Announced Rates
National Bank of Serbia publishes indicative RSD rates against EUR and USD on every business day at 14h. By 18h each business day, the NBS also publishes the official middle exchange rate of RS against the EUR, applicable from 8h next business day.
This data can be acquired by the Kurs API, too, in a form of an Announced Rate.
Get Announced currency Rate
curl "https://kurs.resenje.org/api/v1/currencies/usd/rates/future"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/rates/future')
response.json()
The above command returns JSON structured like this:
{
"code": "USD",
"date": "2017-01-09",
"type": "indicative",
"rate": 117.2071,
"change": 0.1791
}
This endpoint retrieves a announced (indicative or official) rate for specific currency.
Field “change” is a relative change of a dinar rate against the foreign currency in percents compared to the current middle exchange rate. Positive value is a dinar’s appreciation, and negative dinars’ depreciation.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/rates/future
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
Get all Announced Rates
curl "https://kurs.resenje.org/api/v1/rates/future"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/rates/future')
response.json()
The above command returns JSON structured like this:
{
"rates": [
{
"code": "EUR",
"date": "2017-01-04",
"type": "official",
"rate": 123.6418,
"change": -0.0391
},
{
"code": "USD",
"date": "2017-01-03",
"type": "indicative",
"rate": 117.2071,
"change": 0.1791
}
]
}
This endpoint retrieves a list of all announced currency rates.
HTTP Request
GET https://kurs.resenje.org/api/v1/rates/future
Conversions
Conversions represent amount of money converted on a specific date to or from a foreign currency or to or from Serbian Dinar.
Convert by current Rate
curl "https://kurs.resenje.org/api/v1/currencies/usd/conversions/123.45/today"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/conversions/123.45/today')
response.json()
The above command returns JSON structured like this:
{
"rate": {
"code": "USD",
"date": "2017-01-04",
"date_from": "2017-01-04",
"number": 1,
"parity": 1,
"cash_buy": 117.7702,
"cash_sell": 119.4306,
"exchange_buy": 118.2446,
"exchange_middle": 118.6004,
"exchange_sell": 118.9562
},
"buy_middle": 14641.21938,
"sell_middle": 1.0408902499485668,
"buy_exchange": 14597.29587,
"sell_exchange": 1.0377769296598245,
"buy_cash": 14538.73119,
"sell_cash": 1.0336546915112208
}
This endpoint retrieves a current conversion for the provided amount of money and rate for specific currency.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/conversions/<AMOUNT>/today
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
| AMOUNT | The amount of money to convert |
Convert by a specific Rate
curl "https://kurs.resenje.org/api/v1/currencies/usd/conversions/123.45/2016-01-25"
import requests
response = requests.get('https://kurs.resenje.org/api/v1/currencies/usd/conversions/123.45/2016-01-25')
response.json()
The above command returns the same JSON structure like in the previous API call.
This endpoint retrieves a conversion for the provided amount of money and rate for specific currency on a specific date.
HTTP Request
GET https://kurs.resenje.org/api/v1/currencies/<CODE>/conversions/<AMOUNT>/<YEAR>-<MONTH>-<DAY>
URL Parameters
| Parameter | Description |
|---|---|
| CODE | The currency three letter code |
| YEAR | Year of a requested date |
| MONTH | Month of a requested date |
| DAY | Day of a requested date |
| AMOUNT | The amount of money to convert |
Errors
curl "https://kurs.resenje.org/api/v1/currencies/abc"
import requests
response = requests.get('http://kurs.resenje.org/api/v1/currencies/abc')
response.json()
The above command returns JSON structured like this:
{
"code": 404,
"message": "Currency Not Found"
}
The Kurs API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request – Request body or URL contains invalid data |
| 404 | Not Found – The specific resource could not be found |
| 405 | Method Not Allowed – HTTP method is not allowed for a specific resource |
| 500 | Internal Server Error – We had a problem with our server. Try again later. |
All error responses contain a JSON encoded body with fields code and message where message can contain more detailed explanation about the error.