pycvm vs apicvm: Local CVM ZIP Parser vs Filings API
Python developers comparing pycvm vs CVM API options usually want the same outcome: programmatic access to Brazilian regulatory filings (DFP, ITR, FRE). The tools differ in shape — pycvm is an open-source library that parses CVM bulk ZIP dumps locally; apicvm is a hosted HTTP API for ticker-first document workflows.
This page compares both fairly — trade-offs, not a winner-takes-all ranking.
What pycvm provides
pycvm (GitHub: glourencoffee/pycvm) is a Python library for extracting structured data from CVM open-data ZIP files. Typical workflow:
Download ZIP from dados.cvm.gov.br → open with pycvm → iterate records / DataFramesDocument types supported by the library (per PyPI docs):
| Type | pycvm support |
|---|---|
| FCA (Formulário Cadastral) | Yes |
| DFP | Yes |
| ITR | Yes |
| FRE | Partial |
| IPE, CAD | Not supported in pycvm |
Strengths: free (MIT), runs offline after download, full control over parsing logic, good for batch econometrics and custom ETL over historical dumps.
Example pattern:
import cvm
with cvm.DFPITRFile("path/to/dfp_or_itr.zip") as file:
for dfpitr in file:
print(dfpitr.company_name, dfpitr.type.name, dfpitr.receipt_date)What apicvm provides
apicvm is a product API over an ingested CVM corpus:
resolve company → list documents → download file → optional async text extractionexport APICVM_KEY='apicvm_...'
export APICVM_URL='https://apicvm.dev'
curl -H "Authorization: Bearer $APICVM_KEY" \
"$APICVM_URL/v1/documents?ticker=PETR4&type=DFP&year=2024&perPage=20"| Capability | pycvm | apicvm |
|---|---|---|
| Interface | Local Python library | HTTP REST (/v1/*) |
| Input | CVM ZIP dumps you download | Ticker / CNPJ queries |
| Per-filing PDF download | Via ZIP contents | GET /v1/documents/:id/file |
Stable document.id |
No (you manage paths) | Yes (UUID) |
| Page markdown extraction | DIY (PDF parsing) | Async callback job |
| FCA support | Yes | Not in ingested corpus |
| Ops burden | You run ETL + storage | Hosted |
Where each approach fits
pycvm shines when you already work with CVM open-data bulk files — cross-sectional panels, offline notebooks, or pipelines where you own the full data lake. You pay in engineering time (ZIP discovery, schema updates, PDF handling) instead of subscription fees.
apicvm shines when filings are a dependency inside a product — agents, SaaS features, microservices — and you want GET /v1/documents?ticker=PETR4 instead of maintaining ZIP ingestion.
When to use each
| Use pycvm | Use apicvm |
|---|---|
| Offline analysis on full historical ZIP dumps | Production HTTP integration with API key |
| Need FCA registration-form data | DFP / ITR / FRE per-filing workflow |
| Zero vendor cost, full data control | Ticker-first list + stable document IDs |
| You already maintain CVM open-data ETL | Async page-level markdown for RAG/agents |
| Batch parse thousands of rows from one ZIP | One company's latest filing from code in seconds |
Many teams prototype with pycvm or open-data dumps, then move hot paths to an API once uptime and per-filing access matter.
Can you use both?
Yes. Common pattern:
pycvm / open data → historical panels, FCA, econometric datasets
apicvm → live lookups, PDF download, agent tools, extractionThey are complementary layers — not strict substitutes.
Current limitations (apicvm)
- Corpus covers ingested DFP / ITR / FRE — not FCA, IPE, CAD, or every open-data category pycvm can parse.
- Extraction is async via callback; no job-status polling endpoint in v1.
- Paid API with rate limits — pycvm remains free OSS after you download ZIPs.
- Ingestion lag — not real-time CVM publication.
Current limitations (pycvm)
- You must fetch and refresh ZIP files from the portal yourself.
- FRE support is partial; IPE and CAD are outside library scope.
- No HTTP endpoints — not drop-in for agent tools expecting REST.
- Schema and ZIP layout changes require library updates or your own fixes.
Next steps
Ready to integrate?
Get an API key and start querying Brazilian CVM filings programmatically.