API داده بازار khapi؛ دریافت قیمت تتر، طلا و دلار در پروژه شما
راهنمای استفاده از API داده بازار khapi برای دریافت و پردازش قیمت تتر، دلار و طلا؛ همراه با نمونههای عملی curl، Python و Next.js برای ساخت داشبورد، هشدار قیمت و ابزارهای تحلیلی.
دادهٔ بازار khapi چیست؟
khapi endpoint دادهٔ بازار را برای دریافت نرخهای لحظهای مانند ارز، طلا و شاخصها فراهم میکند. برخلاف API خبر، این endpoint بدون احراز هویت در دسترس است.
تنها endpoint معتبر:
curl -X GET "https://khapi.ir/api/market-prices"
ساختار پاسخ
پاسخ شامل وضعیت کلی و دیکشنری `prices` است:
{
"available": true,
"stale": true,
"news_count_24h": 5970,
"stale_after_seconds": 120,
"max_age_seconds": 21600,
"service": {
"active": "active",
"failed": "active"
},
"prices": {
"usd_free": {
"label": "دلار آزاد",
"value": 98200.0,
"unit": "تومان",
"updated_at": "2026-07-31T22:47:19",
"age_seconds": 51,
"stale": false,
"too_old": false,
"provider": "TGJU USD/IRR",
"change_24h_percent": 0.2,
"change_24h_value": 200.0
}
}
}
فیلدهای هر قیمت عبارتاند از: `label`، `value` (مقدار عددی)، `unit`، `updated_at`، `age_seconds`، `stale`، `too_old`، `provider` و `change_24h_percent`.
نکتهٔ مهم دربارهٔ فیلد `stale`
فیلد `stale` در سطح کلی پاسخ ممکن است `true` باشد حتی اگر برخی قیمتها تازه باشند. دلیل آن میتواند قدیمیبودن بخشی از دادهها، مانند شاخصهای بورس در ساعات غیرمعاملاتی، باشد. بنابراین مصرفکننده نباید کل پاسخ را تازه فرض کند و باید وضعیت `stale` را برای هر نماد جداگانه بررسی کند.
دریافت قیمت با Python
نمونهٔ کامل برای خواندن `usd_free` و اعتبارسنجی تازگی:
import requests
response = requests.get("https://khapi.ir/api/market-prices", timeout=20)
response.raise_for_status()
data = response.json()
if not data.get("available"):
raise RuntimeError("دادهٔ بازار در دسترس نیست")
usd = data["prices"].get("usd_free")
if usd is None:
raise KeyError("نماد usd_free یافت نشد")
# بررسی تازگی پیش از مصرف
if usd.get("stale") or usd.get("too_old"):
print("هشدار: قیمت usd_free ممکن است قدیمی باشد")
else:
print(f"{usd['label']}: {usd['value']:,} {usd['unit']}")
print(f"بهروزرسانی: {usd['updated_at']} (سن: {usd['age_seconds']} ثانیه)")
print(f"تغییر ۲۴ ساعته: {usd['change_24h_percent']}%")
همیشه پیش از نمایش یا ذخیرهٔ هر نماد، فیلدهای `stale` و `too_old` آن نماد را بررسی کنید.
کاربردها
- نمایش قیمت لحظهای در داشبورد یا اپلیکیشن
- ساخت هشدار عبور قیمت از آستانه (در سرویس خودتان)
- ذخیرهٔ تاریخچه برای تحلیل روند
- ترکیب با دادهٔ خبر برای تحلیل زمینه
خطاهای رایج
- فرض اینکه کل پاسخ تازه است بهخاطر `stale: false` کلی (اشتباه است)
- مقایسهٔ قیمتهای ناهمواحد (ریال، تومان، دلار)
- نادیدهگرفتن `age_seconds` هنگام تصمیمگیری
لینکهای داخلی
جمعبندی
Endpoint `/api/market-prices` تنها منبع معتبر دادهٔ بازار در khapi است. همیشه تازگی را در سطح هر نماد بررسی کنید و قیمتهای `stale` یا `too_old` را پیش از مصرف رد یا علامتگذاری کنید.
این مطلب چطور به کار شما بیاید؟
مفاهیم این مقاله را مستقیم در پنل khapi امتحان کنید:
آماده شروع هستید؟
۳ روز استفادهٔ رایگان از پنل تحلیلگر، مطابق محدودیتهای دورهٔ آزمایشی و بدون نیاز به کارت بانکی.