İçeriğe geç

API ve MCP belgeleri

FinancialMD, SEC bildirimlerinden oluşturulan finansal tablolar sunar. Her sayı, geldiği bildirime bağlanır ve her sayı herhangi bir tarihte bilindiği şekliyle okunabilir. Hesap gerekmez.

İlk çağrıyı yap

API, HTTPS üzerinden JSON kullanır. Bu çağrı Apple'ın son beş yıllık gelir tablosunu döndürür. Anahtar gerekmez.

curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"

Tablo türü income_statement, balance_sheet, cash_flow veya supplemental seçeneklerinden biridir. Dönem türü ise annual, quarterly, ltm veya ytd seçeneklerinden biridir.

Bir şirket belirtin

Her şirket rotası company parametresini alır.

  • ticker:AAPL veya borsayı belirtmek için ticker:AAPL.XNAS
  • cik:320193, SEC şirket numarası
  • fmd_<id>, FinancialMD'nin şirkete verdiği kimlik

Tek başına AAPL bir ticker olarak, yalnızca rakamlardan oluşan değerler ise CIK olarak okunur. Yanıt, neyin eşleştiğini meta.company.matched_by içinde belirtir.

Bir değer okuyun

Başarılı bir yanıt { data, meta }. data içindeki bir sayı asla çıplak değildir. Bu bir değer nesnesidir:

