Quickstart

Make your first psxdata REST API calls in under 5 minutes.

This guide walks you through four common API calls: confirming the API is reachable, fetching historical price data, listing index constituents, and understanding how errors are returned.

Base URL: https://psxdata-api.fastapicloud.dev

---

Step 1: Health check

Verify that the API is reachable and operational before making data requests.

curl https://psxdata-api.fastapicloud.dev/health

Python

import requests

resp = requests.get("https://psxdata-api.fastapicloud.dev/health")
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://psxdata-api.fastapicloud.dev/health");
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
console.log(data);

Expected response

{
  "data": { "status": "ok" },
  "meta": { "timestamp": "2025-01-15T10:30:00+00:00", "cached": false }
}

A status of "ok" means the API is healthy and accepting requests.

---

Step 2: Fetch historical prices

Retrieve daily OHLCV data for a symbol over a date range. Replace ENGRO with any PSX ticker.

curl "https://psxdata-api.fastapicloud.dev/stocks/ENGRO/historical?start=2025-01-01&end=2025-01-31"

Python

import requests

params = {"start": "2025-01-01", "end": "2025-01-31"}
resp = requests.get(
    "https://psxdata-api.fastapicloud.dev/stocks/ENGRO/historical",
    params=params,
)
resp.raise_for_status()
payload = resp.json()

for row in payload["data"]:
    print(row["date"], row["close"])

JavaScript

const url = new URL("https://psxdata-api.fastapicloud.dev/stocks/ENGRO/historical");
url.searchParams.set("start", "2025-01-01");
url.searchParams.set("end", "2025-01-31");

const resp = await fetch(url);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const payload = await resp.json();

for (const row of payload.data) {
  console.log(row.date, row.close);
}

Expected response

{
  "data": [
    {
      "date": "2025-01-02",
      "open": 286.9,
      "high": 293.5,
      "low": 285.0,
      "close": 291.0,
      "volume": 1234567,
      "is_anomaly": false
    }
  ],
  "meta": {
    "timestamp": "2025-01-15T10:30:00+00:00",
    "cached": false,
    "count": 22
  }
}

meta.count is the total number of trading-day records returned. is_anomaly flags data points that may be suspect due to corporate actions or data-feed issues.

---

Step 3: List index constituents

Fetch the current list of symbols that make up the KSE-100 index.

curl https://psxdata-api.fastapicloud.dev/indices/KSE100

Python

import requests

resp = requests.get("https://psxdata-api.fastapicloud.dev/indices/KSE100")
resp.raise_for_status()
payload = resp.json()

for row in payload["data"]:
    print(row["symbol"], row["idx_weight"])

JavaScript

const resp = await fetch("https://psxdata-api.fastapicloud.dev/indices/KSE100");
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const payload = await resp.json();

for (const row of payload.data) {
  console.log(row.symbol, row.idx_weight);
}

Expected response

{
  "data": [
    {
      "symbol": "ENGRO",
      "current_index": 48250.5,
      "idx_weight": 2.8,
      "idx_point": 135.1,
      "market_cap_m": 245000.0,
      "freefloat_m": 98000.0,
      "shares_m": null
    }
  ],
  "meta": {
    "timestamp": "2025-01-15T10:30:00+00:00",
    "cached": false,
    "count": 100
  }
}

data is a list of constituents. Each row contains symbol, idx_weight (percentage), market_cap_m (millions PKR), and optional freefloat_m or shares_m depending on the index.

---

Step 4: Handle a 404 error

The API returns structured errors for all 4xx and 5xx responses. Requesting a symbol that does not exist produces a 404.

curl -i https://psxdata-api.fastapicloud.dev/stocks/NOTREAL/quote

Python

import requests
from requests.exceptions import HTTPError

try:
    resp = requests.get("https://psxdata-api.fastapicloud.dev/stocks/NOTREAL/quote")
    resp.raise_for_status()
except HTTPError as exc:
    payload = exc.response.json()
    error = payload["error"]
    print(f"Error {error['status']}: [{error['code']}] {error['message']}")

JavaScript

const resp = await fetch("https://psxdata-api.fastapicloud.dev/stocks/NOTREAL/quote");

if (!resp.ok) {
  const payload = await resp.json();
  const { status, code, message } = payload.error;
  console.error(`Error ${status}: [${code}] ${message}`);
}

Expected response (HTTP 404)

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "NOTREAL not found"
  }
}

All errors follow the same envelope shape: an error object with status (HTTP code), code (machine-readable string), and message (human-readable description). See Introduction for the full list of error codes.

---

Next steps

• Introduction — rate limits, error codes, and the response envelope in detail
• API reference — endpoint-by-endpoint reference for all available resources