مواد پر جائیں

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.XNAS
  • cik: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}/documentEDGAR پر فائلنگ کے صفحات کے لنکس، یا اس کی بنیادی دستاویز بطور 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/events8-K آئٹمز: فائلنگ پر مبنی ایونٹ فیڈ
GET /v1/newsہر کور شدہ کمپنی کی 8-K فائلنگز، سب سے نئی پہلے، ایونٹ کی اقسام اور اہمیت کی سطح کے ساتھ
GET /v1/news/feedFinancialMD کی اپنی ایونٹ فیڈ، ہر ایونٹ رکھنے والے 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/filings2001 سے EDGAR دستاویزات کی مکمل متن تلاش (SEC EDGAR مکمل متن کی تلاش)
GET /v1/coverageہر ڈیٹا سیٹ اپنی حیثیت کے ساتھ: فراہم کردہ، کور نہیں (لائسنس یافتہ) یا تیار نہیں، اور اس کے بجائے کیا استعمال کریں
GET /v1/company/estimatesFinancialMD کے اپنے ماڈل پر مبنی بنیادی تخمینے، وقفوں اور مخصوص وقت کے مطابق (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/fundsForm 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/profileN-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/identifiersLEI اور 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-dataPOST /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/summaryFinancialMD کی اپنی ایونٹ فیڈ سے ایک دن کی فائلنگ پر مبنی خبروں، یا ایک کمپنی کے حالیہ واقعات، کا 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/mcp

MCP گائیڈ ٹولز کی فہرست دیتا ہے۔ سرور کارڈ رجسٹریز کے لیے ہے۔

غلطیاں

ایک error { "error": { code, message, docs, request_id, remedies } } ہوتا ہے۔ remedies فہرست بتاتی ہے کہ آگے کیا کرنا ہے۔ error reference ہر code کی وضاحت کرتا ہے۔