fima

با این کتابخانهٔ پایتون می‌توانید داده‌های بازارهای مالی ایران را برای تحلیل و پژوهش دریافت کنید؛ از تاریخچهٔ سهام و اطلاعات صندوق‌ها تا قیمت طلا و ارز، اختیار معامله و معاملات بورس کالا.

نصب

به پایتون نسخهٔ ۳٫۱۰ یا جدیدتر نیاز دارید:

pip install fima

شروع سریع

برای دریافت تاریخچهٔ قیمت سهام، نام نماد را وارد کنید:

from fima import get_ticker_historical_data

history = get_ticker_historical_data(ticker="فملی")
print(history[["ClosingPrice", "TradeVolume"]].head())

خروجی یک جدول پانداس با نمایهٔ JalaliDate است؛ تاریخ‌های شمسی به‌شکل رشته‌هایی مانند 1405-07-26 برمی‌گردند. قیمت پایانی رسمی در ستون ClosingPrice و حجم معاملات در ستون TradeVolume قرار دارد.

چه داده‌هایی در دسترس است؟

• سهام و شاخص‌ها: تاریخچهٔ قیمت، معاملات و سهامداران از ماژول TSETMC.
• طلا، ارز و بازارهای جهانی: فهرست نمادها، آخرین قیمت‌های موجود و تاریخچهٔ روزانه از ماژول TGJU.
• صندوق‌های سرمایه‌گذاری: فهرست صندوق‌ها، ارزش خالص دارایی‌ها و ترکیب دارایی‌ها از ماژول Funds؛ اطلاعات صندوق‌ها از سامانهٔ بورس نیز در همین ماژول است.
• بورس کالا: معاملات بازار فیزیکی، صادراتی، آتی، اختیار و گواهی سپرده از ماژول IME.
• اختیار معامله: زنجیرهٔ قراردادها، تاریخچه و محاسبات قیمت و حساسیت‌ها از ماژول Options.
• فرابورس: اوراق بدهی، شاخص‌ها، نرخ بدون ریسک و تأمین مالی از ماژول IFB.
• نهادهای مالی: فهرست نهادها از ماژول TSEInstitutions.
• بانک مرکزی ایران: تاریخچهٔ رسمی نرخ‌های سیاستی و بازار بین‌بانکی از ماژول CBI؛ راهنما و محدودیت دسترسی منبع.

مثال‌های کاربردی

قیمت تعدیل‌شدهٔ سهام

برای افزودن قیمت‌های تعدیل‌شده، گزینهٔ تعدیل را فعال کنید:

from fima import get_ticker_historical_data

history = get_ticker_historical_data(ticker="فملی", adjust_prices=True)
print(history[["ClosingPrice", "AdjustedClosingPrice"]].head())

قیمت خام حفظ می‌شود. تعدیل بر پایهٔ قیمت مرجع بورس و با مبنای آخرین تاریخ برگشتی است؛ این خروجی، سری بازده کل تأییدشده نیست. روش محاسبه و انتخاب تاریخ مبنا در راهنمای تعدیل آمده است.

تاریخچهٔ قیمت دلار

برای دریافت داده‌های طلا و ارز، نام ابزار و گروه آن را مشخص کنید:

from fima import get_tgju_history

usd = get_tgju_history("دلار", "ارز", start_date="2026-10-01", end_date="2026-10-15")
print(usd[["GregorianDate", "ClosingPrice"]].tail())

در این مثال، تاریخ‌های ورودی میلادی‌اند. برای تاریخ شمسی و یافتن نام دقیق ابزارها، راهنمای طلا و ارز را ببینید. واحد هر سری در مشخصات خروجی قرار دارد؛ ریال و تومان به هم تبدیل نمی‌شوند.

اطلاعات صندوق‌های سرمایه‌گذاری

برای دیدن فهرست صندوق‌ها و اطلاعات فعلی آن‌ها از این تابع استفاده کنید:

from fima import get_all_funds

funds = get_all_funds()
print(funds[["FundName", "FundTypeName", "TotalNAV"]].head())

برای دریافت تاریخچهٔ ارزش خالص دارایی‌ها و ترکیب دارایی‌های یک صندوق، نام دقیق آن را از همین فهرست انتخاب کنید؛ نمونه‌ها در راهنمای صندوق‌ها آمده‌اند.

فهرست و جزئیات صندوق‌ها از سامانهٔ بورس

برای انتخاب صندوق از منبع TSETMC، نام گروه و نام کامل صندوق کافی است:

