باز هم با قسمتی دیگر از سری آموزشهای تخصصی کارینا در خدمت شما عزیزان هستیم. یکی از مواردی که ما به عنوان برنامهنویس یا مدیر سایت در پروژههای مرتبط با طلا و جواهر با آن مواجه میشویم، درخواست کارفرما برای نمایش روند قیمت در گذشته است. مشتری فقط قیمت امروز را نمیخواهد؛ بلکه میخواهد بداند قیمت در هفتهها و ماههای اخیر چه مسیری را طی کرده است. به همین دلیل، در این آموزش قرار است ساخت نمودار قیمت طلا در سایت را با کمک دادههای تاریخچه قیمت طلا قدمبهقدم یاد بگیریم.
در این مطلب ابتدا دادههای بازهای را با تاریخ شمسی از API دریافت میکنیم. سپس یک واسط امن در PHP میسازیم و در نهایت، با کتابخانهٔ Chart.js نمودار قیمت طلا را به شکلی خوانا و راستبهچپ در صفحه رسم میکنیم.
سناریوی واقعی: نمایش روند قیمت در سایت یک گالری طلا
یک مثال میزنم تا موضوع را بهتر متوجه شوید: فرض کنید برای یک گالری طلا، فروشگاه اینترنتی طراحی کردهاید. مدیر فروشگاه میخواهد در صفحهٔ اصلی و صفحهٔ محصولات، یک نمودار قیمت طلا قرار بگیرد تا خریداران پیش از خرید، روند بازار را ببینند. در واقع، این نمودار به اعتماد مشتری کمک میکند و زمان ماندن او در سایت را نیز افزایش میدهد.
بنابراین خواستههای کارفرما را میتوان به شکل زیر خلاصه کرد:
- نمایش قیمت هر گرم طلای ۱۸ عیار به تومان در قالب یک نمودار خطی؛
- امکان انتخاب بازهٔ «یک ماه اخیر»، «شش ماه اخیر» و «یک سال اخیر» توسط کاربر؛
- نمایش تاریخها به صورت شمسی، مطابق عادت مخاطب ایرانی؛
- سرعت بارگذاری مناسب و عدم افشای توکن API در کدهای سمت مرورگر؛
- نمایش پیام مناسب در صورت بروز خطا، بهجای یک کادر خالی.
معماری راهحل: چرا مستقیماً از مرورگر به API وصل نمیشویم؟
شاید اولین ایده این باشد که در جاوااسکریپت، مستقیماً به API کارینا ریکوئست بفرستیم. با این حال، این کار یک خطای رایج امنیتی است؛ زیرا توکن API در کد سمت کاربر قرار میگیرد و هر بازدیدکنندهای میتواند آن را ببیند و از سهمیهٔ شما استفاده کند.
حالا راهحل این مشکل چیست؟ راهحل استاندارد، ساختن یک واسط کوچک در سمت سرور است. به عبارت دیگر، جریان داده به ترتیب زیر خواهد بود:
- مرورگر بازهٔ دلخواه کاربر (مثلاً
1m) را به فایلgold-history.phpروی سرور شما میفرستد. - اسکریپت PHP تاریخ شروع و پایان را به صورت شمسی محاسبه میکند.
- اگر دادهٔ تازه در کش وجود داشته باشد، همان را برمیگرداند؛ در غیر این صورت با توکن محرمانه به API کارینا ریکوئست میفرستد.
- از ریسپانس API فقط برچسب تاریخها و قیمتها استخراج و به مرورگر ارسال میشود.
- کتابخانهٔ Chart.js این دادهها را به نمودار قیمت طلا تبدیل میکند.
در نتیجه، توکن هرگز از سرور خارج نمیشود و به لطف کش، تعداد ریکوئستها به API نیز به شکل محسوسی کاهش پیدا میکند.

