Line Items: Querying Canonical Financial Metrics

Line items are canonical financial metrics and text fields extracted from fund reports, identified by stable slugs and organized into report sections.

Line items are the building blocks of structured financial data in the MKK API. Each line item defines a canonical metric or text field that can appear across many fund reports — things like net asset value, number of circulating units, or fund manager name. By mapping raw PDF labels to these canonical definitions, the API lets you compare the same metric across different funds and reporting periods using a single stable identifier.

Kinds of line items

Every line item has a kind field that indicates what type of value it holds:

• metric — a numeric measurement (e.g., net asset value, total assets). These line items have a unit field (e.g., "TRY", "units") and populate the numeric_value field in their values.
• text — a descriptive or categorical value (e.g., fund manager name, investment strategy description). These line items have no unit and store their data in the string value field.

Slugs as stable identifiers

Each line item is identified by a slug — a kebab-case string like "net-asset-value" or "number-of-units". Slugs are stable across API versions and safe to hard-code in your application. Use the slug to fetch a specific line item or to filter values:

GET https://mkk-roan.vercel.app/api/line-items/net-asset-value

Sections

Line items are organized into canonical report sections (e.g., "fund-information", "balance-sheet"). The sectionId on a line item tells you which section it belongs to. Sections have a sort_order that reflects their order in a standard MKK disclosure report.

You can browse available sections at /sections, optionally filtered by fund:

GET https://mkk-roan.vercel.app/api/sections?fund_code=OJB

Line item values

A LineItemValue is the actual extracted value for a specific line item in a specific document. Where the line item definition is the schema, the value is the data. Each value records:

Field	Description
document_id	The document this value was extracted from
disclosure_index	The MKK disclosure reference
fund_code	The fund the document belongs to
period	The reporting period
line_item_slug	Slug of the parent line item
raw_label	The original label text as it appeared in the PDF
value	Extracted value as a string
numeric_value	Parsed numeric value (for metric kind)
unit	Unit of measurement
mapping_method	How the raw label was matched to the canonical line item
mapping_confidence	Confidence score for the mapping (0–1)

Mapping method and confidence

Because MKK PDF reports are not perfectly consistent across funds or periods, the API uses a matching process to map raw PDF labels to canonical line items. The mapping_method tells you how the match was made (e.g., exact string match, fuzzy match, or ML-based inference), and mapping_confidence gives you a 0–1 score indicating how certain the system is about that match.

Values with a low mapping_confidence should be treated with extra care. A score below 0.7 may indicate that the raw label was ambiguous or unusual — verify against the source PDF using the document’s pdf_url or kap_file_url when precision is critical.

The raw_label field preserves the original text from the PDF so you can inspect what the parser actually found.

Example requests

List all line items

curl https://mkk-roan.vercel.app/api/line-items

Example response: GET /line-items/net-asset-value

{
  "id": 7,
  "slug": "net-asset-value",
  "name": "Net Asset Value",
  "sectionId": "balance-sheet",
  "unit": "TRY",
  "kind": "metric",
  "value_count": 1240,
  "fund_count": 38,
  "document_count": 312
}

Example LineItemValue

{
  "document_id": 42,
  "disclosure_index": "FCH2023Q3",
  "fund_code": "OJB",
  "period": "2023-Q3",
  "line_item_slug": "net-asset-value",
  "raw_label": "Fon Toplam Değeri",
  "value": "154320000.00",
  "numeric_value": 154320000.00,
  "unit": "TRY",
  "mapping_method": "exact",
  "mapping_confidence": 1.0
}

The /key-values endpoint is an alias for /line-item-values and accepts the same query parameters. Both paths return identical responses.