نمونهٔ زیر از نام کلیدهای نسخهٔ ۰٫۱۰٫۰ استفاده می‌کند. تفاوت‌های ناسازگار با نسخه‌های پیشین در راهنمای مهاجرت آمده‌اند.

from fima import get_tsetmc_funds, get_tsetmc_fund_details

funds = get_tsetmc_funds("مختلط")
print(funds[["FundName", "RegistrationNumber"]].head())
details = get_tsetmc_fund_details(funds.iloc[0]["FundName"], fund_type="مختلط")
print(details["FundName"])

نام صندوق را از ستون FundName انتخاب کنید. جدول فهرست و دیکشنری جزئیات از نام‌های یکسان برای مفهوم‌های مشترک استفاده می‌کنند. فیلدهای نامشخص منبع فقط در بخش صریح ProviderMetadata حفظ می‌شوند. اطلاعات این منبع ممکن است با وب‌سایت صندوق از نظر تاریخ و پوشش متفاوت باشد؛ راهنمای صندوق‌های بورس جزئیات بیشتری دارد.

قرارداد داده‌ها

خروجی‌های عمومی نسخهٔ ۰٫۹ از یک قرارداد مشترک پیروی می‌کنند:

• نام ستون‌های جدول‌ها و کلیدهای معمول دیکشنری‌ها انگلیسی و به‌شکل PascalCase است؛ نام توابع و پارامترهای پایتون به‌شکل snake_case باقی می‌ماند. مفهوم‌های مالی یکسان نیز تا جای ممکن نام یکسان دارند.
• تاریخ‌های میلادی در جای مناسب به‌صورت datetime پانداس و تاریخ‌های شمسی به‌شکل رشتهٔ لاتین YYYY-MM-DD برمی‌گردند.
• مقدارهای مالی قابل محاسبه عددی‌اند، اما شناسه‌هایی که کاربرد محاسباتی ندارند رشته باقی می‌مانند. مقدارهای ناموجود نیز با رفتار معمول داده‌های گمشده در پانداس نمایش داده می‌شوند.
• درصدهای داخل جدول‌ها بر حسب واحد درصد هستند؛ برای نمونه 2.5 یعنی 2.5%.
• واحد پول و واحد فیزیکی اعلام‌شدهٔ ارائه‌دهنده بدون تبدیل حفظ می‌شود، مگر آنکه مستندات یک تابع صریحاً خلاف آن را بگویند.

تعریف کامل نام‌ها، نوع داده‌ها و استثناها در قرارداد داده‌های عمومی آمده است.

ارتقا به نسخهٔ ۰٫۹٫۰

در نسخهٔ ۰٫۹٫۰ نام برخی ستون‌ها، نوع بعضی داده‌ها، مقیاس درصدهای جدولی و تعدادی محاسبه برای یکپارچگی و اصلاح معنی مالی تغییر کرده‌اند. اگر از نسخه‌ای قدیمی‌تر ارتقا می‌دهید، راهنمای کامل مهاجرت را پیش از به‌روزرسانی کد خود ببینید. نام توابع و پارامترهای عمومی تغییر نکرده است.

مستندات بیشتر

• قرارداد داده‌های عمومی و راهنمای مهاجرت نسخهٔ ۰٫۹٫۰
• راهنمای سهام و شاخص‌ها و روش تعدیل قیمت
• راهنمای طلا، ارز و بازارهای جهانی
• راهنمای بانک مرکزی و تاریخچهٔ نرخ‌های سیاستی
• راهنمای صندوق‌ها و تاریخچهٔ دارایی‌ها
• راهنمای صندوق‌های بورس
• مثال‌های اختیار معامله، فرابورس، بورس کالا و نهادهای مالی
• فهرست توابع عمومی

نکات مهم

• دریافت داده به اینترنت و در دسترس بودن منبع وابسته است؛ دادهٔ موجود ممکن است قدیمی یا ناقص باشد.
• این کتابخانه مستقل از ارائه‌دهندگان داده است. شرایط استفادهٔ هر منبع را رعایت کنید.

مشارکت و گزارش مشکل

برای گزارش مشکل، یک مسئله در گیت‌هاب باز کنید. نام تابع، نمونهٔ کوتاه کد و متن خطا را بنویسید. برای توسعه و اجرای آزمون‌ها، راهنمای مشارکت را ببینید.

این پروژه با مجوز ام‌آی‌تی منتشر می‌شود. نسخهٔ قابل نصب در صفحهٔ بسته در پای‌پی‌آی و راه تماس در اطلاعات پروژه قرار دارد.