مستندات توسعه‌دهندگان PersianFX
PersianFX شروع استفاده
📊 API تقویم اقتصادی چندبازاره

PersianFX Economic Calendar API

API تقویم اقتصادی PersianFX رویدادهای اقتصادی ذخیره‌شده را در قالب JSON ارائه می‌کند. هر رویداد علاوه بر اطلاعات عمومی و داده‌های Actual / Forecast / Previous / Revised، می‌تواند عضویت و شدت اثر جداگانه برای بازارهای فارکس، کریپتو، فلزات و انرژی داشته باشد.

💱
Foreximpact + market_forex
₿
Cryptocrypto_effect + market_crypto
🥇
Metalsmetal_effect + market_metal
⚡
Energyenergy_effect + market_energy

API Endpoint

درخواست‌ها از نوع GET و خروجی JSON با UTF-8 است.

Endpoint URL
https://api.persianfx.com/api.phpJSON
HTTP Method
GET

پارامترهای درخواست

API دو حالت اصلی دارد: دریافت رویدادهای یک روز یا دریافت یک رویداد با شناسه داخلی.

پارامترنوعاجباریتوضیحنمونه
dateYYYY-MM-DDخیرتاریخ موردنظر. اگر ارسال نشود، تاریخ امروز بر اساس Asia/Tehran استفاده می‌شود.?date=2026-10-06
idIntegerخیرشناسه داخلی جدول economic_events.id. در این حالت پاسخ، یک Event Object مستقیم است.?id=154
پارامترهای market، currency و impact در نسخه فعلی API به‌صورت سروری پیاده‌سازی نشده‌اند؛ در صورت نیاز، خروجی events را در سمت کلاینت فیلتر کنید.

Quick Start

نمونه دریافت رویدادهای یک تاریخ مشخص

JavaScriptfetch
const url = "https://api.persianfx.com/api.php?date=2026-10-06";

fetch(url)
  .then(r => r.json())
  .then(data => {
    console.log(data.count);
    console.log(data.events);
  });
PHPPHP
<?php
$url = "https://api.persianfx.com/api.php?date=2026-10-06";
$data = json_decode(file_get_contents($url), true);

foreach ($data['events'] as $event) {
    echo $event['time'] . ' - ';
    echo $event['currency'] . ' - ';
    echo $event['event_name'] . PHP_EOL;
}
?>
Pythonrequests
import requests

url = "https://api.persianfx.com/api.php"
r = requests.get(url, params={"date": "2026-10-06"})
data = r.json()

for event in data["events"]:
    print(event["time"], event["currency"], event["event_name"])
دریافت یک رویدادid
fetch("https://api.persianfx.com/api.php?id=154")
  .then(r => r.json())
  .then(event => {
    console.log(event.event_name);
    console.log(event.actual);
  });

ساختار پاسخ روزانه

پاسخ ?date=YYYY-MM-DD شامل اطلاعات ریشه و آرایه events است.

{
  "status": "success",
  "date": "2026-10-06",
  "count": 25,
  "events": [
    {
      "id": 154,
      "external_id": 19398,
      "event_definition_id": 275,
      "event_name": "BOJ Gov Ueda Speaks",
      "event_name_fa": "سخنرانی اوئدا - رئیس بانک مرکزی ژاپن",
      "currency": "JPY",
      "currency_name": "ین ژاپن",
      "currency_market": "forex",
      "date": "2026-10-06",
      "time": "10:05:00",
      "time_model_name": null,
      "impact": "high",
      "crypto_effect": "low",
      "metal_effect": "low",
      "energy_effect": "low",
      "market_forex": 1,
      "market_crypto": 1,
      "market_metal": 1,
      "market_energy": 1,
      "actual": null,
      "forecast": null,
      "previous": null,
      "revised": null,
      "description": "...",
      "usual_effect": "...",
      "usual_effect_crypto": "...",
      "usual_effect_metals": "...",
      "usual_effect_energy": "...",
      "source_name": "بانک مرکزی ژاپن",
      "source_link": "https://www.boj.or.jp/en/index.htm/",
      "next_release": null,
      "source_type": "forex",
      "status": "waiting",
      "created_at": "2026-10-06 12:00:00",
      "updated_at": "2026-10-06 12:00:00"
    }
  ]
}

فیلدهای ریشه پاسخ روزانه

Fieldتوضیح
statusدر پاسخ روزانه موفق مقدار success دارد.
dateتاریخی که برای آن درخواست انجام شده است.
countتعداد رویدادهای موجود در آرایه events.
eventsآرایه رویدادهای اقتصادی همان روز.

شناسه، عنوان و زمان

فیلدهای اصلی هر Event Object

Fieldتوضیح
idشناسه داخلی رکورد در دیتابیس PersianFX؛ برای درخواست ?id=... و polling قابل استفاده است.
external_idشناسه یکتای occurrence از منبع. مبنای جلوگیری از رکورد تکراری و UPSERT است.
event_definition_idشناسه تعریف کلی نوع رویداد در منبع.
event_nameنام انگلیسی رویداد.
event_name_faنام فارسی رویداد.
currencyنماد ارز یا دارایی مرتبط، مانند USD، EUR، JPY یا OIL.
currency_nameنام فارسی ارز/دارایی مرتبط.
currency_marketدسته بازار اصلی اعلام‌شده توسط منبع.
dateتاریخ وقوع/انتشار رویداد.
timeساعت رویداد در دیتابیس.
time_model_nameتوضیح زمانی خاص مانند «کل‌روز»، «نامشخص» یا نام دوره؛ ممکن است null باشد.

