Get Started with the MKK Structured Data API

Make your first API calls to the MKK Structured Data API. Query funds, retrieve financial line items, and explore portfolio holdings in minutes.

The MKK Structured Data API requires no authentication and no setup — you can start querying immediately using any HTTP client. This guide walks you through five essential starting points: checking that the API is healthy, listing funds, fetching a fund’s detail, querying line item values, and listing portfolio holdings.

All examples use curl. If you prefer Python, JavaScript, or another language, swap out the curl command for your HTTP client of choice — the request shape is identical.

1. Check API health

   Before making data requests, verify the API is reachable by calling the health endpoint.

   curl https://mkk-roan.vercel.app/api/health
   

   A healthy API returns a 200 OK response with aggregate dataset counts:

   {
     "status": "ok",
     "documents": 4821,
     "funds": 312,
     "sections": 47,
     "line_items": 198,
     "line_item_values": 891430,
     "portfolio_entries": 2347610,
     "portfolio_rows": 2401088
   }
   

   If you receive a non-200 response or a connection error, the service may be temporarily unavailable.

2. List all funds

   Call GET /funds to retrieve every fund in the database. Each fund has a fund_code you will use to filter data in subsequent requests.

   curl https://mkk-roan.vercel.app/api/funds
   

   {
     "funds": [
       {
         "id": "1",
         "fund_code": "OJB",
         "fund_title": "OJB Değişken Fon",
         "document_count": 48,
         "period_count": 16,
         "line_item_count": 94,
         "first_period": "2019-Q1",
         "last_period": "2023-Q4"
       },
       {
         "id": "2",
         "fund_code": "AKB",
         "fund_title": "AKB Bono Fonu",
         "document_count": 36,
         "period_count": 12,
         "line_item_count": 78,
         "first_period": "2020-Q1",
         "last_period": "2023-Q4"
       }
     ]
   }
   

   Each fund object includes first_period and last_period so you know what time range of data is available.

3. Get a specific fund's detail

   Pass a fund code as a path parameter to GET /funds/{fundId} to retrieve full detail for a single fund, including its associated documents, sections, and line items.

   curl https://mkk-roan.vercel.app/api/funds/OJB
   

   {
     "id": "1",
     "fund_code": "OJB",
     "fund_title": "OJB Değişken Fon",
     "document_count": 48,
     "period_count": 16,
     "line_item_count": 94,
     "first_period": "2019-Q1",
     "last_period": "2023-Q4",
     "portfolio_entry_count": 14320,
     "documents": [
       {
         "id": 42,
         "disclosure_index": "FCH2023Q4",
         "fund_code": "OJB",
         "period": "2023-Q4",
         "document_type": "quarterly",
         "report_date": "2024-01-15",
         "line_item_value_count": 94,
         "portfolio_entry_count": 312,
         "portfolio_row_count": 318
       }
     ],
     "sections": [],
     "line_items": [],
     "portfolio_sections": [],
     "portfolio_limit": 500,
     "portfolio_offset": 0,
     "portfolio_entries": []
   }
   

   The numeric id values on documents are used to fetch line item values and portfolio data for a specific disclosure report.

4. Query line item values

   Use GET /line-item-values with query parameters to retrieve structured financial metrics for a specific fund and period. This is the primary way to pull normalized numbers from disclosure reports.

   curl "https://mkk-roan.vercel.app/api/line-item-values?fund_code=OJB&period=2023-Q4"
   

   {
     "line_item_values": [
       {
         "id": 8801,
         "document_id": 42,
         "disclosure_index": "FCH2023Q4",
         "fund_code": "OJB",
         "fund_title": "OJB Değişken Fon",
         "period": "2023-Q4",
         "line_item_id": 7,
         "line_item_slug": "net-asset-value",
         "line_item_name": "Net Asset Value",
         "sectionId": "balance-sheet",
         "sectionName": "Balance Sheet",
         "kind": "metric",
         "raw_label": "Fon Toplam Değeri",
         "value": "154320000.00",
         "numeric_value": 154320000.0,
         "unit": "TRY",
         "mapping_method": "exact",
         "mapping_confidence": 1.0
       }
     ]
   }
   

   You can narrow results further by adding section_id or line_item_slug query parameters. See the line items concept page for the full list of supported filters.

5. List portfolio entries for a fund

   Call GET /portfolio-entries filtered by fund_code to retrieve the normalized holdings from a fund’s disclosures, including security identifiers, market values, and portfolio weights.

   curl "https://mkk-roan.vercel.app/api/portfolio-entries?fund_code=OJB"
   

   {
     "total": 312,
     "limit": 100,
     "offset": 0,
     "portfolio_entries": [
       {
         "id": 5001,
         "document_id": 42,
         "disclosure_index": "FCH2023Q4",
         "fund_code": "OJB",
         "fund_title": "OJB Değişken Fon",
         "period": "2023-Q4",
         "section": "Devlet İç Borçlanma Senetleri",
         "security": "TURKIYE CUMHURIYETI 15.03.2026",
         "isin": "TR0000000001",
         "issuer": "Hazine ve Maliye Bakanlığı",
         "nominal_value": "10.000.000",
         "numeric_nominal_value": 10000000.0,
         "market_value": "9.875.000",
         "numeric_market_value": 9875000.0,
         "currency": "TRY"
       }
     ]
   }
   

   To retrieve holdings for a specific document rather than the latest, add a document_id query parameter.

Next steps

You now have the building blocks to explore any fund in the API. From here you can:

• Read the Core Concepts pages to understand filtering, pagination, and data quality flags
• Use the API Reference for the complete list of endpoints and query parameters
• Follow the Exporting data guide to download line item values and portfolio entries as CSV files