On this page
A dataframe becomes research-ready when its identity, dates, precision and missing observations are explicit. Loading a JSON array is only the first step; a clean-looking chart can still hide a duplicated date or an approximate source conversion.
This workflow reads the completed export from the NAV pagination guide, validates it with pandas and keeps exact decimal values beside separate chart values. It produces a quality summary, a CSV and an optional observation chart. It does not turn raw NAV change into a complete investor-return history.
The useful part, upfront.
- Keep original NAV strings and construct Decimal directly from them.
- Fail on duplicate identities and dates before preparing analysis.
- Calendar gaps are observations to investigate, not values to silently fill.
Collect a complete selection before opening pandas#
Use the private collect_nav.py workflow to retrieve all history pages for one returned fund slug and an explicit range. The resulting nav-export.json has rows, selection, retrieved_at and the metadata for each collected page. The dataframe code never sends an API key, and loading a private completed file makes your transformation reproducible without repeating a network request every time you adjust a chart.
Install pandas and matplotlib into your research environment and save the script below as prepare_nav.py. Use a virtual environment and record dependency versions alongside the research output. The examples are independent of a particular real fund or promised historical coverage. If you use the synthetic fixture, label both exported data and every chart as a fictional demonstration.
References: ILovePSX public API reference · ILovePSX NAV API guide
Choose the analytical columns without destroying the raw export#
The script projects five columns: fund_slug, fund_name, nav_date, nav and currency. The raw export remains unchanged and retains optional offer, repurchase, market-price, load and change fields. A projection is a deliberate analysis choice, not a statement that the API only provides five fields.
A selected history should contain one canonical fund identity. The preparation step checks this rather than allowing similarly named plans to mix into one line. Currency stays explicit even when current NAV observations use PKR. If you later combine several funds, partition calculations by identity and describe the date-alignment policy before comparing them.
References: ILovePSX public API reference
Validate dates, duplicates and Decimal values#
The function uses a declared date format and raises on invalid dates. It rejects missing required fields, duplicate fund/date combinations and records outside the chosen range. It also verifies that NAV input is a decimal string before constructing Decimal. An unexpected numeric JSON value therefore becomes a contract check failure rather than silently passing through a float conversion.
The exact nav column remains present. nav_decimal supports explicit decimal arithmetic; nav_plot_approximate is reserved for the chart. Only the latter converts to float. Empty exports return a NO_OBSERVATIONS summary and an empty table with the expected source columns. The script does not create a chart from an empty selection or a single point.
import json
from decimal import Decimal
from pathlib import Path
import pandas as pd
def prepare(export):
columns = ["fund_slug", "fund_name", "nav_date", "nav", "currency"]
frame = pd.DataFrame(export["rows"]).reindex(columns=columns)
if frame.empty:
return frame, {"state": "NO_OBSERVATIONS", "rows": 0}
if frame[["fund_slug", "nav_date", "nav"]].isna().any().any():
raise ValueError("Required NAV fields are missing.")
if not frame["nav"].map(lambda value: isinstance(value, str)).all():
raise ValueError("Expected NAV decimal strings.")
frame["observation_date"] = pd.to_datetime(
frame["nav_date"], format="%Y-%m-%d", errors="raise")
if frame.duplicated(["fund_slug", "nav_date"], keep=False).any():
raise ValueError("Duplicate observations need reconciliation.")
if set(frame["fund_slug"]) != {export["selection"]["fund_slug"]}:
raise ValueError("The file contains another fund.")
frame["nav_decimal"] = frame["nav"].map(Decimal)
if not frame["nav_decimal"].map(lambda value: value.is_finite() and value > 0).all():
raise ValueError("NAV must be a finite positive decimal.")
frame = frame.sort_values("observation_date").reset_index(drop=True)
start = pd.Timestamp(export["selection"]["from"])
end = pd.Timestamp(export["selection"]["to"])
if not frame["observation_date"].between(start, end).all():
raise ValueError("Observation outside the selected range.")
frame["calendar_gap_days"] = frame["observation_date"].diff().dt.days
frame["nav_plot_approximate"] = frame["nav_decimal"].map(float)
summary = {"state": "OBSERVED", "rows": len(frame),
"first_date": frame["nav_date"].iloc[0],
"last_date": frame["nav_date"].iloc[-1],
"gaps_over_one_day": int((frame["calendar_gap_days"] > 1).sum())}
return frame, summary
if __name__ == "__main__":
export = json.loads(Path("nav-export.json").read_text(encoding="utf-8"))
frame, summary = prepare(export)
print(json.dumps(summary, indent=2))
frame.to_csv("nav-analysis.csv", index=False)
if len(frame) > 1:
import matplotlib.pyplot as plt
axis = frame.plot(x="observation_date", y="nav_plot_approximate",
legend=False, marker="o")
axis.set(xlabel="Observed NAV date", ylabel="NAV per unit (PKR)",
title="NAV observations · approximate chart values")
plt.figtext(0.5, 0.01, "Retrieved: " + export["retrieved_at"], ha="center")
plt.tight_layout(rect=(0, 0.04, 1, 1))
plt.savefig("nav-observations.png", dpi=160)
plt.close()References: pandas explicit date conversion · pandas duplicate-row detection · Python Decimal arithmetic
Read a synthetic quality summary and table#
Consider the three invented observations below. They are not an actual fund history. The exact strings preserve their source representation, and the calendar-gap column describes elapsed calendar days since the preceding observation. The first row has no predecessor in the selected file, so its gap is missing rather than zero.
This selection has three rows, a first date of 2026-09-28, a last date of 2026-10-01 and one gap over a single calendar day. That summary is useful without asserting that an unobserved date should contain a NAV. A gap report helps you decide which source or coverage question needs investigation before applying a calendar transformation.
| nav_date | nav (exact text) | nav_decimal | calendar_gap_days | nav_plot_approximate |
|---|---|---|---|---|
| 2026-09-28 | 100.125000 | Decimal('100.125000') | Missing first predecessor | 100.125 |
| 2026-09-29 | 100.250000 | Decimal('100.250000') | 1 | 100.25 |
| 2026-10-01 | 100.500000 | Decimal('100.500000') | 2 | 100.5 |
References: Python Decimal arithmetic
Reconcile duplicates before choosing which observation survives#
A duplicate fund/date key can come from concatenating exports or accidentally collecting overlapping ranges. Automatically dropping the later row may preserve an outdated value; automatically keeping it may hide an unexplained conflict. The example raises when it encounters duplicates so that a human or an explicit import policy can resolve the conflict first.
For a controlled warehouse, retain retrieval metadata and upsert observations using a documented correction policy. Compare exact NAV and other relevant fields before replacing the working record. Identical repeated rows and conflicting revisions are different cases. pandas can identify both, but the dataframe library does not determine which source version your research should trust.
References: pandas duplicate-row detection · ILovePSX public API reference
Keep observed dates separate from a calendar grid#
nav_date is a date-only observation. Parse it as such instead of introducing a midnight timezone conversion that can move it into the previous day for some readers. The collector's retrieved_at is an instant and should retain its timezone. Source date and retrieval instant serve different purposes in a research record.
The script sorts observations and measures calendar gaps. It does not resample, interpolate or forward-fill. If your analysis requires a complete calendar index, build that as a separate derived table with flags for observed and imputed values. Be explicit about the relevant fund schedule and data coverage before calling an unobserved day missing or stale.
References: pandas explicit date conversion · ILovePSX NAV API guide
Label the chart as NAV, then establish a return method separately#
The optional PNG plots approximate values at actual observation dates and retains the collector retrieval time in its caption. A line segment is a visual connection between available observations; it does not manufacture intervening source records. Keep the y-axis label NAV per unit (PKR), and record whether the selected dates are sufficient for the purpose of the chart.
NAV price change can differ from an investor's total return when payouts and reinvestment matter. The script deliberately does not compute a total-return series or advertise a backtest. Consult the NAV-change guide for those inputs and the reported-performance guide for disclosed FMR metrics. A fund's monthly reported return is not automatically the same calculation as a two-point NAV percentage change.
References: ILovePSX public API reference
Bring profiles and portfolio disclosures into the analysis carefully#
The canonical fund identity can connect NAV analysis to available FMR profiles, reported performance, holdings, asset allocation and credit-quality disclosures. These facts have report periods and versions of their own. Keep a separate dataframe for each section and retain the denominators, raw labels and source context before merging.
For a time-aware join, define which report was available for the date you are studying. Joining every historical NAV date to the latest portfolio can introduce a false impression that today's retrieved report described the past. The same care applies to credit-quality buckets: they describe a disclosed composition for a period, not a rating assigned by your dataframe.
References: ILovePSX public API reference
Keep a small, auditable research bundle#
Retain the original export, preparation script, dependency versions, quality summary and chosen chart alongside the analysis. CSV is useful for sharing a projection, but other software may infer numeric types when reopening it. Tell recipients which NAV column is exact text and which is approximate, and retain the original JSON as the unambiguous reference.
Test the preparation function with an empty selection, a valid series, a duplicate, an invalid date and an out-of-range observation. Only proceed after the failure states are understandable. That gives your research a reproducible foundation before you build dashboards, fund comparisons or an AI assistant on top of it.
References: ILovePSX authentication, scopes and limits
Try a complete example.
Use these fictional records to prototype a full fund view: profile, reported returns, holdings, asset and sector allocations, credit quality, fees and ratings. Every name, identifier and number is invented. This is educational mock data, with no connection to a real fund, source document or agency opinion.
The JSON mirrors the public response structure. The complete FMR example includes all supported expansions; empty arrays and nulls demonstrate valid missing-data states. Your live integration must still request the sections it needs and check the returned coverage.
Inspect the complete FMR model
{
"success": true,
"data": {
"id": "00000000-0000-4000-8000-000000000101",
"report_ids": [
"00000000-0000-4000-8000-000000000101"
],
"fund": {
"id": "00000000-0000-4000-8000-000000000201",
"slug": "example-research-fund",
"name": "Example Research Fund",
"mufap_fund_id": null,
"amc": {
"id": "00000000-0000-4000-8000-000000000301",
"slug": "example-asset-management",
"name": "Example Asset Management"
}
},
"report_date": "2026-09-30",
"currency": "PKR",
"data_version": 1,
"identity": {
"fund_name_as_reported": "Example Research Fund",
"fund_short_name_as_reported": "ERF",
"parent_fund_name_as_reported": null,
"plan_name_as_reported": null,
"fund_type_as_reported": "Open-end",
"category_as_reported": "Illustrative mixed-asset category",
"risk_profile_as_reported": "Illustrative higher-risk profile",
"is_shariah_compliant": false,
"is_plan": false,
"is_pension_scheme": false,
"is_etf": false
},
"fund_size": {
"nav_per_unit": "100.500000",
"nav_date": "2026-09-30",
"offer_price": "100.500000",
"redemption_price": "100.500000",
"repurchase_price": "100.500000",
"market_price": null,
"net_assets_pkr": "1005000000.0000",
"fund_size_pkr": "1005000000.0000",
"fund_size_including_fof_pkr": "1005000000.0000",
"fund_size_excluding_fof_pkr": "1005000000.0000",
"amount_invested_by_fof_pkr": "0.0000",
"units_outstanding": "10000000.000000"
},
"profile": {
"launch_date": "2025-01-01",
"inception_date": "2025-01-01",
"maturity_date": null,
"benchmark": "Example composite benchmark",
"old_benchmark": null,
"new_benchmark": null,
"benchmark_effective_date": null,
"risk_of_principal_erosion": "Principal may fluctuate; synthetic disclosure.",
"pricing_mechanism": "Forward pricing — illustrative",
"dealing_days": "Monday to Friday — illustrative",
"dealing_time": "09:00 to 14:00 Pakistan time — illustrative",
"cutoff_time": "14:00 Pakistan time — illustrative",
"settlement_period": "T+2 — illustrative, not an actual dealing policy",
"minimum_initial_investment_pkr": "5000.0000",
"minimum_subsequent_investment_pkr": "1000.0000",
"minimum_redemption_pkr": "1000.0000",
"unit_classes": [
"Illustrative standard units"
],
"leverage": "None in this synthetic example"
},
"report_fragments": [
{
"id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"schema_version": "fmr_page_v3",
"data_version": 1,
"promoted_at": "2026-10-08T08:00:00Z",
"report_date": "2026-09-30",
"report_month": "September 2026",
"page_type": "FUND_REPORT",
"extraction_mode": "PROFILE_PERFORMANCE_PORTFOLIO",
"amc_name_raw": "Example Asset Management",
"fund_name_raw": "Example Research Fund",
"fund_short_name_raw": "ERF",
"parent_fund_name_raw": null,
"plan_name_raw": null,
"fund_type_raw": "Open-end",
"category_raw": "Illustrative mixed-asset category",
"risk_profile_raw": "Illustrative higher-risk profile",
"risk_of_principal_erosion_raw": "Principal may fluctuate; synthetic disclosure.",
"is_shariah_compliant": false,
"is_plan": false,
"is_pension_scheme": false,
"is_etf": false,
"launch_date": "2025-01-01",
"inception_date": "2025-01-01",
"maturity_date": null,
"benchmark_raw": "Example composite benchmark",
"old_benchmark_raw": null,
"new_benchmark_raw": null,
"benchmark_effective_date": null,
"par_value": "100.000000",
"listing_raw": null,
"leverage_raw": "None in this synthetic example",
"nav_per_unit": "100.500000",
"nav_date": "2026-09-30",
"offer_price": "100.500000",
"redemption_price": "100.500000",
"repurchase_price": "100.500000",
"market_price": null,
"net_assets": "1005000000.0000",
"fund_size": "1005000000.0000",
"fund_size_including_fof": "1005000000.0000",
"fund_size_excluding_fof": "1005000000.0000",
"amount_invested_by_fof": "0.0000",
"units_outstanding": "10000000.000000",
"currency": "PKR",
"pricing_mechanism_raw": "Forward pricing — illustrative",
"dealing_days_raw": "Monday to Friday — illustrative",
"dealing_time_raw": "09:00 to 14:00 Pakistan time — illustrative",
"cutoff_time_raw": "14:00 Pakistan time — illustrative",
"settlement_period_raw": "T+2 — illustrative, not an actual dealing policy",
"minimum_initial_investment": "5000.0000",
"minimum_subsequent_investment": "1000.0000",
"minimum_redemption": "1000.0000",
"unit_classes": [
"Illustrative standard units"
]
}
],
"sub_funds": [],
"reported_returns": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"period_label_raw": "1 year",
"period_key": "1Y",
"fund_return_percent": "12.00000000",
"benchmark_return_percent": "10.00000000",
"peer_return_percent": null,
"return_type": "ABSOLUTE",
"is_annualized": false,
"is_since_inception": false,
"calculation_basis_raw": "Synthetic cumulative return for the stated period"
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 2,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"period_label_raw": "Month to date",
"period_key": "MTD",
"fund_return_percent": "0.50000000",
"benchmark_return_percent": "0.40000000",
"peer_return_percent": null,
"return_type": "ABSOLUTE",
"is_annualized": false,
"is_since_inception": false,
"calculation_basis_raw": "Synthetic cumulative September return"
}
],
"allocations": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "ASSET_ALLOCATION",
"label_raw": "Equities",
"label_normalized": null,
"percent_of_total_assets": "60.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": "603000000.0000",
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 2,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "ASSET_ALLOCATION",
"label_raw": "Cash",
"label_normalized": null,
"percent_of_total_assets": "20.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": "201000000.0000",
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 3,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "ASSET_ALLOCATION",
"label_raw": "Government securities",
"label_normalized": null,
"percent_of_total_assets": "15.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": "150750000.0000",
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 4,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "ASSET_ALLOCATION",
"label_raw": "Other assets",
"label_normalized": null,
"percent_of_total_assets": "5.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": "50250000.0000",
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 5,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "SECTOR_ALLOCATION",
"label_raw": "Technology",
"label_normalized": null,
"percent_of_total_assets": "25.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": "251250000.0000",
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 6,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "SECTOR_ALLOCATION",
"label_raw": "Fertilizer",
"label_normalized": null,
"percent_of_total_assets": "20.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": "201000000.0000",
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 7,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "SECTOR_ALLOCATION",
"label_raw": "Banks",
"label_normalized": null,
"percent_of_total_assets": "15.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": "150750000.0000",
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 8,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "CREDIT_QUALITY",
"label_raw": "Government securities — illustrative bucket",
"label_normalized": null,
"percent_of_total_assets": "15.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": null,
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 9,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"allocation_type": "CREDIT_QUALITY",
"label_raw": "Unrated / no rating assigned in this example",
"label_normalized": null,
"percent_of_total_assets": "85.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"amount": null,
"current_period": null,
"previous_period": null,
"change_percent": null,
"bucket_start_days": null,
"bucket_end_days": null,
"bucket_start_years": null,
"bucket_end_years": null
}
],
"holdings": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"holding_group": "TOP_HOLDINGS",
"rank": 1,
"name_raw": "Example Technology Company",
"holding_type": "EQUITY",
"asset_class": "Equities",
"issuer_name_raw": "Example Technology Company",
"security_name_raw": "Example Technology Company ordinary shares",
"symbol_raw": "EXTECH",
"sector_raw": "Technology",
"percent_of_total_assets": "18.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"percent_held": null,
"market_value": "180900000.0000",
"value_before_provisioning": null,
"provisioning_amount": null,
"value_after_provisioning": null,
"quantity": "1000000.000000",
"units": "shares",
"credit_rating": null,
"rating_agency": null,
"instrument_type_raw": "Ordinary shares",
"coupon_rate": null,
"yield_percent": null,
"ytm_percent": null,
"issue_date": null,
"maturity_date": null,
"listed_or_unlisted": "Listed — illustrative",
"secured_or_unsecured": null,
"is_shariah_compliant": null,
"is_top_holding": true,
"is_non_compliant": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 2,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"holding_group": "TOP_HOLDINGS",
"rank": 2,
"name_raw": "Example Fertilizer Company",
"holding_type": "EQUITY",
"asset_class": "Equities",
"issuer_name_raw": "Example Fertilizer Company",
"security_name_raw": "Example Fertilizer Company ordinary shares",
"symbol_raw": "EXFERT",
"sector_raw": "Fertilizer",
"percent_of_total_assets": "12.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"percent_held": null,
"market_value": "120600000.0000",
"value_before_provisioning": null,
"provisioning_amount": null,
"value_after_provisioning": null,
"quantity": "800000.000000",
"units": "shares",
"credit_rating": null,
"rating_agency": null,
"instrument_type_raw": "Ordinary shares",
"coupon_rate": null,
"yield_percent": null,
"ytm_percent": null,
"issue_date": null,
"maturity_date": null,
"listed_or_unlisted": "Listed — illustrative",
"secured_or_unsecured": null,
"is_shariah_compliant": null,
"is_top_holding": true,
"is_non_compliant": null
},
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 3,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"holding_group": "TOP_HOLDINGS",
"rank": 3,
"name_raw": "Example Banking Company",
"holding_type": "EQUITY",
"asset_class": "Equities",
"issuer_name_raw": "Example Banking Company",
"security_name_raw": "Example Banking Company ordinary shares",
"symbol_raw": "EXBANK",
"sector_raw": "Banks",
"percent_of_total_assets": "8.000000",
"percent_of_net_assets": null,
"percent_of_gross_assets": null,
"percent_held": null,
"market_value": "80400000.0000",
"value_before_provisioning": null,
"provisioning_amount": null,
"value_after_provisioning": null,
"quantity": "500000.000000",
"units": "shares",
"credit_rating": null,
"rating_agency": null,
"instrument_type_raw": "Ordinary shares",
"coupon_rate": null,
"yield_percent": null,
"ytm_percent": null,
"issue_date": null,
"maturity_date": null,
"listed_or_unlisted": "Listed — illustrative",
"secured_or_unsecured": null,
"is_shariah_compliant": null,
"is_top_holding": true,
"is_non_compliant": null
}
],
"metrics": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"metric_key": "NUMBER_OF_HOLDINGS",
"label_raw": "Illustrative number of equity holdings",
"value": "12.00000000",
"unit": "count",
"period": "September 2026",
"benchmark_value": null
}
],
"fees": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"fee_type": "TOTAL_EXPENSE_RATIO",
"label_raw": "Illustrative annualized total expense ratio",
"value_percent": "2.000000",
"value_amount": null,
"currency": "PKR",
"period": "September 2026 — annualized illustration",
"with_government_levies": true,
"government_levy_percent": null,
"secp_fee_percent": null,
"is_actual_charged": true,
"is_maximum_allowed": false
}
],
"ratings": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"rating_type": "ILLUSTRATIVE",
"rating_raw": "Illustrative rating — not an agency opinion",
"rating_agency": "Example agency (fictional)",
"rating_date": null,
"outlook_raw": null
}
],
"parties": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"role": "FUND_MANAGER",
"name_raw": "Example Research Team",
"designation_raw": "Illustrative fund-management team",
"organization_raw": "Example Asset Management"
}
],
"special_terms": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"term_type": "INVESTMENT_OBJECTIVE",
"label_raw": "Illustrative investment objective",
"value_raw": "A fictional mixed-asset portfolio used only to demonstrate the response model.",
"value_numeric": null,
"value_percent": null,
"value_amount": null,
"value_date": null,
"currency": "PKR"
}
],
"compliance": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"compliance_type": "ILLUSTRATIVE_DISCLOSURE",
"name_raw": "Synthetic compliance disclosure",
"limit_type_raw": null,
"regulatory_limit_percent": null,
"actual_exposure_percent": null,
"excess_percent": null,
"gross_assets_percent": null,
"net_assets_percent": null,
"status_raw": "Illustrative only — no regulatory assessment has been performed"
}
],
"notes": [
{
"sub_fund_key": null,
"sub_fund_name_raw": null,
"row_order": 1,
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"note_kind": "NOTE",
"section_type": "PORTFOLIO",
"note_type": "ILLUSTRATIVE",
"text": "All figures and entities are synthetic. The three reported top holdings are a partial list. Sector percentages use total assets. Credit-quality labels and rating text are not agency opinions."
}
],
"source": [
{
"report_id": "00000000-0000-4000-8000-000000000101",
"page_number": 1,
"document": null,
"promoted_at": "2026-10-08T08:00:00Z",
"data_version": 1
}
],
"sections": {
"sub_funds": {
"status": "NOT_REPORTED",
"row_count": 0
},
"reported_returns": {
"status": "AVAILABLE",
"row_count": 2
},
"allocations": {
"status": "AVAILABLE",
"row_count": 9
},
"holdings": {
"status": "AVAILABLE",
"row_count": 3
},
"metrics": {
"status": "AVAILABLE",
"row_count": 1
},
"fees": {
"status": "AVAILABLE",
"row_count": 1
},
"ratings": {
"status": "AVAILABLE",
"row_count": 1
},
"parties": {
"status": "AVAILABLE",
"row_count": 1
},
"special_terms": {
"status": "AVAILABLE",
"row_count": 1
},
"compliance": {
"status": "AVAILABLE",
"row_count": 1
},
"notes": {
"status": "AVAILABLE",
"row_count": 1
},
"source": {
"status": "AVAILABLE",
"row_count": 1
}
},
"available_expansions": [
"allocations",
"compliance",
"fees",
"holdings",
"metrics",
"notes",
"parties",
"ratings",
"reported_returns",
"source",
"special_terms",
"sub_funds"
]
},
"meta": {
"request_id": "00000000000040008000000000000401",
"generated_at": "2026-10-08T08:00:00Z",
"data_as_of": "2026-09-30",
"data_freshness_days": 8
}
}Inspect the latest NAV model
{
"success": true,
"data": [
{
"fund_id": "00000000-0000-4000-8000-000000000201",
"fund_slug": "example-research-fund",
"fund_name": "Example Research Fund",
"mufap_fund_id": null,
"nav_date": "2026-09-30",
"nav": "100.500000",
"offer_price": "100.500000",
"repurchase_price": "100.500000",
"market_price": null,
"front_end_load_pct": "0.000000",
"back_end_load_pct": "0.000000",
"contingent_load_pct": null,
"nav_change_abs": null,
"nav_change_pct": null,
"currency": "PKR"
}
],
"meta": {
"request_id": "00000000000040008000000000000402",
"generated_at": "2026-10-08T08:00:00Z",
"data_as_of": "2026-09-30",
"data_freshness_days": 8
}
}Sources & further reading
Check the published contract for current fields and limits. Source documents describe reported facts; API availability still depends on promoted production coverage.
Put the guide to work.
Start with the documented contract, keep your key server-side, and make dates and missing data visible in your product.
Review NAV precision and date semantics