Skip to main content

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.

​
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

{
  extractedFinancialData: {
    // Metadata
    fiscalYear: FiscalYear;
    approvalDate: string | null;
    currency: string | null;
    accountingStandard: AccountingStandard;
    statementType: StatementType;

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

​
Metadata Fields

​
Fiscal Year

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

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

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

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

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

RatioFormulaGoodWatchRisk
Current RatioCurrent Assets / Current Liabilities> 1.51.0 - 1.5< 1.0
Quick Ratio(Current Assets - Inventory) / Current Liabilities> 1.00.5 - 1.0< 0.5
Debt to EquityTotal Liabilities / Total Equity< 1.01.0 - 2.0> 2.0
Net Profit MarginNet Income / Revenue> 10%5% - 10%< 5%
Return on EquityNet 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: 
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: 
{
  "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.