Rial Exchange Rates Archive

This repository serves as the archive for Iranian Rial (IRR) currency conversion rates sourced from bonbast.com. The exchange rates are automatically updated every day using a GitHub Actions workflow.

The primary goal of this repository is to maintain a comprehensive historical record of Iranian Rial exchange rates over time.

Please note that all prices in this repository are in Toman.

Table of Contents

• Structure
  • {year}/{month}/{day} file model
  • full file model
• Files
• Usage
  • Getting exchange rates for specific date
  • Converting full file to date-price map/dict
  • Converting full files to array/list
• Currencies
• Contributing
• License

Structure

The repository is organized into two main directories: gregorian and jalali. Both directories have the same format and type of files, with the only difference being the date.

├── gregorian
│   └── {year}
│       ├── full -> contain every day in that year
│       └── {month}
│           ├── full -> contain every day in that month
│           └── {day}
├── jalali
│   └── {year}
│       ├── full -> contain every day in that year
│       └── {month}
│           ├── full -> contain every day in that month
│           └── {day}
└── automated-python-scripts

{year}/{month}/{day} file model

These files contain the daily currency conversion rates. They all have the same DTO for convenience.

Please note that the starting file is always 2012/10/09 for gregorian and 1391/07/18 for jalali.

{
  "{currency-code}": {
    "name": <string>,
    "sell": <int>,
    "buy": <int>
  }
}

full file model

If a year or a month has ended and the last day exists, a corresponding full file is available in the same directory. This file contains every single day with the same DTO structure.

{
  "{date}": {
    "{currency-code}": {
      "name": <string>,
      "sell": <int>,
      "buy": <int>
    }
  }
}

Files

Every night, automated scripts generate the following types of release files:

• {calende}_all.json: Contains all the information from the start
• {calende}_all.min.json: Similar to the previous one, but whitespaces and the name field (from currency DTO) is removed
• {calende}_imp.min.json: Similar to the previous one, but only for USD, EUR, and GBP
• {calende}_31days.min.json: Contains all currencies in the past 31 days
• {calende}_7days.min.json: Contains all currencies in the past 7 days

Note: Only the last 10 releases are retained. That means you always have to a get the last one like this:

curl -Ls https://github.com/SamadiPour/rial-exchange-rates-archive/releases/latest/download/gregorian_imp.min.json | jq

data branch files

This repository also includes an orphan branch that contains generated outputs. The branch will always have just one commit and no history. The data stored in this branch is identical to the release section, but it also includes the following files:

• /currency/{currency-code}.json: Contains currency specific information from the start

CORS Issue: If you are encountering CORS error while getting the release files, you can instead use the files stored in the data branch. For example, try one of these two links:

- https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/data/gregorian_imp.min.json
- https://cdn.jsdelivr.net/gh/SamadiPour/rial-exchange-rates-archive@data/gregorian_imp.min.json

Usage

You can access the historical exchange rate data by exploring the contents of this repository. The data is organized and stored in a structured format, allowing for easy retrieval and analysis.

Getting exchange rates for specific date

The output of these examples will be like this:

{
  "usd": {
    "name": "US Dollar",
    "sell": 3400,
    "buy": 3300
  }
}

# == Bash + jq ==
curl -s https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/gregorian/2015/10/15

# == Python ==
import requests
import json

response = requests.get(
    'https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/gregorian/2015/05/10'
)
response.raise_for_status()
prices = json.loads(response.text)
print(prices)
print(prices.get('usd', {}).get('buy', None))

// JavaScript
fetch('https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/jalali/1395/05/01')
    .then(response => response.json())
    .then(data => {
        console.log(data);
        console.log(data.usd.buy);
    })
    .catch(error => {
        console.error('Error:', error)
    })

Converting full file to date-price map/dict

The output of these examples will be like this:

{
  "2013/01/01": 3205,
  "2013/01/02": 3190,
  "2013/01/03": 3195
}

Examples:

# == Bash + jq ==
curl -s https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/gregorian/2015/10/full | jq 'to_entries | map({key: .key, value: .value.usd.buy}) | from_entries'

# == Python ==
import requests
import json

response = requests.get(
    'https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/gregorian/2015/full'
)
response.raise_for_status()
data = json.loads(response.text)
prices = {key: value['eur']['buy'] for key, value in data.items()}
print(prices)

// JavaScript
fetch('https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/jalali/1395/05/full')
    .then(response => response.json())
    .then(data => {
        const prices = Object.fromEntries(
            Object.entries(data).map(([key, value]) => [key, value.usd.sell])
        );
        console.log(prices);
    })
    .catch(error => {
        console.error('Error:', error)
    })

Converting full files to array/list

The output of these examples will be like this:

[
  3205,
  3190,
  3195
]

Examples:

# == Bash + jq ==
curl -s https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/gregorian/2015/10/full | jq '[.[] | .usd.buy]'

# == Python ==
import requests
import json

response = requests.get(
    'https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/gregorian/2015/full'
)
response.raise_for_status()
data = json.loads(response.text)
prices = (value["eur"]["buy"] for value in data.values())
print(prices)

// JavaScript
fetch('https://raw.githubusercontent.com/SamadiPour/rial-exchange-rates-archive/main/jalali/1395/05/full')
    .then(response => response.json())
    .then(data => {
        const prices = Object.values(data).map(item => item.usd.sell);
        console.log(prices);
    })
    .catch(error => {
        console.error('Error:', error)
    })

Currencies

Flag	Currency	Code
🇺🇸	US Dollar	USD
🇪🇺	Euro	EUR
🇬🇧	British Pound	GBP
🇨🇭	Swiss Franc	CHF
🇨🇦	Canadian Dollar	CAD
🇦🇺	Australian Dollar	AUD
🇸🇪	Swedish Krona	SEK
🇳🇴	Norwegian Krone	NOK
🇷🇺	Russian Ruble	RUB
🇹🇭	Thai Baht	THB
🇸🇬	Singapore Dollar	SGD
🇭🇰	Hong Kong Dollar	HKD
🇦🇿	Azerbaijani Manat	AZN
🇦🇲	10 Armenian Dram	AMD
🇩🇰	Danish Krone	DKK
🇦🇪	UAE Dirham	AED
🇯🇵	10 Japanese Yen	JPY
🇹🇷	Turkish Lira	TRY
🇨🇳	Chinese Yuan	CNY
🇸🇦	Saudi Riyal	SAR
🇮🇳	Indian Rupee	INR
🇲🇾	Malaysian Ringgit	MYR
🇦🇫	Afghan Afghani	AFN
🇰🇼	Kuwaiti Dinar	KWD
🇮🇶	100 Iraqi Dinar	IQD
🇧🇭	Bahraini Dinar	BHD
🇴🇲	Omani Rial	OMR
🇶🇦	Qatari Rial	QAR

Coins	Code
Azadi	azadi1
Emami	emami1
½ Azadi	azadi1_2
¼ Azadi	azadi1_4
Gerami	azadi1g

Contributing

Contributions to this repository are welcome! If you notice any issues, discrepancies, or have suggestions for improvement, please open an issue or submit a pull request.

License

This project is licensed under the MIT License. Feel free to use the data and code in accordance with the terms specified in the license.

Disclaimer: The exchange rates provided in this repository are sourced from bonbast.com, and any discrepancies or inaccuracies in the data are beyond the control of the repository maintainers.