Factor screening for China A-shares with one API call

1. What factor screening is (30 seconds)

A factor is a computable metric: `PE_TTM` (price/earnings), `ROETTM` (return on equity), `DividendRatioTTM` (dividend yield), `DebtAssetsRatio` (debt ratio) and so on. Factor screening writes these into conditions and filters the whole market of 5,000+ stocks.

It replaces manually reading financial statements — turning an idea like "cheap + profitable + low debt" into a reproducible, backtestable rule.

• Reproducible: the same conditions give the same result every time
• Backtestable: with `--date` you can screen on a past day variation of factor values
• Not investment advice: screening only filters by objective conditions — being selected does not mean you should buy

2. Quick start: one request for low-PE, high-ROE

`/v1/screen` is a paid endpoint (needs a Key). The most common form is `expr` with a multi-factor intersection — `intersect([...])` means all conditions must hold.

import requests

BASE = "https://api.ashareapi.com/v1"
H = {"Authorization": "Bearer ct-your-key"}   # Key: https://ashareapi.com/pricing

r = requests.get(
    f"{BASE}/screen",
    params={
        "expr": "intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15])",
        "orderby": "ROETTM",
        "desc": "1",
        "limit": 5,
    },
    headers=H,
    timeout=30,
)
body = r.json()
if not body.get("ok"):
    raise RuntimeError(body)                  # upstream failure returns ok=false (not counted)

for row in body["structured"]:                # structured = machine-readable rows
    print(row["code"], row["name"], row["PE_TTM"], row["ROETTM"])

• `PE_TTM > 0` is a required guard — loss-making companies have negative PE and would otherwise appear as "low PE"
• Percentage factors take plain numbers: `ROETTM > 15` means "above 15%" (not `0.15`)
• Values are strings ("14.33") — call `float()` before arithmetic

3. What the result looks like (live run, 2026-09-29)

Real output of the request above (limit=5); `structured` is the machine-readable form:

Do not celebrate yet — the first row (PE_TTM=0.36, ROETTM=883%) is exactly the kind of value you need to inspect. The next section shows how.

4. The 3-step data health check (important)

A factor value is a number a machine computed — not the company true operating picture. When you see extremes (very low PE, very high ROE, huge growth), cross-check with other fields from the same financial statement:

def health_check(code: str) -> None:
    # Inspect factor values: multi-metric ROE, ex-non-recurring, leverage, current profit
    r = requests.get(f"{BASE}/finance", params={"code": code, "limit": 1},
                     headers=H, timeout=30)
    tables = r.json()["data"]        # 3 tables: income / balance sheet / cash flow
    income, balance = tables[0][0], tables[1][0]

    print(code)
    print("  ROE variants:", income.get("ROE"), "/", income.get("ROETTM"),
          "/", income.get("ROEWeighted"), "/ ex-non-recurring", income.get("ROECut"))
    print("  Profit current:", income.get("NPParentCompanyOwners"),
          " TTM:", income.get("NPParentCompanyOwnersTTM"))
    print("  Debt ratio:", balance.get("DebtAssetsRatio"), "%  equity:",
          balance.get("TotalShareholderEquity"))

    try:
        if float(income.get("ROECut") or 0) < 0:
            print("  [!] ex-non-recurring ROE is negative - profit may be non-recurring")
        if float(balance.get("DebtAssetsRatio") or 0) > 70:
            print("  [!] debt ratio above 70% - ROE may be leveraged")
    except (TypeError, ValueError):
        pass

health_check("sz000656")

• 1) Check ex-non-recurring: `ROECut` and `NPDeductNonRecurringPL`. If `ROETTM` is high but `ROECut` is negative, profit likely comes from non-recurring items (asset sales, debt restructuring), not the core business
• 2) Check multi-metric consistency: the same statement carries `ROE` / `ROETTM` / `ROEWeighted` / `ROECut`. If they differ by orders of magnitude (e.g. 0.44 vs 883), one of them is distorted — do not use it directly
• 3) Check leverage and the current period: `DebtEquityRatio` / `DebtAssetsRatio` (leverage inflates ROE) plus `NPParentCompanyOwners` (current-period profit). If TTM profit is far from the current period, the TTM value is suspect

5. Real case: what that 883% ROE actually is

The screened name sz000656 Jinke Property (PE_TTM 0.36 / ROETTM 883%) — one health check reveals the problem. From the same statement:

• The verdict is not a hunch: within one statement, ROE=0.44 vs ROETTM=883 (~2000x), ex-non-recurring is negative, and TTM vs current profit diverge — the bases contradict each other, so this ROETTM should not be used as-is
• Correct handling: this does not mean "the stock is bad", it means "this factor value is unreliable" — switch basis (use `ROECut`) or skip it
• This is exactly why the check is mandatory: the API faithfully returns every basis; whether to exclude is a rule the consumer applies (we give no buy/sell conclusions)

6. Common factors cheat sheet

All 85 factors (6 valuation / 2 market / 38 profitability / 32 balance sheet / 14 cash flow) and 14 templates — see "Expression syntax and factor dictionary".