facts.get_fact() call returns None

[djleblan754]

Issue Type

• [ x ] Data Quality Issue (incorrect financial values, missing data)
• XBRL Parsing Issue (statement rendering, concept mapping)
• Filing Access Issue (download failures, attachment problems)
• Performance Issue (slow operations, memory problems)
• Compatibility Issue (platform/dependency conflicts)
• Documentation Issue (unclear instructions, missing examples)

Environment

EdgarTools Version: (e.g., 4.9.0)
5.11.2
Python Version: (e.g., 3.10.5)
3.11.13
Operating System: (e.g., macOS 14.0, Windows 11, Ubuntu 22.04)
Ubuntu 22.04.5 LTS

Bug Description

What you expected to happen:
I expected the call to return the requested data.

What actually happened:
The call returned None.

Error message (if any):

Paste any error messages here

Reproduction

Company/Ticker: (e.g., AAPL)
Time Period: (e.g., 2020-2023, Q4 2023)
Relevant Forms: (e.g., 10-K, 10-Q, 8-K)

Minimal code to reproduce:

# From 'After' example here: https://edgartools.readthedocs.io/en/latest/PeriodType-Quick-Reference/?h=facts.get_fact%28#from-boolean-annual-parameter

# Rich period support with enhanced querying
from edgar import Company

company = Company("AAPL")

facts = company.get_facts()
print(f"{type(facts)=}")  # --> <class 'edgar.entity.entity_facts.EntityFacts'>
print(f"{facts=}")  # --> ok

# Financial statement methods with boolean parameters
# annual_income = facts.income_statement(annual=True)     # Annual
# quarterly_income = facts.income_statement(annual=False) # Quarterly

# Advanced period filtering with query interface
# ttm_facts = facts.query().by_period_length(12).get()   # Trailing twelve months
# quarterly_facts = facts.query().by_period_length(3).get() # Quarterly periods

# Individual fact retrieval with period specification
revenue_2023 = facts.get_fact("Revenue", period="2023-FY")
print(f"{type(revenue_2023)=}")  # --> <class 'NoneType'>
print(f"{revenue_2023=}")  # --> None

revenue_q4 = facts.get_fact("Revenue", period="2023-Q4")
print(f"{type(revenue_q4)=}")  # --> <class 'NoneType'>
print(f"{revenue_q4=}")  # --> None

Additional Context

My objective is to extract specific 'concepts' from the company facts along with their associated filing dates. These 'concepts' span the income statement, balance sheet and cash flow statements. Ironically, I believe that it may be easier if I could work directly with the company facts in JSON format - is it possible to do that?

---

This issue will be handled using EdgarTools' systematic issue resolution workflow. A reproduction test will be created to verify the fix.

[dgunning]

Issue Confirmed - Documentation Example Error

Thank you for reporting this @djleblan754. I've confirmed the issue and classified it as CRITICAL for immediate fix.

The Problem

The documentation example uses "Revenue" as a concept name, but this is not a real XBRL concept in SEC filings. Apple (and most companies) use the full concept name:

• us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax

Immediate Workaround

Use the full concept name or the lowercase label:

from edgar import Company

company = Company("AAPL")
facts = company.get_facts()

# Option 1: Full XBRL concept name
revenue_2023 = facts.get_fact(
    "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", 
    period="2023-FY"
)

# Option 2: Lowercase label (easier to remember)
revenue_2023 = facts.get_fact(
    "revenue from contract with customer, excluding assessed tax", 
    period="2023-FY"
)

print(revenue_2023)  # FinancialFact(...=383,285,000,000 USD, FY 2023)

Fix Timeline

Classification: CRITICAL - Documentation example failure
Release: Point release v5.12.1 (within 24 hours)
Tracking: Beads issue edgartools-fxat created with P0 priority

We're addressing this immediately with a two-phase approach:

1. Immediate (v5.12.1): Fix documentation with correct concept names and clear examples
2. Future (v5.13.0): Add concept aliasing so "Revenue" automatically maps to the correct XBRL concept

Documentation credibility is critical to EdgarTools' mission of being beginner-friendly. This will be fixed ASAP.

Your Original Question

My objective is to extract specific 'concepts' from the company facts along with their associated filing dates.

You're on the right track! Here's a pattern that works well:

from edgar import Company

company = Company("AAPL")
facts = company.get_facts()

# Get specific concepts with filing dates
concepts_to_extract = [
    "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
    "us-gaap:NetIncomeLoss",
    "us-gaap:Assets",
    "us-gaap:CashAndCashEquivalentsAtCarryingValue"
]

for concept in concepts_to_extract:
    fact = facts.get_fact(concept, period="2023-FY")
    if fact:
        print(f"{fact.label}: ${fact.numeric_value:,.0f}")
        print(f"  Filing Date: {fact.filing_date}")
        print(f"  Period: {fact.period_start} to {fact.period_end}")

Thank you for bringing this to our attention!

[djleblan754]

Thanks again for your quick and comprehensive response! I built on your above code and am able to extract the desired data. My current issue is that companies use many different 'full concept names' for the same concept (i.e. Revenue), often changing from one year to the next. I have been reviewing the files in directory 'site-packages/edgar/xbrl/standardization'. Of particular interest is 'gaap_mappings.json'. I was able to load it into a dictionary and create a reverse mapper, but I am concerned that many companies will report subsets of revenue under multiple full concept names. If I am looking for Total Revenues, how do I ensure that I look for the correct 'full concept names' first, or how would I know when it would be appropriate to sum all of the 'full concept name' values found?

I have also found 'full concept names' prefixed with 'ifrs-full:'. Is there a mapping for those as well?