{
  "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, bunun en son bildirilmiş rakam olduğu zaman aralığıdır. restated, yalnızca daha sonraki bir bildirim rakamı değiştirdiğinde true olur; restatement_kind ise bunun nasıl olduğunu belirtir. proof.id, GET /proof/{id} ile değerin arkasındaki bildirime ve ham verilere çözümlenir.

Geçmişi bilindiği gibi okuyun

  • as_of=2024-06-30 herhangi bir okuma rotasında o anda bilinenleri geri getirir.
  • original=true, her dönemin ilk bildirilen sürümünü döndürür.
  • history=true, her dönemin tüm sürümlerini en eskiden başlayarak döndürür.
  • GET /v1/changes?since=<timestamp> o tarihten beri öğrenilen olguları listeler.

Uç noktalar

Uç noktaNe döndürür
GET /v1/companiesŞirket dizini, filtreler ve sayfalama ile
GET /v1/company/profileProfil, kotasyonlar ve mevcut veri setleri
GET /v1/company/metricsŞirket şablonunun kavram satırları
GET /v1/company/financials/{statement}/standardizedStandartlaştırılmış bir tablo
GET /v1/company/financials/{statement}/as_reportedBildirim sahibinin etiketli kendi satır kalemleri
GET /v1/company/ratiosTablolardan hesaplanan oranlar ve girdilerinin kanıtları
GET /v1/company/ratios/daily/{ratio_id}Dönemler boyunca seri halinde tek bir oran
GET /v1/company/filingsBir şirketin bildirim dizini
GET /v1/filing/{accession}Tek bir bildirim
GET /v1/filing/{accession}/factsBir bildirimin etiketlediği eşlenmiş tüm olgular
GET /v1/filing/{accession}/documentBir bildirimin EDGAR üzerindeki sayfalarına veya birincil belgesine HTML, PDF ya da sayfa görüntüleri olarak bağlantılar
GET /v1/company/ownership/insidersForm 3, 4 ve 5'ten içeriden yapılan işlemler
GET /v1/company/ownership/institutionalBir şirketin çeyrek bazında Form 13F sahipleri
GET /v1/ownership/institutional/holdersForm 13F yöneticileri
GET /v1/ownership/institutional/holdingsBir yöneticinin bir çeyreğe ait 13F portföyü
GET /v1/company/splitsBildirimde yer aldığı şekliyle hisse bölünmeleri ve fiyatların bunları doğrulayıp doğrulamadığı
GET /v1/company/dividendsHer dönemde bildirilen veya ödenen hisse başına temettüler, bildirildiği şekliyle
GET /v1/events_calendarKazanç açıklamaları (8-K Madde 2.02 bildirimi) ve modelin beklediği tarihler
GET /v1/company/events8-K öğeleri: bildirime dayalı bir olay akışı
GET /v1/newsKapsanan tüm şirketlerin 8-K bildirimleri, en yeniden eskiye, olay türleri ve önem düzeyiyle birlikte
GET /v1/news/feedFinancialMD'nin, olay içeren tüm SEC formlarından oluşturduğu kendi olay akışı; kurallarla üretilmiş başlıklar, önem düzeyi ve temel rakamlarla birlikte. Haber ajansı akışı değildir
GET /v1/news/issuer_releasesİhraççıların kendileri hakkında yayımladığı duyurular: SEC ekleri ile ihraççının kendi akışındaki başlık ve bağlantı
GET /v1/company/call_materialsİhraççının SEC'ye sunduğu kazanç çağrısı materyalleri: açıklamalar, hazırlanmış konuşma metinleri, mektuplar, sunumlar ve sunulduysa bir transkript
GET /v1/call_material/{id}İhraççının sunduğu tek bir belge; bölümler, konuşmacı sıraları ve konu etiketleriyle pasajlar halinde
GET /v1/calls_calendarİhraççıların SEC bildirimlerinde duyurduğu kazanç çağrıları ve ihraççının kendi webcast sayfasına bağlantı
GET /v1/search/filings2001'den bu yana EDGAR belgelerinde tam metin araması (SEC EDGAR tam metin araması)
GET /v1/coverageHer veri seti ve durumu: sunuluyor, kapsam dışı (lisanslı) veya oluşturulmamış; ayrıca bunun yerine ne kullanılacağı
GET /v1/company/estimatesFinancialMD'nin kendi model tabanlı baz tahminleri; aralıklar, belirli bir tarih itibarıyla (point-in-time) performans geçmişi, şirketin bildirimlerinde belirttiği yönlendirme ve açıklayıcı sinyaller. Konsensüs değildir, analist tahminleri değildir. yönteme bakın
GET /v1/company/estimates/consensusKapsanmıyor: konsensüs tahminleri lisanslıdır. Alternatiflerle birlikte 404 not_covered döndürür
GET /v1/company/analyst_ratingsKapsanmıyor: analist derecelendirmeleri lisanslıdır. 404 not_covered döndürür
GET /v1/company/transcriptsKapsanmıyor: çağrı transkriptleri lisanslıdır. 404 not_covered döndürür
GET /v1/company/stock_prices/intradayKapsanmıyor: gerçek zamanlı ve gün içi fiyatlar lisanslıdır. 404 not_covered döner
GET /v1/company/logoŞirketi tanımlamak için bir logo: atfıyla birlikte açık lisanslı bir dosya veya oluşturulmuş bir kutucuk. JSON, SVG veya PNG
GET /v1/politician_tradesABD Temsilciler Meclisi üyelerinin, resmi raporla birlikte sunulduğu haliyle periyodik işlem raporlarında bildirilen işlemleri. Hiçbir zaman fiyatlandırılmaz. Kullanım 5 U.S.C. 13107(c)(1) ile sınırlıdır: data.notice değerini okuyun
GET /v1/company/segmentsBildirildiği haliyle segment verileri (iş kolu, coğrafya, ürün)
GET /v1/company/ownership/insider_holdersHer içeriden kişinin en son Form 4 veya 5 sonrasında sahip olduğu varlıklar
GET /v1/company/ownership/fundsEn son Form N-PORT bildirimlerinde şirketi tutan fonlar
GET /v1/fundsEn son raporlarıyla birlikte Form N-PORT fonları
GET /v1/fund/holdingsBir fonun Form N-PORT varlıkları
GET /v1/company/kpisŞirket tarafından bildirilen düzeltilmiş ve faaliyet metrikleri; her biri atfıyla birlikte
GET /v1/company/dividend_eventsNakit temettüler ve bildirildiği haliyle tarihleri
GET /v1/company/ownership/insider_holdingsForm 3, 4 ve 5'in sahiplik satırları
GET /v1/fund/profileN-CEN'e göre bir fonun türü ve hisse sınıflarının ücretleri
GET /v1/fund/navBir fonun rapor ayına göre net varlıkları, her sınıfın raporlanan aylık getirisi ve buna karşılık gelen getiri endeksimiz ile SEC bildirimlerinden alınan kapalı uçlu fonlar için hisse başına NAV. Günlük NAV sunulmaz
GET /v1/identifiers/xrefBir tanımlayıcı verildiğinde, adlandırdığı şirket veya fon ile diğer açık tanımlayıcılar; her biri kaynağıyla birlikte
GET /v1/identifiers/masterHer şirketin açık tanımlayıcıları, sayfalanmış
GET /v1/company/stock_prices/returnsFiyat getirisi, toplam getiri ve standart dönemler üzerindeki maksimum düşüş; gün sonu barları ile SEC'e sunulan split ve temettülerden hesaplanır
GET /v1/company/identifiersLEI ve FIGI kanıtlarıyla
GET /v1/company/stock_pricesYalnızca I'deki işlemlerden oluşturulan günlük barlar. Konsolide bant değildir. Varsayılan olarak hamdır; adjust=splits veya adjust=total_return düzeltilmiş değerler ekler
GET /v1/screenKapsanan tüm şirketleri en son dönem metriklerine göre tarayın
POST /v1/verifyBir sayıyı bildirilen değerle karşılaştırın
GET /v1/changesBelirli bir zamandan beri bilinir hale gelen veriler
POST /v1/request-dataİhtiyacınız olup da bulamadığınız veriyi bize söyleyin. Anahtar yok, hiçbir zaman ücret alınmaz, haftalık incelenir. Nasıl talep edilir sayfasına bakın
GET /v1/request-dataPOST /v1/request-data gövdesi şunları alır
GET /v1/request-data/{id}Bir talebin durumu: new, triaged, planned, done veya wontfix
GET /v1/requestedTalep edilen ve teslim edilenler: incelenmiş talepler, sayılarıyla birlikte; gönderene ait ayrıntılar yok
GET /proof/{id}Sunulan bir değer için kanıt
GET /v1/company/line_itemsEtiket ve döneme göre tek bir bildirilen satır: bildirildiği haliyle detay satırları, segment rakamları, şirket metrikleri ve yönlendirme
GET /v1/screen/nlSade dilli bir tarama: soru, tarama filtrelerine (bir AI modeliyle veya etiketli sabit kurallarla) ayrıştırılır ve GET /v1/screen olarak çalıştırılır
GET /v1/askBir şirket hakkında, kendi bildirilen değerlerine dayanan AI tarafından yazılmış bir yanıt; her sayı atıf yapılan verilerle karşılaştırılır
GET /v1/news/summaryFinancialMD'nin kendi olay akışından, bir günün bildirim bazlı haberlerinin veya bir şirketin son olaylarının AI tarafından yazılmış özeti; her madde ilgili bildirimlerine atıf yapar ve her sayı bunlara karşı kontrol edilir
GET /v1/company/ratios/forwardKendi model tabanlı tahminlerimize dayalı ileriye dönük değerleme oranları (etiketli model çıktısı, asla consensus değil); tahmin, aralığı ve geçmiş performansıyla birlikte
GET /v1/company/technicalsTeknik göstergeler (hareketli ortalamalar, RSI, MACD, Bollinger bantları, ATR, kapanış aralığı); tek bir işlem yerinin günlük barları ve SEC'e sunulan splitlerden hesaplanır
GET /v1/pre_ipoHalka açılmak için başvuru yapmış şirketler: herhangi bir periyodik rapordan önce dosyada S-1 veya F-1 bulunan kayıt sahipleri; durum, önerilen ticker ve tarihlerle birlikte
GET /v1/pre_ipo/{cik}IPO öncesi tek bir kayıt sahibi: durum ve kuralı, kayıt bildirimleri, etiketlediği finansal rakamlar ve izahnameden okunan arz şartları
GET /v1/fx_ratesAvrupa Merkez Bankası'nın açık dosyalarından günlük referans döviz kurları; euro üzerinden sunulan herhangi bir para biriminden diğerine. Referans kurlardır, işlem yapılabilir kotasyonlar değil
GET /v1/researchCC BY 4.0 lisanslı bağımsız araştırma raporları; yayıncılarının sitesinde de ücret ödemeden okunabilir: şirket, koleksiyon, dil, kelime ve tarihe göre arama yapılabilir, her birinde raporun kendi sözleriyle bir özet vardır
GET /v1/research/{id}Bir araştırma raporunun tamamı, yapılandırılmış Markdown olarak: bölümler, tickerlar, tarih, kaynaklar, lisans ve alıntı yaparken korunması gereken atıf
POST /v1/feedbackNeyin işe yaradığını ve neyin yaramadığını bize söyleyin: bir not, bir derecelendirme veya nedenler. Anahtar gerekmez, hiçbir zaman ücret alınmaz. GET /v1/feedback gövdeyi açıklar
POST /v1/data-errorsYanlış olduğuna inandığınız bir sayıyı bildirin. Bu sayı, anında sunduğumuz veriyle ve her gün SEC bildirimiyle karşılaştırılır. Ardından GET /v1/data-errors/{id} ile takip edin

OpenAPI belgesi tüm parametreleri ve yanıt şemalarını içerir. llms.txt, llms-full.txt ve beceri dosyası ajanlar için aynı şeyi söyler; https://api.financial.md/docs etkileşimli referanstır ve https://api.financial.md/changelog değişiklikleri listeler.

Bir sayıyı kontrol edin

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}'