آشنایی با API تاریخچه قیمت طلا کارینا
در اینجاست که API تاریخچه قیمت طلا کارینا به کمک ما میآید. این سرویس قیمتهای گذشتهٔ طلا را در یک بازهٔ تاریخ شمسی برمیگرداند و شما با پارامتر period مشخص میکنید که دادهها به صورت روزانه، هفتگی یا ماهانه گروهبندی شوند. پیش از نوشتن هر کدی، توصیه میشود یک بار API را با curl آزمایش کنید.
به مثال زیر توجه کنید:
# توکن را پیشتر در متغیر محیطی KARINA_API_TOKEN قرار دادهایم
curl -s --max-time 10 \
-H "Authorization: Bearer $KARINA_API_TOKEN" \
"https://karinaco.net/api/v1/gold/prices?start_date=1405-01-03&end_date=1405-01-06&period=daily"
جالب است بدانید که خروجی کد بالا به صورت زیر خواهد بود (برای خوانایی، فقط فیلدهای مورد نیاز این آموزش را در آرایهٔ results نگه داشتهایم):
{
"success": true,
"data": {
"metal": "gold",
"karat": 18,
"currency": "IRT",
"unit": "gram",
"calendar": "jalali",
"timezone": "Asia/Tehran",
"period": "daily",
"mode": "latest",
"start_date": "1405-01-03",
"end_date": "1405-01-06",
"count": 4,
"results": [
{ "period_key": "1405-01-03", "price": 17429900, "records": 1 },
{ "period_key": "1405-01-04", "price": 17430200, "records": 1 },
{ "period_key": "1405-01-05", "price": 17547500, "records": 1 },
{ "period_key": "1405-01-06", "price": 17491200, "records": 1 }
]
},
"quota": {
"unlimited": true,
"cost": 1,
"remaining": null
}
}
همانطور که مشاهده میکنید، فیلد calendar مقدار jalali دارد و قیمتها به تومان (IRT) و برای هر گرم طلای ۱۸ عیار هستند. علاوه بر این، هر عضو آرایهٔ results یک کلید دوره (period_key) و یک قیمت دارد؛ یعنی دقیقاً همان دو چیزی که برای محور افقی و عمودی نمودار لازم داریم.
از طرفی، بخش quota وضعیت سهمیهٔ شما را نشان میدهد. برای مثال، اگر پلن شما محدود باشد، فیلد remaining تعداد ریکوئستهای باقیمانده را مشخص میکند. فهرست کامل پارامترها و فیلدها نیز در مستندات رسمی کارینا در docs.karinaco.net آمده است.
انتخاب گام زمانی مناسب برای نمودار قیمت طلا
یکی از تصمیمهای مهم، انتخاب گام زمانی متناسب با طول بازه است. اگر برای یک سال، دادهٔ روزانه بگیرید، نمودار قیمت طلا شلوغ و ناخوانا میشود. به طور کلی، جدول زیر یک انتخاب متعادل را نشان میدهد:
| بازهٔ انتخابی کاربر | مقدار period | تعداد تقریبی نقاط نمودار | کاربرد مناسب |
|---|---|---|---|
| یک ماه اخیر | daily | حدود ۳۰ نقطه | مشاهدهٔ نوسانهای کوتاهمدت پیش از خرید |
| شش ماه اخیر | weekly | حدود ۲۶ نقطه | بررسی روند میانمدت بازار |
| یک سال اخیر | monthly | حدود ۱۲ نقطه | مقایسهٔ کلی قیمت در ماههای مختلف سال |
همانطور که میبینید، تعداد نقاط در هر سه حالت بین ۱۲ تا ۳۰ است؛ لذا نمودار قیمت طلا در همهٔ بازهها خوانا باقی میماند.

