> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Financial Data Extraction

> Documentation on the structured extraction of data from financial statements

## Overview

Topograph extracts financial data automatically from company annual statements. We analyze PDF documents and extract key financial metrics into a structured, machine-readable format.

## How It Works

When a financial statement document is processed:

1. **Document Classification** - The AI first determines if the document is a financial statement
2. **Data Extraction** - If identified as a financial statement, key metrics are extracted
3. **Structured Output** - Data is returned in the `extractedFinancialData` field on each financial statement

Non-financial documents will not have the `extractedFinancialData` field populated.

## Data Model

The structure for extracted data covers all major components of financial statements as presented below.

### Top-Level Structure

```typescript theme={null}
{
  extractedFinancialData: {
    // Metadata
    fiscalYear: FiscalYear;
    approvalDate: string | null;
    currency: string | null;
    accountingStandard: AccountingStandard;
    statementType: StatementType;

    // Financial sections
    incomeStatement: IncomeStatement;
    balanceSheet: BalanceSheet;
  }
}
```

### Metadata Fields

#### Fiscal Year

```typescript theme={null}
fiscalYear: {
  startDate: string; // Format: "YYYY-MM-DD"
  endDate: string; // Format: "YYYY-MM-DD"
}
```

#### Accounting Standard

* `"IFRS"` - International Financial Reporting Standards
* `"French GAAP"` - French Generally Accepted Accounting Principles
* `"US GAAP"` - United States GAAP
* `"Swiss GAAP"` - Swiss GAAP
* `"Lux GAAP"` - Luxembourg GAAP
* `"Other"` - Other accounting standards

#### Statement Type

* `"consolidated"` - Group/consolidated financial statements
* `"simplified"` - Individual/standalone statements

### Income Statement

```typescript theme={null}
incomeStatement: {
  revenue: {
    amount: number | null; // Current period
    previousAmount: number | null; // Prior period
    localName: string; // Original term from document
  }
  depreciationAndAmortization: {
    amount: number | null;
    previousAmount: number | null;
    localName: string;
  }
  operatingIncome: {
    amount: number | null;
    previousAmount: number | null;
    localName: string;
    standardDefinition: string | null; // How it's calculated
    notes: string | null; // Additional context
  }
  netIncome: {
    amount: number | null;
    previousAmount: number | null;
    localName: string;
  }
}
```

### Balance Sheet

The balance sheet is organized into two main sections.

#### Assets

```typescript theme={null}
assets: {
  fixedAssets: {
    total: {
      amount: number | null;
      previousAmount: number | null;
    }
    components: {
      tangible: {
        // Property, plant, equipment
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
      intangible: {
        // Goodwill, patents, software
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
      financialAssets: {
        // Long-term investments
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
    }
  }
  currentAssets: {
    total: {
      amount: number | null;
      previousAmount: number | null;
    }
    components: {
      cashAndEquivalents: {
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
      tradeReceivables: {
        // Accounts receivable
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
      inventory: {
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
      otherCurrentAssets: {
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
    }
  }
}
```

#### Equity and Liabilities

```typescript theme={null}
equityAndLiabilities: {
  equity: {
    total: {
      amount: number | null;
      previousAmount: number | null;
    }
    components: {
      shareCapital: {
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
      retainedEarnings: {
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
      otherReserves: {
        amount: number | null;
        previousAmount: number | null;
        localName: string;
      }
    }
  }
  liabilities: {
    nonCurrent: {
      // Long-term (> 1 year)
      total: {
        amount: number | null;
        previousAmount: number | null;
      }
      components: {
        financialDebt: {
          amount: number | null;
          previousAmount: number | null;
          localName: string;
        }
        otherNonCurrentLiabilities: {
          amount: number | null;
          previousAmount: number | null;
          localName: string;
        }
      }
    }
    current: {
      // Short-term (< 1 year)
      total: {
        amount: number | null;
        previousAmount: number | null;
      }
      components: {
        tradePayables: {
          amount: number | null;
          previousAmount: number | null;
          localName: string;
        }
        currentFinancialDebt: {
          amount: number | null;
          previousAmount: number | null;
          localName: string;
        }
        otherCurrentLiabilities: {
          amount: number | null;
          previousAmount: number | null;
          localName: string;
        }
      }
    }
  }
}
```

## AI Financial Analysis

In addition to extracting raw financial data, Topograph provides AI-powered analysis that includes insights, ratios, trends, and risk assessments.

### Analysis Structure

