A free, keyless JSON API for Iran's free-market exchange rates (with a daily archive since 2010)

If you build anything that touches prices in Iran, you quickly run into the same problem: the rate people actually trade at is the Tehran free-market rate, it moves every day, and most data sources either require an API key or only give you the current number.

I needed the daily history for a pricing tool, so I ended up publishing the data openly. This post is a short tour of what is available.

What you get

• 15 series: US dollar, euro, UAE dirham, Turkish lira, British pound, Chinese yuan, Tether, Bitcoin, 18k and 24k gold per gram, and five gold coins
• Live rates, refreshed every minute
• A daily archive going back to 2010 for the oldest series
• No API key, no sign-up
• Plain JSON, amounts in Iranian toman (1 toman = 10 rial), dates in the Jalali calendar

The endpoints

Live rates:

GET https://nerkh.jahankhahan.shop/data/live.json

{
  "date": "1405/07/13",
  "time": "19:59",
  "rates": { "dollar": 268700, "euro": 301680, "aed": 73403, "gold": 26547200 },
  "change": { "dollar": 0.15, "euro": -0.42 },
  "ounce": 4129.98
}

Daily archive, one array of [date, rate] pairs per series:

GET https://nerkh.jahankhahan.shop/data/rates.json

Today's intraday points (low, high and a point every ten minutes):

GET https://nerkh.jahankhahan.shop/data/intraday.json

And a small calculator that answers "what does an item bought on date X cost today?":

GET https://nerkh.jahankhahan.shop/calc?price=830000&date=1404/07/15&margin=20&format=json

It returns the rate on the purchase date, the current rate, the ratio between them, the replacement cost and a sell price with your margin.

A quick example in Python

import json, urllib.request

BASE = "https://nerkh.jahankhahan.shop"

def get(path):
    with urllib.request.urlopen(BASE + path, timeout=30) as r:
        return json.load(r)

def rate_on(days, date):
    """Closing rate of the last trading day that is not after `date`."""
    found = None
    for day, value in days:
        if day > date:
            break
        found = value
    return found

live = get("/data/live.json")
archive = {s["key"]: s["days"] for s in get("/data/rates.json")["series"]}

then = rate_on(archive["dollar"], "1404/07/15")
now = live["rates"]["dollar"]
print("replacement cost:", round(830000 * now / then))

Two things worth knowing

Holidays have no row. The market is closed on Fridays and public holidays, so for a date that is missing you take the last earlier trading day. The arrays are sorted, and Jalali dates written as YYYY/MM/DD compare correctly as plain strings, so a binary search works.

Do not loop over /calc. If you are pricing a whole catalogue, fetch live.json and rates.json once and do the multiplication yourself. The rates do not change more often than once a minute.

Ready-made pieces

• Full reference: nerkh.jahankhahan.shop/developers/en
• Examples for PHP, Python, Node.js, WordPress and Google Sheets: github.com/hamidjh80-arch/nerkhsanj-api
• An embeddable widget (two lines of HTML): nerkh.jahankhahan.shop/widget
• A WooCommerce plugin that keeps product prices in step with the exchange rate: nerkh.jahankhahan.shop/woocommerce

Terms

It is free. Please credit "Nerkhsanj" when you show the numbers and read each endpoint at most once a minute. The figures are market observations and exchange-rate-based estimates, not forecasts or financial advice.

If something is missing or looks wrong, open an issue on GitHub or leave a comment here.