ساخت واسط PHP برای دریافت تاریخچه قیمت طلا
حالا نوبت به مهمترین بخش آموزش میرسد. در این اسکریپت، ورودی کاربر را فقط از میان سه کلید مجاز میپذیریم تا امکان ارسال پارامترهای دلخواه به API وجود نداشته باشد. همچنین برای تبدیل تاریخ امروز به تاریخ شمسی، از کلاس IntlDateFormatter استفاده میکنیم؛ بنابراین افزونهٔ intl باید روی سرور فعال باشد.
به مثال زیر توجه کنید:
<?php
// فایل gold-history.php — واسط امن میان مرورگر و API کارینا
declare(strict_types=1);
header('Content-Type: application/json; charset=utf-8');
const API_BASE = 'https://karinaco.net/api/v1';
const CACHE_TTL = 1800; // نتیجه را ۳۰ دقیقه در کش نگه میداریم
// بازههای مجاز؛ کاربر فقط میتواند یکی از این کلیدها را انتخاب کند
$presets = [
'1m' => ['modify' => '-1 month', 'period' => 'daily'],
'6m' => ['modify' => '-6 months', 'period' => 'weekly'],
'1y' => ['modify' => '-1 year', 'period' => 'monthly'],
];
function respondError(int $status, string $message): void
{
http_response_code($status);
echo json_encode(['error' => $message], JSON_UNESCAPED_UNICODE);
exit;
}
// تبدیل تاریخ میلادی به تاریخ شمسی با افزونهٔ intl (ارقام لاتین)
function toJalali(DateTimeImmutable $date): string
{
$formatter = new IntlDateFormatter(
'en_US@calendar=persian',
IntlDateFormatter::NONE,
IntlDateFormatter::NONE,
'Asia/Tehran',
IntlDateFormatter::TRADITIONAL,
'yyyy-MM-dd'
);
return $formatter->format($date);
}
$range = $_GET['range'] ?? '1m';
if (!isset($presets[$range])) {
respondError(422, 'بازهٔ زمانی انتخابشده معتبر نیست.');
}
$today = new DateTimeImmutable('now', new DateTimeZone('Asia/Tehran'));
$query = http_build_query([
'start_date' => toJalali($today->modify($presets[$range]['modify'])),
'end_date' => toJalali($today),
'period' => $presets[$range]['period'],
]);
// اگر نسخهٔ تازهای در کش داریم، همان را برمیگردانیم
$cacheFile = sys_get_temp_dir() . '/karina-gold-' . md5($query) . '.json';
if (is_file($cacheFile) && time() - filemtime($cacheFile) < CACHE_TTL) {
readfile($cacheFile);
exit;
}
// توکن API را همیشه از متغیر محیطی بخوانید، نه از داخل کد
$token = getenv('KARINA_API_TOKEN');
if (!$token) {
respondError(500, 'توکن API تنظیم نشده است.');
}
$ch = curl_init(API_BASE . '/gold/prices?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10, // حداکثر ۱۰ ثانیه منتظر پاسخ میمانیم
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Accept: application/json',
],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
$json = is_string($body) ? json_decode($body, true) : null;
if ($status !== 200 || !is_array($json) || empty($json['success'])) {
error_log("Karina gold history failed: HTTP {$status} {$error}");
// در صورت خطا، آخرین دادهٔ ذخیرهشده (حتی اگر قدیمی باشد) بهتر از نمودار خالی است
if (is_file($cacheFile)) {
readfile($cacheFile);
exit;
}
respondError(502, 'دریافت تاریخچهٔ قیمت طلا با خطا مواجه شد.');
}
// فقط دادههایی را که نمودار لازم دارد به مرورگر میفرستیم
$labels = [];
$prices = [];
foreach ($json['data']['results'] ?? [] as $row) {
$labels[] = $row['period_key'];
$prices[] = (int) $row['price'];
}
$output = json_encode([
'karat' => $json['data']['karat'] ?? null,
'unit' => $json['data']['unit'] ?? 'gram',
'period' => $json['data']['period'] ?? $presets[$range]['period'],
'labels' => $labels,
'prices' => $prices,
], JSON_UNESCAPED_UNICODE);
file_put_contents($cacheFile, $output, LOCK_EX);
echo $output;
در این کد چند نکتهٔ کلیدی رعایت شده است. اول اینکه توکن از متغیر محیطی KARINA_API_TOKEN خوانده میشود. دوم اینکه برای ریکوئست، Timeout دهثانیهای تعیین کردهایم تا صفحه در صورت کندی شبکه معطل نماند. سوم اینکه اگر API در دسترس نباشد، آخرین نسخهٔ موجود در کش برگردانده میشود.
جالب است بدانید که خروجی این اسکریپت برای بازهٔ نمونهٔ بالا به صورت زیر خواهد بود:
{
"karat": 18,
"unit": "gram",
"period": "daily",
"labels": ["1405-01-03", "1405-01-04", "1405-01-05", "1405-01-06"],
"prices": [17429900, 17430200, 17547500, 17491200]
}
در واقع، بهجای کل ریسپانس API، یک ساختار سبک و آماده برای نمودار قیمت طلا به مرورگر تحویل میدهیم. این کار حجم داده را کم میکند و کد جاوااسکریپت را نیز سادهتر میکند.