Yanıtta verdict olarak matches, differs veya unknown, bildirilen değer ve kanıtı, aradaki fark ve sayınız on kuvveti kadar hatalıysa bir scale_hint bulunur.

Sınırlar

Anahtarsız çağrılar, IP adresi başına günlük olarak sınırlandırılır.

  • 10 ölçülü arama: oranlar, tarama, doğrulama ve fiyatlı her rota; örneğin standartlaştırılmış tablolar, segmentler ve KPI'lar
  • 1,000 bildirim katmanı okuması: bildirildiği şekliyle veriler, bildirimler, sahiplik ve fiyatlar
  • 1,000 metadata okuması: dizin, profiller, metrikler, kanıtlar ve değişiklikler

Her yanıt RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset taşır. 429 yanıtı ise Retry-After taşır.

api.financial.md üzerinde anahtarsız çağrılar için hiçbir zaman ücret alınmaz. API anahtarları Terminal + Agent planlarıyla birlikte gelir; bkz. API anahtarları. Agent'lar ayrıca agent.financial.md üzerinde çağrı başına ödeme yapabilir. Bkz. Fiyatlandırma.

Neler kapsanır

Kapsam, bugün SEC'e bildirim yapan ve bir US borsasında listelenen şirketlerdir.

  • Standartlaştırılmış tablolar, US GAAP kapsamında raporlama yapan bildirim sahipleri için mevcuttur.
  • IFRS kapsamında raporlama yapan, örneğin Form 20-F veya 40-F sunan birçok yabancı şirketin bildirimleri vardır, ancak henüz standartlaştırılmış tabloları yoktur.
  • Kottan çıkarılmış şirketler, tabloları ve bildirimleriyle birlikte dizinde yer alır. Bunları CIK ile arayın: ticker araması yoktur ve fiyatları da yoktur; bu yüzden fiyat geçmişi yalnızca bugün listelenen şirketleri kapsar.
  • Sahiplik verileri, 1 Temmuz 2026'dan beri yapılan bildirimlerden gelir ve EDGAR günlük endeksinden her gün 13:00 UTC'de güncellenir: kapsanan şirketlerin Form 3, 4 ve 5'lerindeki içeriden işlemler ile tüm Form 13F-HR'ler alınır; böylece yeni bir çeyreğin 13F raporları yöneticiler bunları sundukça gelir. Bir 13F pozisyonu, yalnızca bir Schedule 13D veya 13G kapağı menkul kıymetinin adını verdiğinde bir şirkete bağlanır. 30 Haziran 2026'da biten çeyrek için bu, bildirilen değerin yüzde 80'ini bağlar; diğer pozisyonlar bir yöneticinin portföyünde, bildirildiği şekliyle ihraççı adı altında görünür.
  • Konsensüs tahminleri ve kazanç görüşmesi dökümleri sunulmaz: ikisi de lisanslı veridir. Segmentler bildirildiği gibi sunulur ve haberler 8-K bildirimlerinin akışıdır.

Bir şirket biliniyor ama bir veri kümesi eksikse, API not_covered yanıtı verir ve elindeki veri kümelerini listeler.

MCP sunucusu

MCP sunucusu, aynı API'yi 57 salt okunur araç olarak sunar. MCP Streamable HTTP konuşur ve hesap gerektirmez.

https://mcp.financial.md/mcp

MCP rehberi araçları listeler. sunucu kartı kayıt dizinleri içindir.

Hatalar

Bir hata { "error": { code, message, docs, request_id, remedies } } biçimindedir. remedies listesi sırada ne yapılacağını söyler. hata referansı her kodu açıklar.