Skip to content

Latest commit

 

History

History
308 lines (252 loc) · 8.96 KB

README.md

File metadata and controls

308 lines (252 loc) · 8.96 KB
Raw

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

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.