{"id":5920,"library":"edgartools","title":"edgartools: SEC EDGAR Filings Analysis","description":"EdgarTools is a Python library designed to access and analyze SEC EDGAR filings, XBRL financial statements, 10-K, 10-Q, and 8-K reports. It provides structured Python objects for over 20 filing types, converting complex SEC data into easy-to-use DataFrames. Currently at version 5.29.0, the library is actively developed with frequent updates addressing bug fixes and adding new features, often multiple releases per month.","status":"active","version":"5.29.0","language":"en","source_language":"en","source_url":"https://github.com/dgunning/edgartools","tags":["SEC","EDGAR","XBRL","financial data","investing","corporate filings","pandas","data analysis"],"install":[{"cmd":"pip install edgartools","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core for data manipulation and DataFrame output.","package":"pandas","optional":false},{"reason":"Used for making HTTP requests to the SEC EDGAR database.","package":"httpx","optional":false},{"reason":"High-performance HTML and XML parsing for structured data extraction.","package":"lxml","optional":false},{"reason":"Used for optimized data handling, especially when working with DataFrames.","package":"pyarrow","optional":false}],"imports":[{"note":"Primary class for looking up companies and their filings.","symbol":"Company","correct":"from edgar import Company"},{"note":"Most core components are imported directly from the `edgar` top-level namespace, not `edgartools`.","wrong":"from edgartools import set_identity","symbol":"set_identity","correct":"from edgar import set_identity"},{"note":"Used for fetching a broader range of filings not necessarily tied to a single company, or when working with Form 13F-HR.","symbol":"get_filings","correct":"from edgar import get_filings"}],"quickstart":{"code":"import os\nfrom edgar import Company, set_identity\n\n# The SEC requires all API users to identify themselves with a name and email.\n# Set this once or use the EDGAR_IDENTITY environment variable.\nidentity = os.environ.get('EDGAR_IDENTITY', 'John Doe john.doe@example.com')\nset_identity(identity)\n\n# Get a company by its ticker symbol\ncompany = Company(\"AAPL\")\n\n# Access basic company data\nprint(f\"Company: {company.name}\")\nprint(f\"Industry: {company.industry}\")\n\n# Get the company's latest financial statements\nfinancials = company.get_financials()\nincome_statement = financials.income_statement()\nbalance_sheet = financials.balance_sheet()\ncashflow_statement = financials.cashflow_statement()\n\nprint(\"\\nLatest Income Statement (first 5 rows):\\n\", income_statement.head())\nprint(\"\\nLatest Balance Sheet (first 5 rows):\\n\", balance_sheet.head())","lang":"python","description":"This quickstart demonstrates how to set your SEC identity, create a `Company` object, access basic company information, and retrieve the latest income statement and balance sheet. It highlights the structured data access that edgartools provides."},"warnings":[{"fix":"Call `edgar.set_identity(\"Your Name your.email@example.com\")` once at the beginning of your script, or set the `EDGAR_IDENTITY` environment variable.","message":"The SEC requires all API users to identify themselves with a name and email. Failing to do so will result in an error when making requests.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you `pip install edgartools`. If you previously installed `edgar`, run `pip uninstall edgar && pip install edgartools`.","message":"There is an unrelated package on PyPI also named `edgar`. Installing `edgar` instead of `edgartools` will lead to `ImportError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to edgartools v5.28.5 or newer to ensure HTML content in `TextBlock` disclosures is automatically sanitized to plain text.","message":"Prior to v5.28.5, the `to_dataframe()` method for disclosure `TextBlock` concepts could contain raw HTML markup instead of plain text, leading to uncleaned data in DataFrames.","severity":"gotcha","affected_versions":"<5.28.5"},{"fix":"Upgrade to edgartools v5.28.3 or newer to get accurate quarter labels for non-calendar fiscal year companies.","message":"Before v5.28.3, financial statement quarter labels for companies with non-calendar fiscal years might have been incorrect, using hardcoded calendar months instead of the company's fiscal year end month.","severity":"gotcha","affected_versions":"<5.28.3"},{"fix":"edgartools generally handles rate limiting internally, but for large-scale operations, enable local storage, batch downloads, and process filings sequentially or with careful parallel processing.","message":"The SEC imposes rate limits (typically 10 requests per second) on EDGAR data access. Exceeding these limits can result in your IP being temporarily blocked.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `financials.cashflow_statement()` for consistency and to follow the canonical naming convention.","message":"While `cash_flow_statement()` still works, the canonical method for retrieving cash flow statements is `cashflow_statement()` (without an underscore).","severity":"deprecated","affected_versions":"v5.x"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}