Documentazione API e MCP
FinancialMD fornisce bilanci costruiti a partire dai documenti depositati presso la SEC. Ogni numero rimanda al documento depositato presso la SEC da cui proviene, e ogni numero può essere letto come era noto in qualsiasi data. Non è necessario un account.
Effettua una prima chiamata
L'API utilizza JSON su HTTPS. Questa chiamata restituisce gli ultimi cinque conti economici annuali di Apple. Non richiede una chiave.
curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"Il prospetto è uno tra income_statement, balance_sheet, cash_flow e supplemental. Il tipo di periodo è uno tra annual, quarterly, ltm e ytd.
Specifica una società
Ogni route relativa a una società accetta un parametro company.
ticker:AAPL, oppureticker:AAPL.XNASper specificare la borsacik:320193, il numero identificativo della società presso la SECfmd_<id>, l'identificativo che FinancialMD assegna alla società
Un semplice AAPL viene interpretato come ticker e una sequenza di sole cifre come CIK. La risposta indica il criterio di corrispondenza in meta.company.matched_by.
Leggi un valore
Una risposta riuscita è { data, meta }. Un numero all'interno di data non compare mai da solo. È un oggetto valore:
{
"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 è l'intervallo di tempo in cui questo era l'ultimo dato depositato. restated è vero solo quando un documento depositato presso la SEC successivo ha modificato il dato; restatement_kind indica quindi in che modo. proof.id rimanda, tramite GET /proof/{id}, al documento depositato presso la SEC e ai fatti grezzi alla base del valore.
Leggi il passato come era noto allora
as_of=2024-06-30su qualsiasi route di lettura restituisce ciò che era noto in quell'istante.original=truerestituisce la versione riportata per la prima volta per ciascun periodo.history=truerestituisce tutte le versioni di ciascun periodo, dalla più vecchia.GET /v1/changes?since=<timestamp>elenca i fatti acquisiti da quel momento in poi.
Route
| Route | Cosa restituisce |
|---|---|
GET /v1/companies | Elenco delle società con filtri e paginazione |
GET /v1/company/profile | Profilo, quotazioni e set di dati disponibili |
GET /v1/company/metrics | Le righe dei concetti del modello della società |
GET /v1/company/financials/{statement}/standardized | Un prospetto standardizzato |
GET /v1/company/financials/{statement}/as_reported | Le voci proprie del soggetto depositante con i relativi tag |
GET /v1/company/ratios | Indicatori calcolati dai bilanci, con le prove dei dati utilizzati |
GET /v1/company/ratios/daily/{ratio_id} | Un indicatore come serie su più periodi |
GET /v1/company/filings | Indice dei documenti depositati presso la SEC da una società |
GET /v1/filing/{accession} | Un documento depositato presso la SEC |
GET /v1/filing/{accession}/facts | Tutti i dati mappati contrassegnati con tag in un documento depositato presso la SEC |
GET /v1/filing/{accession}/document | Link alle pagine su EDGAR di un documento depositato presso la SEC, o al suo documento principale in formato HTML, PDF o immagini delle pagine |
GET /v1/filing/{accession}/summary | Una sintesi di un documento depositato presso la SEC scritta dall'IA, con una citazione per ogni affermazione; contrassegnata come output del modello |
GET /v1/company/research | Un rapporto su una società scritto dall'IA, con ogni numero verificato rispetto ai dati; non costituisce consulenza |
GET /v1/company/bull_bear | Tesi rialziste e ribassiste su una società scritte dall'IA, con le stesse verifiche e citazioni; non costituiscono consulenza |
GET /v1/company/ownership/insiders | Operazioni degli insider dai moduli Form 3, Form 4 e Form 5 |
GET /v1/company/ownership/institutional | Detentori di partecipazioni in una società dichiarati nei Form 13F, per trimestre |
GET /v1/ownership/institutional/holders | Gestori che presentano Form 13F |
GET /v1/ownership/institutional/holdings | Portafoglio 13F di un gestore per un trimestre |
GET /v1/company/splits | Frazionamenti azionari come dichiarati nei documenti depositati, e indicazione se i prezzi li confermano |
GET /v1/company/dividends | Dividendi per azione dichiarati o pagati in ciascun periodo, come riportati nei documenti depositati |
GET /v1/events_calendar | Comunicati sui risultati (8-K Item 2.02 depositato) e date previste dal modello |
GET /v1/company/events | Voci degli 8-K: un flusso di eventi basato sui documenti depositati presso la SEC |
GET /v1/news | Documenti depositati presso la SEC di tipo 8-K di tutte le società coperte, dal più recente, con tipi di evento e un livello di importanza |
GET /v1/news/feed | Il flusso di eventi di FinancialMD tratto da ogni modulo SEC contenente eventi, con titoli generati da regole, importanza e numeri chiave. Non sono notizie d'agenzia |
GET /v1/news/issuer_releases | Comunicati pubblicati dagli emittenti su sé stessi: allegati SEC e titolo con link dal feed dell'emittente stesso |
GET /v1/company/call_materials | Materiali delle conference call sui risultati depositati dall'emittente presso la SEC: comunicati, interventi preparati, lettere, presentazioni e una trascrizione, se depositata |
GET /v1/call_material/{id} | Un documento depositato dall'emittente suddiviso in passaggi, con sezioni, turni di intervento e tag tematici |
GET /v1/calls_calendar | Conference call sui risultati come annunciate dagli emittenti nei documenti depositati presso la SEC, con un link alla pagina del webcast dell'emittente stesso |
GET /v1/search/filings | Ricerca nel testo integrale dei documenti EDGAR dal 2001 (ricerca nel testo integrale di SEC EDGAR) |
GET /v1/coverage | Ogni dataset con il relativo stato: disponibile, non coperto (soggetto a licenza) o non realizzato, e cosa usare in alternativa |
GET /v1/company/estimates | Stime di base di FinancialMD basate su modelli, con intervalli e uno storico a una certa data (point-in-time), le previsioni della società così come dichiarate nei suoi documenti depositati presso la SEC e segnali descrittivi. Non sono stime di consenso né stime degli analisti. Vedi il metodo |
GET /v1/company/estimates/consensus | Non coperto: le stime di consenso sono soggette a licenza. Restituisce 404 not_covered con alternative |
GET /v1/company/analyst_ratings | Non coperto: le raccomandazioni degli analisti sono soggette a licenza. Restituisce 404 not_covered |
GET /v1/company/transcripts | Non coperto: le trascrizioni delle conference call sono soggette a licenza. Restituisce 404 not_covered |
GET /v1/company/stock_prices/intraday | Non coperto: i prezzi in tempo reale e intragiornalieri sono soggetti a licenza. Restituisce 404 not_covered |
GET /v1/company/logo | Un logo per identificare la società: un file con licenza aperta e relativa attribuzione, oppure un riquadro generato. JSON, SVG o PNG |
GET /v1/politician_trades | Operazioni comunicate dai membri della Camera dei rappresentanti degli Stati Uniti nei rapporti periodici sulle transazioni, come depositate, con il rapporto ufficiale. Mai corredate di prezzi. L'uso è limitato da 5 U.S.C. 13107(c)(1): leggere data.notice |
GET /v1/fund_letters | Indice delle lettere dei fondi e delle analisi dei rendimenti contenute nei documenti depositati presso la SEC di tipo N-CSR, con le società menzionate. Rimanda all'originale; non ospita il testo delle lettere |
GET /v1/fund_letters/sources | Fonti dell'indice delle lettere dei fondi, siti dei gestori elencati con le relative condizioni e conteggi |
GET /v1/fund_letters/{id} | Una lettera di un fondo indicizzata con tutte le società che menziona |
GET /v1/company/segments | Dati di settore (attività, area geografica, prodotto) come riportati |
GET /v1/company/ownership/insider_holders | Le partecipazioni detenute da ciascun insider dopo il suo ultimo Form 4 o Form 5 |
GET /v1/company/ownership/funds | Fondi che detengono partecipazioni nella società nel loro ultimo Form N-PORT |
GET /v1/funds | Fondi che presentano Form N-PORT con il loro ultimo rapporto |
GET /v1/fund/holdings | Partecipazioni di un fondo riportate nel Form N-PORT |
GET /v1/company/kpis | Metriche rettificate e operative comunicate dalla società, ciascuna con il relativo riferimento alla fonte |
GET /v1/company/dividend_events | Dividendi in contanti con le relative date come riportate nei documenti depositati presso la SEC |
GET /v1/company/ownership/insider_holdings | Voci delle partecipazioni nei Form 3, Form 4 e Form 5 |
GET /v1/fund/profile | La tipologia di un fondo tratta dal N-CEN e le commissioni delle sue classi di quote |
GET /v1/fund/nav | Il patrimonio netto di un fondo per mese di rendicontazione, il rendimento mensile dichiarato di ciascuna classe con il nostro indice di rendimento e il NAV per quota dei fondi chiusi, tratti dai documenti depositati presso la SEC. Il NAV giornaliero non viene fornito |
GET /v1/identifiers/xref | Dato un identificativo, la società o il fondo che identifica e gli altri identificativi aperti, ciascuno con la relativa fonte |
GET /v1/identifiers/master | Identificativi aperti di ogni società, con paginazione |
GET /v1/company/stock_prices/returns | Rendimento del prezzo, rendimento totale e massimo drawdown su intervalli standard, calcolati da barre di fine giornata e da frazionamenti azionari e dividendi riportati nei documenti depositati presso la SEC |
GET /v1/company/identifiers | LEI e FIGI con la relativa documentazione a supporto |
GET /v1/company/stock_prices | Barre giornaliere costruite esclusivamente dagli scambi su IEX. Non dal flusso consolidato delle transazioni. Valori non rettificati per impostazione predefinita; adjust=splits o adjust=total_return aggiunge valori rettificati |
GET /v1/screen | Filtra tutte le società coperte in base alle metriche dell'ultimo periodo |
POST /v1/verify | Verifica un numero rispetto al valore riportato nel documento depositato presso la SEC |
GET /v1/changes | Dati divenuti noti a partire da un dato momento |
POST /v1/request-data | Dicci quali dati ti servivano e non hai trovato. Nessuna chiave, nessun addebito, revisione settimanale. Vedi come inviare una richiesta |
GET /v1/request-data | Il corpo accettato da POST /v1/request-data |
GET /v1/request-data/{id} | Lo stato di una richiesta: new, triaged, planned, done o wontfix |
GET /v1/requested | Richiesti e forniti: richieste esaminate con conteggi, senza dettagli sui richiedenti |
GET /proof/{id} | La prova relativa a un valore fornito |
Il documento OpenAPI contiene tutti i parametri e gli schemi delle risposte. I file llms.txt, llms-full.txt e il file delle competenze forniscono le stesse informazioni agli agenti; https://api.financial.md/docs è il riferimento interattivo e https://api.financial.md/changelog elenca le modifiche.
Verifica un numero
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}'La risposta contiene un verdict pari a matches, differs o unknown, il valore riportato nel documento depositato presso la SEC con la relativa prova, la differenza e uno scale_hint quando il tuo numero differisce per un fattore pari a una potenza di dieci.
Limiti
Le chiamate senza chiave sono soggette a limiti giornalieri per indirizzo IP.
- 25 chiamate conteggiate: indici, selezione e verifica
- 1,000 letture del livello dei documenti depositati presso la SEC: prospetti finanziari, dati come dichiarati, documenti depositati presso la SEC, assetti proprietari e prezzi
- 1,000 letture di metadati: elenco, profili, metriche, prove e modifiche
Ogni risposta include RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Una risposta 429 include Retry-After.
Non vengono ancora rilasciate chiavi API con limiti più elevati. Vedi Chiavi API. Le chiamate su api.financial.md sono gratuite. Gli agenti possono pagare per chiamata su agent.financial.md. Vedi Prezzi.
Cosa è coperto
La copertura comprende le società che depositano documenti presso la SEC e che sono attualmente quotate su una borsa statunitense.
- Sono disponibili prospetti finanziari standardizzati per i soggetti che depositano documenti presso la SEC e redigono i bilanci secondo gli US GAAP.
- I soggetti che redigono i bilanci secondo gli IFRS, come molte società estere che depositano il Form 20-F o il 40-F, dispongono di documenti depositati presso la SEC ma non ancora di prospetti finanziari standardizzati.
- Le società revocate dalla quotazione sono presenti nell'elenco con i loro prospetti finanziari e documenti depositati presso la SEC. Cercale tramite CIK: non sono disponibili né la ricerca per ticker né i prezzi, quindi lo storico dei prezzi copre solo le società attualmente quotate.
- I dati sugli assetti proprietari provengono da documenti depositati presso la SEC a partire dal July 1, 2026 e vengono aggiornati ogni giorno alle 13:00 UTC dall'indice giornaliero EDGAR: operazioni degli insider dai Form 3, Form 4 e Form 5 delle società coperte e ogni Form 13F-HR, quindi i rapporti 13F di un nuovo trimestre arrivano man mano che i gestori li depositano. Una posizione 13F viene associata a una società solo quando il frontespizio di uno Schedule 13D o 13G identifica il suo titolo. Per il trimestre chiuso il June 30, 2026, questo consente di associare l'80 percento del valore dichiarato; le altre posizioni compaiono nel portafoglio del gestore sotto il nome dell'emittente come riportato nel documento depositato presso la SEC.
- Le stime di consenso e le trascrizioni delle conference call sui risultati non vengono fornite: entrambe sono dati soggetti a licenza. I segmenti vengono forniti come dichiarati e le notizie sono il flusso dei documenti 8-K depositati presso la SEC.
Quando una società è nota ma manca un insieme di dati, l'API risponde not_covered ed elenca gli insiemi di dati disponibili.
Server MCP
Il server MCP rende disponibile la stessa API tramite 50 strumenti di sola lettura. Utilizza MCP Streamable HTTP e non richiede un account.
https://mcp.financial.md/mcpLa guida MCP elenca gli strumenti. La scheda del server è destinata ai registri.
Errori
Un errore è { "error": { code, message, docs, request_id, remedies } }. L'elenco remedies indica cosa fare dopo. La guida agli errori spiega ogni codice.