Stock Screening API

Overview

GET /v1/finance/stock/screen filters all A-share stocks by multi-dimensional criteria and returns a sorted list. All filter parameters are optional — pass only the ones you care about.

With no filters, you get the daily change_pct leaderboard.

When to Use

Find stocks in a specific industry: "Banking stocks" → industry=银行
Find theme/concept stocks: "AI stocks" → concept=AI
Filter by valuation: "PE < 15 stocks" → pe_max=15
Filter by market cap: "Large caps", "Small caps" → min_market_cap / max_market_cap
Find high-dividend stocks: "Dividend yield > 3%" → min_dividend_yield=3
Quick preset combinations: Use filter_preset for one-click classic strategies
Daily change leaderboard: No filters → defaults to change_pct desc

Request Parameters

Parameter	Type	Required	Default	Description
`industry`	string	No	-	Fuzzy match on industry name (e.g. `银行`, `医药`)
`concept`	string	No	-	Fuzzy match on concept/theme (e.g. `AI`, `半导体`)
`pe_min`	float	No	-	PE lower bound
`pe_max`	float	No	-	PE upper bound
`pb_max`	float	No	-	PB upper bound
`min_market_cap`	float	No	-	Min total market cap (in CNY)
`max_market_cap`	float	No	-	Max total market cap (in CNY)
`min_dividend_yield`	float	No	-	Min dividend yield (%)
`filter_preset`	string	No	-	Preset combination (see below)
`sort_by`	string	No	`change_pct`	Sort field
`order`	string	No	`desc`	Sort direction: `desc` / `asc`
`limit`	int	No	`20`	Max results (1-100)

Filter Presets

Presets are shortcuts for common filter combinations:

Preset	Equivalent Conditions	Use Case
`low_pe_high_div`	PE < 15 AND dividend yield > 3%	Value / dividend strategy
`small_cap_growth`	Market cap < 10B CNY	Small/mid-cap growth
`large_cap_stable`	Market cap > 50B CNY AND PE < 20	Blue-chip stable

Sort Fields

Field	Meaning
`change_pct` (default)	Daily price change %
`pe`	Price-to-earnings ratio
`pb`	Price-to-book ratio
`market_cap`	Total market capitalization
`turnover_rate`	Turnover rate
`dividend_yield`	Dividend yield
`volume`	Trading volume

Request Examples

Daily Leaderboard (no filters)

curl -H "X-API-Key: sk_gapi_xxxxx" \
  "https://api.groundapi.net/v1/finance/stock/screen?limit=10"

Cheap Bank Stocks

curl -H "X-API-Key: sk_gapi_xxxxx" \
  "https://api.groundapi.net/v1/finance/stock/screen?industry=银行&pe_max=10&limit=10"

AI Concept Stocks Sorted by Market Cap

curl -H "X-API-Key: sk_gapi_xxxxx" \
  "https://api.groundapi.net/v1/finance/stock/screen?concept=AI&sort_by=market_cap&limit=15"

High-Dividend Strategy (Using Preset)

curl -H "X-API-Key: sk_gapi_xxxxx" \
  "https://api.groundapi.net/v1/finance/stock/screen?filter_preset=low_pe_high_div&limit=20"

Blue Chips (Market Cap > 100B AND PE < 20)

curl -H "X-API-Key: sk_gapi_xxxxx" \
  "https://api.groundapi.net/v1/finance/stock/screen?min_market_cap=100000000000&pe_max=20&sort_by=market_cap"

Response Example

{
  "success": true,
  "data": {
    "filter_preset": null,
    "sort_by": "change_pct",
    "order": "desc",
    "count": 3,
    "items": [
      {
        "symbol": "002948.SZ",
        "name": "Qingdao Bank",
        "price": 6.05,
        "change_pct": 7.0796,
        "pe": 5.78,
        "pb": 0.83,
        "total_market_cap": 35213146080.0,
        "turnover_rate": 3.93,
        "dividend_yield": null,
        "volume_ratio": 2.68
      }
    ]
  }
}

Notes

Data comes from local snapshots synced after market close (~15:35 CST). Not real-time.
industry and concept use fuzzy match — finds all entries containing the string
industry = GICS-style taxonomy (banking, pharma); concept = themes (AI, state-owned)
Empty result returns items: [], not an error
Max 100 results per call; for more, use more specific filters and paginate

After getting candidate codes, use GET /v1/finance/stock for details
Not sure of industry/concept name? Try GET /v1/finance/search first

Pricing

$0.02/call. First 500 calls/month are free.