API اور MCP دستاویزات
FinancialMD مالیاتی بیانات فراہم کرتا ہے جو SEC فائلنگز سے تیار کیے گئے ہیں۔ ہر نمبر اس فائلنگ سے منسلک ہوتا ہے جس سے وہ آیا تھا، اور ہر نمبر کسی بھی تاریخ پر پڑھا جا سکتا ہے۔ کسی اکاؤنٹ کی ضرورت نہیں ہوتی۔
پہلی کال کریں
API HTTPS پر JSON ہے۔ یہ کال Apple کے آخری پانچ سالانہ آمدنی کے گوشوارے واپس کرتی ہے۔ اسے کسی key کی ضرورت نہیں۔
curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"گوشوارہ income_statement، balance_sheet، cash_flow یا supplemental میں سے ایک ہوتا ہے۔ مدت کی قسم annual، quarterly، ltm یا ytd میں سے ایک ہوتی ہے۔
کسی کمپنی کا نام بتائیں
ہر کمپنی route ایک company parameter لیتا ہے۔
ticker:AAPL، یا ایکسچینج بتانے کے لیےticker:AAPL.XNAScik:320193، SEC کا کمپنی نمبرfmd_<id>، وہ id جو FinancialMD کمپنی کو دیتا ہے
سادہ AAPL کو ticker کے طور پر پڑھا جاتا ہے اور صرف ہندسوں کو CIK کے طور پر۔ جواب میں meta.company.matched_by میں بتایا جاتا ہے کہ کیا match ہوا۔
ایک قدر پڑھیں
کامیاب جواب { data, meta } ہوتا ہے۔ data کے اندر کوئی عدد کبھی براہِ راست نہیں ہوتا۔ یہ ایک value object ہوتا ہے:
{
"value": 391035000000,
"unit": "USD",
"currency": "USD",
"decimals": -6,
"period": { "start": "2023-10-01", "end": "2024-09-28", "type": "annual", "fiscal_year": 2024, "fiscal_period": "FY" },
"known": { "from": "YYYY-MM-DDThh:mm:ssZ", "to": null },
"restated": false,
"method": "as_filed",
"calc_type": "as_filed",
"proof": { "id": "p_...", "accession": "0000320193-24-000123", "form": "10-K", "filed": "2024-11-01", "taxonomy": "us-gaap", "tag": "...", "source_url": "https://www.sec.gov/..." }
}known وہ مدت ہے جس میں یہ تازہ ترین فائل کردہ figure تھا۔ restated صرف تب true ہوتا ہے جب بعد کی کسی فائلنگ نے figure کو بدل دیا ہو؛ پھر restatement_kind بتاتا ہے کہ کیسے۔ proof.id، GET /proof/{id} پر، value کے پیچھے موجود فائلنگ اور raw facts کے ثبوت تک resolve ہوتا ہے۔
ماضی کو جیسا وہ جانا جاتا تھا ویسا پڑھیں
as_of=2024-06-30کسی بھی read route پر وہ واپس کرتا ہے جو اس لمحے معلوم تھا۔original=trueہر مدت کا پہلی بار رپورٹ کیا گیا ورژن واپس کرتا ہے۔history=trueہر مدت کا ہر ورژن واپس کرتا ہے، سب سے پرانا پہلے۔GET /v1/changes?since=<timestamp>اس کے بعد معلوم ہونے والے حقائق کی فہرست دیتا ہے۔
روٹس
| روٹ | یہ کیا واپس کرتا ہے |
|---|---|
GET /v1/companies | کمپنی ڈائریکٹری فلٹرز اور پیجنگ کے ساتھ |
GET /v1/company/profile | پروفائل، فہرستیں اور دستیاب ڈیٹا سیٹس |
GET /v1/company/metrics | کمپنی کے ٹیمپلیٹ کی تصوراتی قطاریں |
GET /v1/company/financials/{statement}/standardized | ایک معیاری گوشوارہ |
GET /v1/company/financials/{statement}/as_reported | فائلر کی اپنی لائن آئٹمز، ٹیگز کے ساتھ |
GET /v1/company/ratios | گوشواروں سے حساب کیے گئے تناسب، ان کے ان پٹس کے ثبوت کے ساتھ |
GET /v1/company/ratios/daily/{ratio_id} | مدتوں کے لحاظ سے ایک تناسب کی سیریز |
GET /v1/company/filings | کسی کمپنی کا فائلنگ انڈیکس |
GET /v1/filing/{accession} | ایک فائلنگ |
GET /v1/filing/{accession}/facts | ہر mapped fact جسے ایک فائلنگ نے tag کیا |
GET /v1/filing/{accession}/document | EDGAR پر فائلنگ کے صفحات کے لنکس، یا اس کی بنیادی دستاویز بطور HTML، PDF یا صفحہ تصاویر |
GET /v1/company/ownership/insiders | فارم 3، 4 اور 5 سے اندرونی ٹرانزیکشنز |
GET /v1/company/ownership/institutional | کسی کمپنی کے Form 13F ہولڈرز، سہ ماہی کے لحاظ سے |
GET /v1/ownership/institutional/holders | فارم 13F مینیجرز |
GET /v1/ownership/institutional/holdings | ایک مینیجر کا 13F پورٹ فولیو ایک سہ ماہی کے لیے |
GET /v1/company/splits | فائلنگ کے مطابق اسٹاک اسپلٹس، اور آیا قیمتیں ان کی تصدیق کرتی ہیں یا نہیں |
GET /v1/company/dividends | ہر مدت میں اعلان کردہ یا ادا کردہ فی شیئر ڈیویڈنڈ، جیسا کہ فائل کیا گیا |
GET /v1/events_calendar | آمدنی کی ریلیزز (8-K Item 2.02 فائل کیا گیا) اور ماڈل کی متوقع تاریخیں |
GET /v1/company/events | 8-K آئٹمز: فائلنگ پر مبنی ایونٹ فیڈ |
GET /v1/news | ہر کور شدہ کمپنی کی 8-K فائلنگز، سب سے نئی پہلے، ایونٹ کی اقسام اور اہمیت کی سطح کے ساتھ |
GET /v1/news/feed | FinancialMD کی اپنی ایونٹ فیڈ، ہر ایونٹ رکھنے والے SEC فارم سے، قواعد کے مطابق بنی سرخیوں، اہمیت اور اہم اعداد و شمار کے ساتھ۔ وائر نیوز نہیں |
GET /v1/news/issuer_releases | جاری کنندگان کی اپنے بارے میں شائع کردہ ریلیزز: SEC نمائشیں، اور جاری کنندہ کی اپنی فیڈ سے سرخی اور لنک |
GET /v1/company/call_materials | آمدنی کال کا وہ مواد جو جاری کنندہ نے SEC میں فائل کیا: ریلیزز، تیار شدہ ریمارکس، خطوط، پریزنٹیشنز، اور جب فائل کیا گیا ہو تو ٹرانسکرپٹ |
GET /v1/call_material/{id} | جاری کنندہ کی فائل کردہ ایک دستاویز بطور اقتباسات، سیکشنز، مقرر کی باریوں اور موضوعی ٹیگز کے ساتھ |
GET /v1/calls_calendar | آمدنی کالز، جیسا کہ جاری کنندگان انہیں SEC فائلنگز میں اعلان کرتے ہیں، جاری کنندہ کے اپنے ویب کاسٹ صفحے کے لنک کے ساتھ |
GET /v1/search/filings | 2001 سے EDGAR دستاویزات کی مکمل متن تلاش (SEC EDGAR مکمل متن کی تلاش) |
GET /v1/coverage | ہر ڈیٹا سیٹ اپنی حیثیت کے ساتھ: فراہم کردہ، کور نہیں (لائسنس یافتہ) یا تیار نہیں، اور اس کے بجائے کیا استعمال کریں |
GET /v1/company/estimates | FinancialMD کے اپنے ماڈل پر مبنی بنیادی تخمینے، وقفوں اور مخصوص وقت کے مطابق (point-in-time) ٹریک ریکارڈ کے ساتھ، کمپنی کی وہ رہنمائی جیسا کہ اس کی فائلنگز میں بیان کی گئی ہے، اور وضاحتی اشارے۔ یہ consensus نہیں، نہ ہی analyst estimates ہیں۔ طریقہ دیکھیں |
GET /v1/company/estimates/consensus | کور نہیں: consensus estimates لائسنس یافتہ ہیں۔ 404 not_covered متبادل کے ساتھ جواب دیتا ہے |
GET /v1/company/analyst_ratings | کور نہیں: analyst ratings لائسنس یافتہ ہیں۔ 404 not_covered جواب دیتا ہے |
GET /v1/company/transcripts | کور نہیں: call transcripts لائسنس یافتہ ہیں۔ 404 not_covered جواب دیتا ہے |
GET /v1/company/stock_prices/intraday | کور نہیں: حقیقی وقت اور انٹرا ڈے قیمتیں لائسنس یافتہ ہیں۔ جوابات 404 not_covered |
GET /v1/company/logo | کمپنی کی شناخت کے لیے ایک لوگو: ایک کھلے لائسنس والی فائل جس کے ساتھ اس کی نسبت ہو، یا ایک تیار کردہ ٹائل۔ JSON، SVG یا PNG |
GET /v1/politician_trades | امریکی ایوان نمائندگان کے اراکین کی تجارتیں جو پیریڈک ٹرانزیکشن رپورٹس میں، جیسا کہ فائل کی گئی ہیں، سرکاری رپورٹ کے ساتھ درج ہیں۔ کبھی قیمت زدہ نہیں۔ استعمال 5 U.S.C. 13107(c)(1) کے تحت محدود ہے: data.notice |
GET /v1/company/segments | جیسا رپورٹ کیا گیا سیگمنٹ حقائق (کاروبار، جغرافیہ، مصنوعات) |
GET /v1/company/ownership/insider_holders | ہر اندرونی شخص کی اپنے تازہ ترین Form 4 یا Form 5 کے بعد کی ملکیت |
GET /v1/company/ownership/funds | وہ فنڈز جنہوں نے اپنی تازہ ترین Form N-PORT میں کمپنی کو ہولڈ کیا ہوا ہے |
GET /v1/funds | Form N-PORT فنڈز اپنی تازہ ترین رپورٹ کے ساتھ |
GET /v1/fund/holdings | ایک فنڈ کی Form N-PORT ہولڈنگز |
GET /v1/company/kpis | کمپنی کی رپورٹ کردہ ایڈجسٹڈ اور آپریٹنگ میٹرکس، ہر ایک کے ساتھ اس کا حوالہ |
GET /v1/company/dividend_events | نقد ڈیویڈنڈز اپنی تاریخوں کے ساتھ، جیسا کہ فائل کیا گیا |
GET /v1/company/ownership/insider_holdings | فارم 3، 4 اور 5 کی ہولڈنگ لائنز |
GET /v1/fund/profile | N-CEN سے ایک فنڈ کی قسم اور اس کی شیئر کلاسز کی فیسیں |
GET /v1/fund/nav | ایک فنڈ کے نیٹ اثاثے رپورٹ مہینے کے لحاظ سے، ہر کلاس کی رپورٹ شدہ ماہانہ واپسی ہمارے ریٹرن انڈیکس کے ساتھ، اور SEC فائلنگز سے کلوزڈ-اینڈ NAV فی شیئر۔ روزانہ NAV فراہم نہیں کی جاتی |
GET /v1/identifiers/xref | کسی ایک شناخت کنندہ کے لیے، وہ کمپنی یا فنڈ جس کی یہ نشاندہی کرتا ہے، اور دوسرے کھلے شناخت کنندے، ہر ایک اپنے ماخذ کے ساتھ |
GET /v1/identifiers/master | ہر کمپنی کے کھلے شناختی نمبر، پیج کیے گئے |
GET /v1/company/stock_prices/returns | قیمت کی واپسی، کل واپسی اور زیادہ سے زیادہ ڈرا ڈاؤن معیاری ونڈوز میں، جو end-of-day bars اور SEC-filed splits اور dividends سے حساب کیے جاتے ہیں |
GET /v1/company/identifiers | LEI اور FIGI اپنے ثبوت کے ساتھ |
GET /v1/company/stock_prices | ڈیلی بارز جو صرف IEX پر ہونے والی ٹریڈز سے بنائی گئی ہیں۔ کنسولیڈیٹڈ ٹیپ نہیں۔ بطور ڈیفالٹ raw؛ adjust=splits یا adjust=total_return ایڈجسٹڈ ویلیوز شامل کرتا ہے |
GET /v1/screen | ہر کور شدہ کمپنی کو تازہ ترین مدت کے میٹرکس پر اسکرین کریں |
POST /v1/verify | فائل شدہ ویلیو کے ساتھ نمبر چیک کریں |
GET /v1/changes | وہ حقائق جن کے بارے میں علم ایک مخصوص وقت کے بعد دستیاب ہوا |
POST /v1/request-data | ہمیں بتائیں کہ آپ کو کون سا ڈیٹا چاہیے تھا اور نہیں ملا۔ کوئی key نہیں، کبھی چارج نہیں کیا گیا، ہفتہ وار جائزہ لیا جاتا ہے۔ درخواست دینے کا طریقہ دیکھیں |
GET /v1/request-data | POST /v1/request-data کی باڈی میں یہ شامل ہوتا ہے |
GET /v1/request-data/{id} | درخواست کی صورتحال: نئی، triaged، planned، done یا wontfix |
GET /v1/requested | درخواست کی گئی اور فراہم کی گئی: جائزہ لی گئی درخواستیں گنتیوں کے ساتھ، جمع کرانے والے کی کوئی تفصیل نہیں |
GET /proof/{id} | سرو کی گئی قدر کا ثبوت |
GET /v1/company/line_items | لیبل اور مدت کے لحاظ سے ایک رپورٹ شدہ لائن: جیسا رپورٹ کیا گیا تفصیلی لائنیں، سیگمنٹ اعداد و شمار، کمپنی میٹرکس اور رہنمائی |
GET /v1/screen/nl | ایک سادہ زبان کی اسکرین: سوال کو اسکرین فلٹرز میں پارس کیا جاتا ہے (ایک AI model یا مقررہ قواعد کے ذریعے، لیبل کے ساتھ) اور GET /v1/screen کے طور پر چلایا جاتا ہے |
GET /v1/ask | ایک AI-written جواب جو ایک کمپنی کے بارے میں اس کی اپنی فائل شدہ ویلیوز سے ہے، جس میں ہر نمبر کو حوالہ دیے گئے حقائق کے خلاف چیک کیا گیا ہے |
GET /v1/news/summary | FinancialMD کی اپنی ایونٹ فیڈ سے ایک دن کی فائلنگ پر مبنی خبروں، یا ایک کمپنی کے حالیہ واقعات، کا AI-written خلاصہ؛ ہر بلٹ اپنی فائلنگز کا حوالہ دیتا ہے اور ہر نمبر کو ان کے خلاف چیک کیا جاتا ہے |
GET /v1/company/ratios/forward | ہمارے اپنے model-based estimates پر فارورڈ valuation ratios (لیبل شدہ model output، کبھی consensus نہیں)، تخمینے، اس کے وقفے اور اس کے ٹریک ریکارڈ کے ساتھ |
GET /v1/company/technicals | تکنیکی اشاریے (moving averages، RSI، MACD، Bollinger bands، ATR، close range) جو single-venue daily bars اور SEC-filed splits سے حساب کیے جاتے ہیں |
GET /v1/pre_ipo | وہ کمپنیاں جنہوں نے پبلک ہونے کے لیے فائل کیا ہے: ایسے رجسٹرنٹس جن کی کسی بھی پیریڈک رپورٹ سے پہلے S-1 یا F-1 فائل پر موجود ہو، اسٹیٹس، مجوزہ ٹکر اور تاریخوں کے ساتھ |
GET /v1/pre_ipo/{cik} | ایک pre-IPO رجسٹرنٹ: اسٹیٹس اور اس کا قاعدہ، رجسٹریشن فائلنگز، وہ مالی اعداد و شمار جنہیں اس نے ٹیگ کیا، اور پروسپیکٹس سے پڑھی گئی آفرنگ کی شرائط |
GET /v1/fx_rates | یورپی مرکزی بینک کی عوامی فائلوں سے روزانہ حوالہ شدہ تبادلہ کی شرحیں، یورو کے ذریعے کسی بھی دوسری کرنسی کے مقابلے میں پیش کی جانے والی کوئی کرنسی؛ حوالہ جاتی شرحیں، قابل تجارت کوٹس نہیں |
GET /v1/research | آزاد تحقیقی رپورٹس جو CC BY 4.0 لائسنس یافتہ ہیں، جو ان کے پبلشر کی ویب سائٹ پر بغیر فیس کے پڑھی جا سکتی ہیں: کمپنی، مجموعہ، زبان، الفاظ اور تاریخ کے لحاظ سے تلاش کریں، ہر ایک کے ساتھ رپورٹ کے اپنے الفاظ میں خلاصہ ہوتا ہے |
GET /v1/research/{id} | ایک تحقیقی رپورٹ مکمل طور پر منظم Markdown کی صورت میں: سیکشنز، ٹکرز، تاریخ، ذرائع، لائسنس اور وہ نسبت جسے اسے نقل کرتے وقت برقرار رکھنا ہے |
POST /v1/feedback | ہمیں بتائیں کیا کام آیا اور کیا نہیں: ایک نوٹ، ایک درجہ بندی یا وجوہات۔ کوئی key نہیں، کبھی چارج نہیں ہوتا۔ GET /v1/feedback باڈی کی وضاحت کرتا ہے |
POST /v1/data-errors | وہ نمبر رپورٹ کریں جسے آپ غلط سمجھتے ہیں۔ اس کا فوراً ہمارے فراہم کردہ نمبر سے اور روزانہ SEC فائلنگ سے موازنہ کیا جاتا ہے۔ پھر GET /v1/data-errors/{id} استعمال کریں |
OpenAPI دستاویز میں ہر پیرامیٹر اور جواب کا schema موجود ہے۔ llms.txt، llms-full.txt اور skill file ایجنٹس کے لیے بھی یہی بتاتے ہیں؛ https://api.financial.md/docs انٹرایکٹو ریفرنس ہے اور https://api.financial.md/changelog تبدیلیوں کی فہرست دیتا ہے۔
ایک نمبر چیک کریں
curl -X POST "https://api.financial.md/v1/verify" -H "content-type: application/json" \
-d '{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000}'جواب میں verdict کے طور پر matches، differs یا unknown ہوتا ہے، فائل شدہ ویلیو اس کے ثبوت کے ساتھ، فرق، اور ایک scale_hint بھی ہوتا ہے جب آپ کا نمبر دس کی طاقت کے حساب سے غلط ہو۔
حدود
key کے بغیر کالز فی IP ایڈریس، روزانہ محدود ہیں۔
- 10 میٹرڈ کالز: ratios، screen، verify اور ہر قیمت والا route، جیسے standardized statements، segments اور KPI
- 1,000 filing-layer ریڈز: as-reported facts، filings، ownership اور prices
- 1,000 metadata ریڈز: directory، profiles، metrics، proofs اور changes
ہر جواب میں RateLimit-Limit، RateLimit-Remaining اور RateLimit-Resetہیں۔ 429 میں Retry-Afterہے۔
بغیر چابی کے api.financial.md پر کالز پر کبھی کوئی فیس نہیں لی جاتی۔ API چابیاں ٹرمینل + ایجنٹ پلانز کے ساتھ آتی ہیں؛ API کیزدیکھیں۔ ایجنٹس agent.financial.mdپر فی کال بھی ادائیگی کر سکتے ہیں۔ پرائسنگدیکھیں۔
کیا شامل ہے
کوریج وہ کمپنیاں ہیں جو SEC کے ساتھ فائل کرتی ہیں اور آج US ایکسچینج پر لسٹ ہوتی ہیں۔
- ان فائلرز کے لیے معیاری بیانات موجود ہیں جو US GAAPکے تحت رپورٹ کرتے ہیں۔
- وہ فائلرز جو IFRS کے تحت رپورٹ کرتے ہیں، جیسے بہت سی غیر ملکی کمپنیاں جو Form 20-F یا 40-F فائل کرتی ہیں، ان کے پاس فائلنگز ہوتی ہیں لیکن ابھی تک معیاری بیانات نہیں ہوتے۔
- جو کمپنیاں ڈی لسٹ ہو چکی ہیں، وہ اپنی اسٹیٹمنٹس اور فائلنگز کے ساتھ ڈائریکٹری میں موجود ہیں۔ انہیں CIK کے ذریعے تلاش کریں: ان کے لیے ticker lookup نہیں ہوتا اور نہ ہی prices، اس لیے price history صرف آج لسٹڈ کمپنیوں تک محدود ہے۔
- ملکیت کا ڈیٹا 1 جولائی 2026 سے کی گئی فائلنگز سے آتا ہے، اور ہر روز 13:00 UTC پر EDGAR روزانہ انڈیکس سے اپ ڈیٹ ہوتا ہے: کور شدہ کمپنیوں کے Form 3، Form 4 اور Form 5 سے insider transactions، اور ہر 13F-HR سے، اس لیے نئی سہ ماہی کی 13F رپورٹس مینیجرز کے فائل کرتے ہی آ جاتی ہیں۔ 13F پوزیشن کسی کمپنی سے صرف اس وقت جوڑی جاتی ہے جب Schedule 13D یا 13G کور اس کی سیکیورٹی کا نام لے۔ 30 جون 2026 کو ختم ہونے والی سہ ماہی کے لیے اس طرح رپورٹ شدہ قدر کا 80 فیصد جوڑا جاتا ہے؛ باقی پوزیشنز مینیجر کے پورٹ فولیو میں issuer name کے تحت ویسے ہی ظاہر ہوتی ہیں جیسے فائل کیا گیا ہو۔
- consensus estimates اور earnings call transcripts فراہم نہیں کیے جاتے: دونوں licensed data ہیں۔ segments رپورٹ کے مطابق فراہم کیے جاتے ہیں، اور news 8-K فائلنگز کی فیڈ ہے۔
جب کوئی کمپنی جانی پہچانی ہو لیکن کوئی ڈیٹا سیٹ غائب ہو، تو API not_covered کا جواب دیتا ہے اور اپنے پاس موجود ڈیٹا سیٹس کی فہرست دیتا ہے۔
MCP سرور
MCP سرور اسی API کو 57 read-only tools میں پیش کرتا ہے۔ یہ MCP Streamable HTTP بولتا ہے اور کسی اکاؤنٹ کی ضرورت نہیں ہوتی۔
https://mcp.financial.md/mcpMCP گائیڈ ٹولز کی فہرست دیتا ہے۔ سرور کارڈ رجسٹریز کے لیے ہے۔
غلطیاں
ایک error { "error": { code, message, docs, request_id, remedies } } ہوتا ہے۔ remedies فہرست بتاتی ہے کہ آگے کیا کرنا ہے۔ error reference ہر code کی وضاحت کرتا ہے۔