نکته: دادههای تاریخچه، برخلاف قیمت لحظهای، برای روزهای گذشته تغییر نمیکنند. بنابراین میتوانید مدت کش را برای بازههای هفتگی و ماهانه طولانیتر در نظر بگیرید تا مصرف سهمیهٔ API باز هم کمتر شود.
تذکر: قالب period_key در گامهای هفتگی و ماهانه ممکن است با گام روزانه متفاوت باشد. لذا پیش از انتشار، خروجی هر سه بازه را یک بار بررسی کنید و در صورت نیاز، برچسبها را مطابق سلیقهٔ طراحی سایت قالببندی کنید.
رسم نمودار قیمت طلا با Chart.js
پس از آماده شدن دادهها، به سراغ بخش نمایشی میرویم. برای رسم نمودار قیمت طلا از کتابخانهٔ متنباز Chart.js استفاده میکنیم؛ زیرا سبک است، از نمودار خطی و راستبهچپ پشتیبانی میکند و به وابستگی خاصی نیاز ندارد.
ساختار HTML صفحه
ابتدا یک منوی کشویی برای انتخاب بازه، یک عنصر canvas برای رسم نمودار و یک پاراگراف برای نمایش پیام وضعیت قرار میدهیم. به مثال زیر توجه کنید:
<div class="gold-chart-box">
<label for="gold-range">بازهٔ زمانی:</label>
<select id="gold-range">
<option value="1m">یک ماه اخیر (روزانه)</option>
<option value="6m">شش ماه اخیر (هفتگی)</option>
<option value="1y">یک سال اخیر (ماهانه)</option>
</select>
<canvas id="gold-chart" height="120"></canvas>
<p id="gold-chart-status" aria-live="polite"></p>
</div>
<script src="https://cdn.jsdelivr.net/npm/chart.js" defer></script>
<script src="/js/gold-chart.js" defer></script>
ویژگی aria-live باعث میشود پیامهای وضعیت برای صفحهخوانها نیز اعلام شوند. از طرفی، ویژگی defer اجرای اسکریپتها را تا پایان بارگذاری HTML به تأخیر میاندازد و ترتیب اجرای آنها را نیز حفظ میکند.
کد جاوااسکریپت نمودار قیمت طلا
در این مرحله، دادهها را از واسط PHP میگیریم و نمودار را میسازیم. اگر کاربر بازه را تغییر دهد، بهجای ساختن نمودار جدید، فقط دادههای نمودار فعلی را بهروز میکنیم. به مثال زیر توجه کنید:
// فایل /js/gold-chart.js
const canvas = document.getElementById('gold-chart');
const rangeSelect = document.getElementById('gold-range');
const statusBox = document.getElementById('gold-chart-status');
const toman = new Intl.NumberFormat('fa-IR');
let chart = null;
async function loadGoldHistory(range) {
statusBox.textContent = 'در حال دریافت اطلاعات...';
// اگر پاسخ بیش از ۱۰ ثانیه طول بکشد، ریکوئست را لغو میکنیم
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10000);
try {
const response = await fetch(`/gold-history.php?range=${encodeURIComponent(range)}`, {
signal: controller.signal,
});
const payload = await response.json();
if (!response.ok) {
throw new Error(payload.error || 'خطای ناشناخته');
}
renderChart(payload);
statusBox.textContent = '';
} catch (error) {
console.error(error);
statusBox.textContent = 'در حال حاضر امکان نمایش نمودار وجود ندارد؛ لطفاً دقایقی بعد دوباره تلاش کنید.';
} finally {
clearTimeout(timer);
}
}
function renderChart({ labels, prices, karat }) {
const data = {
labels,
datasets: [{
label: `قیمت هر گرم طلای ${karat} عیار (تومان)`,
data: prices,
borderColor: '#b8860b',
backgroundColor: 'rgba(184, 134, 11, 0.15)',
fill: true,
tension: 0.3,
pointRadius: 2,
}],
};
// اگر نمودار قبلاً ساخته شده، فقط دادهها را بهروز میکنیم
if (chart) {
chart.data = data;
chart.update();
return;
}
chart = new Chart(canvas, {
type: 'line',
data,
options: {
responsive: true,
interaction: { mode: 'index', intersect: false },
scales: {
// تاریخها شمسی هستند، پس از محور دستهای استفاده میکنیم نه محور زمانی
x: { type: 'category', ticks: { maxTicksLimit: 8 } },
y: { ticks: { callback: (value) => toman.format(value) } },
},
plugins: {
legend: { rtl: true },
tooltip: {
rtl: true,
callbacks: {
label: (ctx) => `${toman.format(ctx.parsed.y)} تومان`,
},
},
},
},
});
}
rangeSelect.addEventListener('change', () => loadGoldHistory(rangeSelect.value));
document.addEventListener('DOMContentLoaded', () => loadGoldHistory(rangeSelect.value));
در این کد، تابع loadGoldHistory مسئول دریافت داده و مدیریت خطاست و تابع renderChart فقط کار رسم را انجام میدهد. علاوه بر این، با Intl.NumberFormat و زبان fa-IR، اعداد محور عمودی و راهنمای نمودار با ارقام فارسی و جداکنندهٔ هزارگان نمایش داده میشوند.
نتیجهٔ نهایی، یک نمودار خطی طلاییرنگ است که با حرکت نشانگر ماوس روی هر نقطه، تاریخ شمسی و قیمت هر گرم طلا را به تومان نشان میدهد. با انتخاب گزینهٔ دیگری از منوی کشویی نیز نمودار قیمت طلا بدون بارگذاری مجدد صفحه بهروز میشود.