تأثیر و عضویت در بازارها

شدت اثر هر بازار مستقل است و پرچم عضویت مشخص می‌کند رویداد در کدام دسته‌های منبع حضور داشته است.

شدت اثر

impactشدت اثر رویداد در فارکس.
crypto_effectشدت اثر در بازار کریپتو.
metal_effectشدت اثر در بازار فلزات.
energy_effectشدت اثر در بازار انرژی.

low mid / medium high none / null

عضویت بازار

market_forex1 یعنی رویداد در بخش Forex منبع دیده شده است.
market_crypto1 یعنی رویداد در بخش Crypto منبع دیده شده است.
market_metal1 یعنی رویداد در بخش Metals منبع دیده شده است.
market_energy1 یعنی رویداد در بخش Energy منبع دیده شده است.
برای فیلتر بازار، از پرچم‌های market_* استفاده کنید؛ برای نمایش شدت اثر، ستون متناظر همان بازار را بخوانید. ممکن است یک رویداد همزمان عضو چند بازار باشد.

📈 Economic Data

actualمقدار واقعی منتشرشده؛ قبل از انتشار معمولاً null است.
forecastمقدار پیش‌بینی بازار.
previousمقدار قبلی.
revisedنسخه اصلاح‌شده مقدار قبلی.
statuswaiting قبل از دریافت actual و published پس از آن.

🕒 زمان‌های سیستمی

created_atزمان ایجاد رکورد در دیتابیس.
updated_atآخرین زمان به‌روزرسانی رکورد.

توضیحات و اطلاعات تحلیلی

Fieldتوضیح
descriptionتوضیح اختصاصی occurrence یا اطلاعیه رویداد.
measuresشرح اینکه شاخص یا رویداد چه چیزی را اندازه‌گیری می‌کند.
usual_effectاثر معمول نتیجه بر فارکس.
usual_effect_cryptoاثر معمول بر کریپتو.
usual_effect_metalsاثر معمول بر فلزات.
usual_effect_energyاثر معمول بر انرژی.
why_trader_caresدلیل اهمیت رویداد برای معامله‌گران.
frequentlyتناوب/زمان‌بندی انتشار طبق متن منبع.
frequencyalias سازگاری برای frequently.
ff_noteیادداشت عمومی منبع درباره این نوع رویداد.
ff_noticeاطلاعیه اختصاصی occurrence فعلی.
derived_viaروش محاسبه یا استخراج داده، در صورت وجود.
speakerنام/سمت سخنران برای رویدادهای سخنرانی.
also_calledنام دیگر رویداد.
acro_expandتوضیح کامل مخفف.
abbreviationalias سازگاری برای acro_expand.

منبع و اطلاعات تکمیلی

Fieldتوضیح
source_nameنام سازمان یا منبع منتشرکننده.
source_linkلینک منبع.
intro_linkلینک معرفی تکمیلی، در صورت وجود.
intro_link_textمتن لینک معرفی.
next_releaseتاریخ انتشار بعدی در صورت اعلام منبع.
is_rateمشخص می‌کند رویداد از نوع نرخ بهره است یا خیر؛ 0/1/null.
rate_nameنام نرخ مرتبط در صورت وجود.
source_typeنوع نمایشی که به‌عنوان رکورد canonical نگه داشته شده است. برای تشخیص بازارهای مرتبط، از market_* استفاده کنید.
فیلد raw_json در دیتابیس داخلی ذخیره می‌شود، اما عمداً در خروجی عمومی api.php ارسال نمی‌شود.

فیلترهای کاربردی در سمت کلاینت

نسخه فعلی API همه رویدادهای تاریخ را برمی‌گرداند.

فقط رویدادهای Cryptomarket_crypto
const cryptoEvents = data.events.filter(
  event => Number(event.market_crypto) === 1
);

cryptoEvents.forEach(event => {
  console.log(event.event_name, event.crypto_effect);
});
High Impact فارکسForex
const highForex = data.events.filter(event =>
  Number(event.market_forex) === 1 &&
  event.impact === "high"
);
فلزات با اثر بالاMetals
const highMetals = data.events.filter(event =>
  Number(event.market_metal) === 1 &&
  event.metal_effect === "high"
);
فیلتر ارزUSD
const usdEvents = data.events.filter(
  event => event.currency === "USD"
);

⚠️ نکات مهم

بسیاری از فیلدها بسته به نوع رویداد می‌توانند null باشند؛ کد مصرف‌کننده باید null-safe باشد.
یک رویداد می‌تواند همزمان در چند بازار عضو باشد؛ از market_* برای عضویت و از فیلد اثر همان بازار برای شدت استفاده کنید.
قبل از انتشار، actual معمولاً null و status برابر waiting است. پس از دریافت actual، وضعیت به published تغییر می‌کند.
پارامتر id شناسه داخلی PersianFX است، نه external_id.
اگر date فرمت معتبر YYYY-MM-DD نداشته باشد، API پاسخ HTTP 400 با {"error":"Invalid date"} می‌دهد.
درخواست ?id=... اگر رویداد را پیدا نکند، آبجکت {"error":"Event not found"} برمی‌گرداند.
🌐 API URL

PersianFX Economic Calendar API

https://api.persianfx.com/api.php?date=2026-10-06GET