```typescript theme={null}
analysis: {
  // Executive summary (2-3 sentences)
  summary: string;
  
  // Concise narrative analysis covering key points
  narrativeAnalysis: string;
  
  // Overall financial health score (1-10)
  healthScore: number;
  
  // Risk assessment
  overallRisk: "low" | "medium" | "high" | "critical";
  
  // Key financial ratios
  ratios: {
    currentRatio: number;     // Current Assets / Current Liabilities
    quickRatio: number;       // (Current Assets - Inventory) / Current Liabilities
    debtToEquity: number;     // Total Liabilities / Total Equity
    netProfitMargin: number;  // Net Income / Revenue (%)
    returnOnEquity: number;   // Net Income / Total Equity (%)
    revenueGrowth: number;    // YoY Revenue Change (%)
  }
  
  // Year-over-year trend directions
  trends: {
    revenueDirection: "increasing" | "stable" | "decreasing";
    profitabilityDirection: "improving" | "stable" | "declining";
    debtDirection: "increasing" | "stable" | "decreasing";
  }
  
  // Specific insights with risk levels
  insights: Array<{
    category: "liquidity" | "profitability" | "solvency" | "growth";
    title: string;
    description: string;
    riskLevel: "low" | "medium" | "high" | "critical";
    metricValue: string;
    recommendation?: string;
  }>
  
  // Key strengths identified
  strengths: string[];
  
  // Areas of concern
  concerns: string[];
}
```

### Ratio Explanations

| Ratio             | Formula                                            | Good   | Watch     | Risk   |
| ----------------- | -------------------------------------------------- | ------ | --------- | ------ |
| Current Ratio     | Current Assets / Current Liabilities               | > 1.5  | 1.0 - 1.5 | \< 1.0 |
| Quick Ratio       | (Current Assets - Inventory) / Current Liabilities | > 1.0  | 0.5 - 1.0 | \< 0.5 |
| Debt to Equity    | Total Liabilities / Total Equity                   | \< 1.0 | 1.0 - 2.0 | > 2.0  |
| Net Profit Margin | Net Income / Revenue                               | > 10%  | 5% - 10%  | \< 5%  |
| Return on Equity  | Net Income / Total Equity                          | > 15%  | 10% - 15% | \< 10% |

### Health Score

The health score ranges from 1 to 10:

* **8-10**: Excellent financial health
* **6-7**: Good, with some areas to monitor
* **4-5**: Fair, requires attention
* **2-3**: Weak financial position
* **1**: Critical condition

## Important Notes

### Data Quality

* **Null Values** - Fields return `null` when data is missing, unclear, or not applicable
* **Numeric Values** - All amounts are numeric values without currency symbols or thousand separators
* **Negative Values** - Losses and deficits preserve the negative sign
* **Local Terms** - The `localName` field presents the exact wording used in the source document

### Multi-Language Support

The extraction works across multiple languages and accounting frameworks:

* Recognizes financial terms in various languages
* Maps local terminology to standardized fields
* Preserves original terms in `localName` fields

### Current Limits

* Only processes PDF financial statements
* Extraction accuracy depends on document quality and structure
* Complex or non-standard formats may have reduced accuracy
* Currently focuses on core financial metrics

## Example Usage

When retrieving documents with financial statements:

```bash theme={null}
POST https://api.topograph.co/v2/company
{
  "id": "your-company-id",
  "countryCode": "DE",
  "dataPoints": [],
  "documents": ["financial_statement_id"]
}
```

The response will include the extracted data and AI analysis:

```json theme={null}
{
  "documents": {
    "financialStatements": [
      {
        "id": "financial_statement_id",
        "extractedFinancialData": {
          "fiscalYear": {
            "startDate": "2023-01-01",
            "endDate": "2023-12-31"
          },
          "currency": "EUR",
          "accountingStandard": "IFRS",
          "statementType": "consolidated",
          "incomeStatement": { /* ... */ },
          "balanceSheet": { /* ... */ },
          "analysis": {
            "summary": "Company shows strong profitability with 15% revenue growth...",
            "healthScore": 7.5,
            "overallRisk": "low",
            "ratios": {
              "currentRatio": 1.52,
              "quickRatio": 1.17,
              "debtToEquity": 1.84,
              "netProfitMargin": 3.02,
              "returnOnEquity": 11.87,
              "revenueGrowth": 3.16
            },
            "trends": {
              "revenueDirection": "stable",
              "profitabilityDirection": "improving",
              "debtDirection": "decreasing"
            },
            "insights": [
              {
                "category": "profitability",
                "title": "Strong Profit Growth",
                "description": "Net income increased by 302% year-over-year...",
                "riskLevel": "low",
                "metricValue": "+302% YoY"
              }
            ],
            "strengths": [
              "Exceptional profitability growth",
              "Healthy liquidity position"
            ],
            "concerns": [
              "Trade receivables growing faster than revenue"
            ]
          }
        }
      }
    ]
  }
}
```

## Feedback

This is a beta feature and we're actively collecting feedback to improve extraction accuracy and expand coverage.
Please share your experiences and suggestions on support channels or to your account manager.