API এবং MCP ডকস
FinancialMD SEC ফাইলিং থেকে তৈরি আর্থিক বিবৃতি সরবরাহ করে। প্রতিটি সংখ্যা যে ফাইলিং থেকে এসেছে তার সঙ্গে লিঙ্ক করা, এবং প্রতিটি সংখ্যা যেকোনো তারিখে যেমনটি জানা ছিল তেমনভাবে পড়া যায়। কোনো অ্যাকাউন্টের প্রয়োজন নেই।
প্রথম কল করুন
API হলো HTTPS-এর উপর JSON। এই কলটি Apple-এর শেষ পাঁচটি বার্ষিক আয় বিবরণী ফেরত দেয়। এর জন্য কোনো কী লাগে না।
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-এর মধ্যে একটি।
একটি কোম্পানি নির্দিষ্ট করুন
প্রতিটি কোম্পানির রুট একটি company প্যারামিটার নেয়।
ticker:AAPL, অথবা এক্সচেঞ্জের নাম দিতেticker:AAPL.XNAScik:320193, SEC-এর কোম্পানি নম্বরfmd_<id>, কোম্পানিটিকে FinancialMD যে id দেয়
একটি সাধারণ AAPL টিকার হিসেবে এবং শুধু অঙ্কগুলো CIK হিসেবে পড়া হয়। meta.company.matched_by-এ কী মেলানো হয়েছে তা প্রতিক্রিয়ায় বলা থাকে।
একটি মান পড়ুন
একটি সফল প্রতিক্রিয়া হলো { data, meta }। data-এর ভেতরের কোনো সংখ্যা কখনও একা থাকে না। এটি একটি মান অবজেক্ট:
{
"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 হলো সেই সময়সীমা, যার মধ্যে এটি সর্বশেষ ফাইল করা সংখ্যা ছিল। restated কেবল তখনই true হয়, যখন পরবর্তী কোনো ফাইলিং সেই সংখ্যাটি পরিবর্তন করে; restatement_kind তখন জানায় কীভাবে। proof.id GET /proof/{id}-এ মানটির পেছনের ফাইলিং এবং raw facts-এ resolve করে।
অতীতকে যেমন জানা ছিল সেভাবেই পড়ুন
- যে কোনো read রুটে
as_of=2024-06-30দিলে সেই মুহূর্তে যা জানা ছিল তা ফেরত দেয়। 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 | একটি ফাইলিং যে সব ম্যাপ করা ফ্যাক্টে ট্যাগ করেছে |
GET /v1/filing/{accession}/document | EDGAR-এ ফাইলিংয়ের পৃষ্ঠাগুলোর লিঙ্ক, বা এর মূল নথি HTML, PDF বা পৃষ্ঠার ছবি হিসেবে |
GET /v1/company/ownership/insiders | Form 3, Form 4 এবং Form 5 থেকে ইনসাইডার লেনদেন |
GET /v1/company/ownership/institutional | ত্রৈমাসিকভিত্তিতে একটি কোম্পানির Form 13F হোল্ডাররা |
GET /v1/ownership/institutional/holders | Form 13F ম্যানেজাররা |
GET /v1/ownership/institutional/holdings | একটি ত্রৈমাসিকের জন্য এক ম্যানেজারের 13F পোর্টফোলিও |
GET /v1/company/splits | ফাইলিংয়ে যেমন আছে তেমন স্টক স্প্লিট, এবং দাম সেগুলো নিশ্চিত করে কি না |
GET /v1/company/dividends | ফাইলিং অনুযায়ী প্রতিটি পিরিয়ডে ঘোষিত বা পরিশোধিত শেয়ারপ্রতি লভ্যাংশ |
GET /v1/events_calendar | আয় প্রকাশনা (8-K Item 2.02 filed) এবং মডেল-প্রত্যাশিত তারিখ |
GET /v1/company/events | 8-K আইটেম: একটি ফাইলিং-ভিত্তিক ইভেন্ট ফিড |
GET /v1/news | সব কভার করা কোম্পানির 8-K ফাইলিং, নতুনতম আগে, ইভেন্টের ধরন ও গুরুত্বের স্তরসহ |
GET /v1/news/feed | প্রতিটি ইভেন্ট-বহনকারী SEC ফর্ম থেকে FinancialMD-এর নিজস্ব ইভেন্ট ফিড, নিয়ম-তৈরি শিরোনাম, গুরুত্ব ও মূল সংখ্যাসহ। ওয়্যার নিউজ নয় |
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 full-text search) |
GET /v1/coverage | প্রতিটি ডেটাসেট তার স্ট্যাটাসসহ: served, not covered (licensed) বা not built, এবং এর বদলে কী ব্যবহার করবেন |
GET /v1/company/estimates | FinancialMD-এর নিজস্ব মডেল-ভিত্তিক বেসলাইন অনুমান, ইন্টারভ্যাল ও একটি পয়েন্ট-ইন-টাইম ট্র্যাক রেকর্ডসহ, ফাইলিংয়ে যেমন বলা আছে সেই কোম্পানির গাইডেন্স, এবং বর্ণনামূলক সিগন্যাল। 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 | মার্কিন হাউসের সদস্যদের ট্রেড, যা periodic transaction reports-এ রিপোর্ট করা হয়েছে, ফাইল অনুযায়ী, অফিসিয়াল রিপোর্টসহ। কখনও মূল্যায়িত নয়। ব্যবহার 5 U.S.C. 13107(c)(1) দ্বারা সীমিত: data.notice পড়ুন |
GET /v1/company/segments | যেমন-রিপোর্ট করা সেগমেন্ট তথ্য (ব্যবসা, ভূগোল, পণ্য) |
GET /v1/company/ownership/insider_holders | সর্বশেষ Form 4 বা 5-এর পরে প্রতিটি ইনসাইডারের কী মালিকানা ছিল |
GET /v1/company/ownership/funds | তাদের সর্বশেষ N-PORT-এ কোম্পানিটি ধারণ করা ফান্ডগুলি |
GET /v1/funds | সর্বশেষ রিপোর্টসহ Form N-PORT ফান্ডগুলি |
GET /v1/fund/holdings | একটি ফান্ডের Form N-PORT হোল্ডিংস |
GET /v1/company/kpis | কোম্পানি-রিপোর্ট করা adjusted এবং operating metrics, প্রতিটির উদ্ধৃতিসহ |
GET /v1/company/dividend_events | ফাইল অনুযায়ী তারিখসহ নগদ লভ্যাংশ |
GET /v1/company/ownership/insider_holdings | Form 3, 4 এবং 5-এর হোল্ডিং লাইনগুলো |
GET /v1/fund/profile | N-CEN থেকে একটি ফান্ডের ধরন এবং এর শেয়ার ক্লাসগুলোর ফি |
GET /v1/fund/nav | SEC ফাইলিং থেকে রিপোর্ট মাস অনুযায়ী একটি ফান্ডের নেট সম্পদ, আমাদের রিটার্ন ইনডেক্সসহ প্রতিটি ক্লাসের রিপোর্ট করা মাসিক রিটার্ন, এবং ক্লোজড-এন্ড NAV প্রতি শেয়ার। দৈনিক NAV দেওয়া হয় না |
GET /v1/identifiers/xref | একটি identifier দিলে, সেটি যে কোম্পানি বা ফান্ডকে নির্দেশ করে এবং অন্য উন্মুক্ত identifierগুলো, প্রতিটির উৎসসহ |
GET /v1/identifiers/master | প্রতিটি কোম্পানির উন্মুক্ত identifier, পেজ করা |
GET /v1/company/stock_prices/returns | প্রাইস রিটার্ন, মোট রিটার্ন এবং স্ট্যান্ডার্ড উইন্ডোতে সর্বাধিক ড্রডাউন, দিনের শেষের বার এবং SEC-ফাইল করা স্প্লিট এবং ডিভিডেন্ড থেকে গণনা করা হয় |
GET /v1/company/identifiers | LEI এবং FIGI, তাদের প্রমাণসহ |
GET /v1/company/stock_prices | শুধু IEX-এ হওয়া ট্রেড থেকে তৈরি দৈনিক bar। consolidated tape নয়। ডিফল্টভাবে raw; adjust=splits বা adjust=total_return adjusted মান যোগ করে |
GET /v1/screen | সর্বশেষ-পর্যায়ের metrics-এ অন্তর্ভুক্ত সব কোম্পানিকে স্ক্রিন করুন |
POST /v1/verify | ফাইল করা মানের বিপরীতে একটি নম্বর পরীক্ষা করুন |
GET /v1/changes | যেসব তথ্যের জ্ঞান একটি নির্দিষ্ট সময়ের পর থেকে উন্মুক্ত হয়েছে |
POST /v1/request-data | আপনার কোন ডেটা প্রয়োজন ছিল কিন্তু খুঁজে পাননি, আমাদের জানান। কোনো key লাগে না, কখনও চার্জ করা হয় না, সাপ্তাহিক পর্যালোচনা করা হয়। কীভাবে অনুরোধ করবেন দেখুন |
GET /v1/request-data | POST /v1/request-data-এর body নেয় |
GET /v1/request-data/{id} | একটি অনুরোধের অবস্থা: new, triaged, planned, done বা wontfix |
GET /v1/requested | অনুরোধ করা এবং সরবরাহ করা: গণনাসহ পর্যালোচিত অনুরোধ, জমাদানকারীর কোনও বিস্তারিত নেই |
GET /proof/{id} | একটি সরবরাহকৃত মানের প্রমাণ |
GET /v1/company/line_items | লেবেল ও পিরিয়ড অনুযায়ী একটি রিপোর্ট করা লাইন: যেমন-রিপোর্ট করা বিস্তারিত লাইন, সেগমেন্ট পরিসংখ্যান, কোম্পানির metrics এবং guidance |
GET /v1/screen/nl | একটি সরল-ভাষার screen: প্রশ্নটি screen filter-এ পার্স করা হয় (একটি AI model বা নির্দিষ্ট rules দ্বারা, label-সহ) এবং GET /v1/screen হিসেবে চালানো হয় |
GET /v1/ask | একটি কোম্পানি সম্পর্কে তার নিজস্ব ফাইল করা মান থেকে AI-লিখিত উত্তর, যেখানে প্রতিটি সংখ্যা উদ্ধৃত তথ্যের সঙ্গে মিলিয়ে দেখা হয় |
GET /v1/news/summary | FinancialMD-এর নিজস্ব event feed থেকে এক দিনের filing-ভিত্তিক খবর, বা একটি কোম্পানির সাম্প্রতিক ঘটনাগুলোর AI-লিখিত সারাংশ; প্রতিটি bullet তার filing উদ্ধৃত করে এবং প্রতিটি সংখ্যা সেগুলোর সঙ্গে মিলিয়ে দেখা হয় |
GET /v1/company/ratios/forward | আমাদের নিজস্ব model-based estimate-এর ওপর forward valuation ratio (label-সহ model output, কখনও consensus নয়), estimate, তার interval এবং track record-সহ |
GET /v1/company/technicals | প্রযুক্তিগত সূচক (moving averages, RSI, MACD, Bollinger bands, ATR, close range), যা single-venue daily bar এবং SEC-filed split থেকে গণনা করা হয় |
GET /v1/pre_ipo | যেসব কোম্পানি public হওয়ার জন্য ফাইল করেছে: কোনও periodic report-এর আগে ফাইলে S-1 বা F-1 থাকা registrant, status, proposed ticker এবং তারিখসহ |
GET /v1/pre_ipo/{cik} | একটি pre-IPO registrant: status ও তার rule, registration filing, এটি ট্যাগ করা আর্থিক পরিসংখ্যান, এবং prospectus থেকে পড়া offering terms |
GET /v1/fx_rates | European Central Bank-এর public file থেকে দৈনিক reference exchange rate, ইউরোর মাধ্যমে যেকোনও সরবরাহকৃত মুদ্রার বিপরীতে অন্য যেকোনও মুদ্রা; reference rate, tradable quote নয় |
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 document-এ প্রতিটি প্যারামিটার ও response 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}'উত্তরে matches, differs বা unknown-এর একটি verdict, প্রমাণসহ ফাইল করা মান, পার্থক্য, এবং আপনার সংখ্যা দশের ঘাতের কারণে ভুল হলে একটি scale_hint থাকে।
সীমাবদ্ধতা
কোনও key ছাড়া কলগুলো IP ঠিকানা-প্রতি, প্রতিদিন সীমিত।
- 10টি metered call: ratios, screen, verify এবং প্রতিটি মূল্যযুক্ত route, যেমন standardized statements, segments ও KPI
- 1,000টি filing-layer read: as-reported facts, filings, ownership এবং prices
- 1,000টি metadata read: directory, profiles, metrics, proofs এবং changes
প্রতিটি response-এ RateLimit-Limit, RateLimit-Remaining এবং RateLimit-Reset থাকে। 429 response-এ Retry-After থাকে।
api.financial.md-এ key ছাড়া কলের জন্য কখনও চার্জ নেওয়া হয় না। API key Terminal + Agent plan-এর সঙ্গে আসে; API keys দেখুন। এজেন্টরা agent.financial.md-এ call-প্রতি অর্থও দিতে পারে। Pricing দেখুন।
কী কী কভার করা হয়
কভারেজে আছে সেই কোম্পানিগুলো, যারা SEC-এ ফাইল করে এবং বর্তমানে একটি US exchange-এ তালিকাভুক্ত।
- US GAAP-এর অধীনে রিপোর্ট করা filer-দের জন্য standardized statement আছে।
- IFRS-এর অধীনে রিপোর্ট করা filer-দের, যেমন অনেক বিদেশি কোম্পানি যারা 20-F বা 40-F ফাইল করে, ফাইলিং আছে কিন্তু এখনও standardized statement নেই।
- যেসব কোম্পানি delist হয়েছে, তারা তাদের statement ও filing-সহ directory-তে আছে। CIK দিয়ে তাদের খুঁজুন: তাদের জন্য ticker lookup নেই এবং price-ও নেই, তাই price history শুধু আজ তালিকাভুক্ত কোম্পানিগুলোকেই কভার করে।
- মালিকানার ডেটা 1 জুলাই, 2026 থেকে করা ফাইলিং থেকে আসে, এবং EDGAR daily index থেকে প্রতিদিন 13:00 UTC-তে আপডেট হয়: কভার করা কোম্পানিগুলোর Form 3, Form 4 এবং Form 5 থেকে insider transaction, এবং প্রতিটি 13F-HR, তাই নতুন ত্রৈমাসিকের 13F report ম্যানেজাররা ফাইল করার সঙ্গে সঙ্গে আসে। একটি 13F position কেবল তখনই একটি কোম্পানির সঙ্গে যুক্ত হয়, যখন কোনও 13D বা 13G কভারে তার security-র নাম থাকে। 30 জুন, 2026-এ শেষ হওয়া ত্রৈমাসিকের জন্য এতে reported value-এর 80 percent যুক্ত হয়; বাকি position-গুলো ফাইল করা অনুযায়ী issuer name-এ একজন ম্যানেজারের portfolio-তে দেখা যায়।
- Consensus estimate এবং earnings call transcript দেওয়া হয় না: দুটোই licensed data। segment দেওয়া হয় reported as-is, আর news হলো 8-K filing-এর feed।
যখন কোনও কোম্পানি পরিচিত কিন্তু একটি dataset অনুপস্থিত, তখন API not_covered ফেরত দেয় এবং তার কাছে থাকা dataset-গুলোর তালিকা দেয়।
MCP সার্ভার
MCP server একই API-কে 57টি read-only tool হিসেবে দেয়। এটি MCP Streamable HTTP-এ কথা বলে এবং কোনও account লাগে না।
https://mcp.financial.md/mcpMCP গাইড সরঞ্জামগুলি তালিকাভুক্ত করে। সার্ভার কার্ড রেজিস্ট্রিগুলির জন্য।
ত্রুটি
একটি error হলো { "error": { code, message, docs, request_id, remedies } }। remedies তালিকা পরের ধাপে কী করতে হবে তা বলে। error reference প্রতিটি code ব্যাখ্যা করে।