مستندات API نسخهٔ ۱

نقاط دسترسی

پایهٔ آدرس: https://bazarnama.github.io. فایل‌ها ایستا هستند و با GitHub Actions بازسازی می‌شوند؛ زمان واقعی به‌روزرسانی را از freshness بخوانید، نه از زمان درخواست.

نمونه: latest.json (ساختار)

{
  "api": "bazarnama/v1",
  "generated_utc": "2026-11-13T10:57:03",
  "fetched_utc": "2026-11-13T11:03:43Z",
  "freshness": {
    "counts": {
      "fresh": 44,
      "aging": 0,
      "stale": 0,
      "unknown": 0
    },
    "checked_utc": "2026-11-13T11:03:43Z",
    "policy_version": 1
  },
  "items": [
    "... 44 items ..."
  ]
}

یک قلم واقعی

{
  "id": "usd",
  "family": "currency",
  "name": {
    "en": "US dollar (Tehran free market)",
    "fa": "دلار آمریکا (بازار آزاد)"
  },
  "unit": "IRT",
  "price": 268200.0,
  "price_irt": null,
  "change_pct": 0.47,
  "spread_pct": 0.97,
  "sources": 2,
  "method": "average",
  "as_of": null,
  "updated_utc": "2026-11-13T10:44:43",
  "stale": false,
  "page": {
    "fa": "https://nerkhara.com/dollar/",
    "en": "https://nerkhara.com/en/dollar/"
  },
  "history": {
    "json": "https://nerkhara.com/api/v1/history/usd.json",
    "csv": "https://nerkhara.com/api/v1/history/usd.csv",
    "first": "2016-09-21",
    "last": "2026-11-13"
  },
  "freshness": {
    "status": "fresh",
    "observed_utc": "2026-11-13T10:44:43Z",
    "checked_utc": "2026-11-13T11:03:43Z",
    "age_seconds": 1140,
    "max_age_seconds": 5400,
    "clock_basis": "provider_timestamp"
  },
  "source_checked_utc": "2026-11-13T11:03:43Z",
  "source_name": "NerkhAra",
  "source_updated_utc": "2026-11-13T10:44:43",
  "source_selection": "primary-aggregated",
  "secondary_source": "NerkhSanj",
  "secondary_price": 266900.0,
  "validation_source": "NerkhSanj",
  "validation_price": 266900.0,
  "source_discrepancy_pct": 0.485,
  "validation_warning": false,
  "discrepancy_warning": false,
  "validation": {
    "status": "accepted",
    "reason": "ok_in_range"
  }
}

فیلدها

نمونه: تاریخچه (usd، سه نقطهٔ آخر)

{
  "api": "bazarnama/v1",
  "id": "usd",
  "unit": "IRT",
  "updated_utc": "2026-11-13T11:00:00Z",
  "points": [
    {
      "timestamp": 1794553200,
      "price": 268200.0
    },
    {
      "timestamp": 1794564000,
      "price": 268200.0
    },
    {
      "timestamp": 1794567600,
      "price": 268200.0
    }
  ]
}

timestamp یعنی Unix UTC بر حسب ثانیه و price در همان unit سطح بالای فایل است. فاصلهٔ نقاط یکنواخت نیست (سال‌های قدیم معمولاً روزانه‌اند و نقاط اخیر می‌توانند ساعتی باشند) و ممکن است شکاف داشته باشد؛ نقطهٔ گمشده را درون‌یابی نکنید.

تازگی و سقف سن

وضعیت aging از ۶۵٪ سقف شروع می‌شود. سری‌های روزانه (مثل برنت و WTI فیزیکی، سبد اوپک، گاز طبیعی) آستانه‌های بلندتری دارند؛ جزئیات در DATA-FRESHNESS.md. نمونهٔ source-health.json:

{
  "schema": "bazarnama/source-health/v1",
  "freshness": {
    "policy": {
      "crypto": 1200,
      "currency": 5400,
      "gold": 7200,
      "coin": 7200,
      "metal": 7200,
      "energy": 7200
    },
    "counts": {
      "fresh": 44,
      "aging": 0,
      "stale": 0,
      "unknown": 0
    }
  }
}

اعتبارسنجی

دلایل ممکن برای validation.reason (از آخرین اجرا):

نمونهٔ اجرا

# curl
curl -s https://bazarnama.github.io/api/v1/latest.json | jq '.items[] | select(.id=="usd") | {price, unit, freshness: .freshness.status}'

# JavaScript
const r = await fetch("https://bazarnama.github.io/api/v1/latest.json");
const { items } = await r.json();
const x = items.find(i => i.id === "usd");
if (x.stale || x.freshness.status !== "fresh") console.warn("not live");

# Python
import requests
d = requests.get("https://bazarnama.github.io/api/v1/history/usd.json", timeout=15).json()
print(d["unit"], d["points"][-1])

سیاست پایداری

• مسیرها و نام فیلدهای v1 حذف یا تغییر نمی‌کنند؛ فقط فیلد اضافه می‌شود. کد شما باید فیلدهای ناشناخته را نادیده بگیرد.
• تغییر ناسازگار فقط در مسیر /api/v2/ منتشر می‌شود.
• بدون کلید و بدون محدودیت رسمی؛ بیش از یک خواندن در دقیقه برای هر فایل لازم نیست. بدون SLA.
• داده «لحظه‌ای» تضمین‌شده نیست؛ فقط freshness.status = fresh به‌معنی تازه بودن طبق سیاست بالاست و قیمت stale نباید زنده تلقی شود.
• مجوز بازنشر داده‌های منبع هنوز با تأیید انسانی بررسی نشده؛ پیش از استفادهٔ تجاری آن را بررسی کنید.