نکته: محور زمانی Chart.js (type: 'time') برای کار با تاریخهای میلادی طراحی شده است. از آنجا که دادههای ما شمسی هستند، محور دستهای (category) سادهترین و مطمئنترین انتخاب است؛ زیرا برچسبها را دقیقاً به همان ترتیبی که API برگردانده نمایش میدهد.
نکات تکمیلی برای انتشار روی سرور پروداکشن
پیش از انتقال این قابلیت به سرور اصلی پروژه، بهتر است موارد زیر را نیز بررسی کنید:
- تنظیم متغیر محیطی: توکن را در تنظیمات وبسرور یا پنل میزبانی تعریف کنید و هرگز آن را در مخزن گیت قرار ندهید.
- پایش سهمیه: فیلد
quotaرا در لاگها ثبت کنید تا پیش از اتمام سهمیه، از وضعیت آن مطلع شوید. - لیزی لود نمودار: اگر نمودار در پایین صفحه قرار دارد، میتوانید با
IntersectionObserverدریافت داده را تا زمان رسیدن کاربر به آن بخش به تأخیر بیندازید. - سازگاری با فریمورک: اگر پروژهٔ شما با لاراول نوشته شده است، منطق همین واسط را میتوانید با Http Client و Cache لاراول پیاده کنید.
برای مثال، در مقالهٔ اتصال API قیمت در لاراول با Http Client، Cache و Scheduler روش کش کردن و زمانبندی ریکوئستها را به تفصیل بررسی کردهایم. همچنین اگر علاوه بر نمودار، قصد دارید قیمت محصولات فروشگاه نیز با بازار همگام بماند، آموزش بهروزرسانی خودکار قیمت محصولات فروشگاه با API قیمت دلار میتواند برای شما مفید باشد.
اگر در کنار نمودار قیمت طلا، نمایش قیمت لحظهای را نیز لازم دارید، میتوانید از API قیمت طلا برای آخرین قیمت و از API تاریخچه قیمت طلا برای دادههای بازهای استفاده کنید. برای شروع، کافی است یکی از پلنهای مناسب پروژهٔ خود را در صفحهٔ پلنها انتخاب کنید و توکن خود را از داشبورد کارینا بسازید.
حرف آخر اینکه: برای ساخت یک نمودار قیمت طلا امن و سریع، دادهها را از طریق یک واسط سمت سرور با کش و مدیریت خطا دریافت کنید و فقط دادههای لازم را به مرورگر بفرستید. با انتخاب گام زمانی متناسب با بازه و استفاده از محور دستهای برای تاریخهای شمسی، نموداری خوانا و قابلاعتماد در اختیار کاربران قرار خواهد گرفت.
خب به پایان آموزش «ساخت نمودار قیمت طلا در سایت با API تاریخچه قیمت طلا و Chart.js» رسیدیم. امیدوارم این مبحث مورد توجه شما واقع شده باشد. چنانچه ابهام، اشکال یا سؤالی داشتید و یا مورد خاصی در پروژههایتان تجربه کردهاید، میتوانید در بخش دیدگاهها با ما و بقیهٔ همراهان کارینا به اشتراک بگذارید. همچنین پیشنهاد میگردد بلاگ کارینا را دنبال کنید تا از جدیدترین آموزشهای تخصصی بهرهمند شوید.
سوالات متداول
آیا میتوانم بدون PHP و مستقیماً از جاوااسکریپت به API تاریخچه قیمت طلا وصل شوم؟
از نظر فنی امکانپذیر است، اما توکن API در کد سمت مرورگر برای همه قابل مشاهده میشود. به همین دلیل توصیه میشود ریکوئستها همیشه از طریق یک واسط سمت سرور ارسال شوند.
تاریخهای ریسپانس API شمسی هستند یا میلادی؟
تاریخها شمسی هستند و منطقهٔ زمانی آنها Asia/Tehran است. تاریخ شروع و پایان بازه را نیز باید به صورت شمسی و با قالب YYYY-MM-DD ارسال کنید.
قیمتهای تاریخچه بر اساس چه واحدی برگردانده میشوند؟
در ریسپانس نمونه، قیمتها به تومان و برای هر گرم طلای ۱۸ عیار هستند. فیلدهای unit و karat در ریسپانس، واحد و عیار را مشخص میکنند.
آیا بهجای Chart.js میتوانم از کتابخانهٔ نمودار دیگری استفاده کنم؟
بله؛ خروجی واسط PHP فقط دو آرایهٔ برچسب و قیمت است و تقریباً هر کتابخانهٔ نموداری میتواند آن را نمایش دهد.
دیدگاهها
هنوز دیدگاهی ثبت نشده است. اولین نفر باشید!