> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/en-docs/rest-api/get-basic-info/get-market-overview.md).

# GET Market Overview Data

### Description

This group of endpoints provides market-level overview data, including market temperature (valuation/sentiment), advance/decline distribution, global indexes, leading industries, daily market commentary, and ranking boards such as top gainers, top losers and popularity.

### Rate Limit

Shares the same rate limit with other endpoints. Refer to [API Rate Limits](https://docs.infoway.io/getting-started/api-limitation).

### Error Codes

Refer to [HTTP Error Codes](https://docs.infoway.io/getting-started/error-codes/http).

### Request Headers

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `apiKey`  | String | Yes      | Your API Key |

### Multi-language Support (I18n)

All endpoints on this page support multi-language responses. Append the `lang` query parameter to control the language of the name-type fields in the response:

| Parameter | Type   | Required | Description                                                | Example |
| --------- | ------ | -------- | ---------------------------------------------------------- | ------- |
| `lang`    | String | No       | `en` for English (default); `zh-CN` for Simplified Chinese | `zh-CN` |

The two languages are cached independently and do not affect each other. Any other value falls back to the default `en` without raising an error.

**Fields affected by `lang`**

| Endpoint                | Field                         | `lang=zh-CN`        | `lang=en`                                                  |
| ----------------------- | ----------------------------- | ------------------- | ---------------------------------------------------------- |
| Global Indexes          | `name`                        | 纳斯达克                | NASDAQ                                                     |
| Leading Industries      | `data.lists[].lists[].name`   | 系统软件                | Systems Software                                           |
| Leading Industries      | `leading_name`                | 中国信息科技              | CHINA INFO TECH                                            |
| Daily Market Commentary | `overview`                    | 香港恒指收盘持平，早盘高开后续回落…… | Hong Kong's HSI closed flat after fading a morning gap-up… |
| Ranking Categories      | `name` / `indicators[].name`  | 全部 / 最新价            | All / Price                                                |
| Ranking Data            | `name`, `indicators.industry` | 辰兴发展                | CHEN XING                                                  |

> \[!WARNING] The **Market Breadth** endpoint returns numeric counts only, with no translatable text field, so `lang` makes no difference there.

### Supported Markets

`HK` (Hong Kong), `US` (United States), `CN` (China A-shares)

***

### Market Temperature

Get market valuation and sentiment temperature (0-100), useful for gauging market heat.

**Endpoint**

* Base path: `/common/v2/basic/market/temperature`
* Full path: `https://data.infoway.io/common/v2/basic/market/temperature`

**Query Parameters**

| Parameter | Type   | Required | Description                                       | Example |
| --------- | ------ | -------- | ------------------------------------------------- | ------- |
| `market`  | String | No       | Market codes, comma-separated. Default `HK,US,CN` | `HK,US` |

**Response Example**

```json
{
  "markets": ["HK", "US"],
  "data": {
    "list": [
      {
        "market": "HK",
        "temp": "69",
        "temp_intro": "Temperature is moderate and rising",
        "valuation": "80",
        "sentiment": "58"
      },
      {
        "market": "US",
        "temp": "36",
        "valuation": "54",
        "sentiment": "18"
      }
    ]
  }
}
```

| Field        | Type   | Description                                  |
| ------------ | ------ | -------------------------------------------- |
| `market`     | String | Market code                                  |
| `temp`       | String | Overall temperature (0-100, higher = hotter) |
| `temp_intro` | String | Temperature description                      |
| `valuation`  | String | Valuation temperature                        |
| `sentiment`  | String | Sentiment temperature                        |

***

### Market Breadth

Get advance/decline distribution statistics.

**Endpoint**

* Base path: `/common/v2/basic/market/breadth/{market}`
* Full path: `https://data.infoway.io/common/v2/basic/market/breadth/{market}`

**Path Parameters**

| Parameter | Type   | Required | Description | Example |
| --------- | ------ | -------- | ----------- | ------- |
| `market`  | String | Yes      | Market code | `HK`    |

**Response Example**

```json
{
  "market": "HK",
  "data": {
    "flatline": 928,
    "rise_less_than_three": 816,
    "rise_three_to_five": 200,
    "rise_five_to_seven": 110,
    "rise_more_than_seven": 128,
    "fall_less_than_three": 686,
    "fall_three_to_five": 154,
    "fall_five_to_seven": 69,
    "fall_more_than_seven": 88
  }
}
```

| Field                  | Type    | Description               |
| ---------------------- | ------- | ------------------------- |
| `flatline`             | Integer | Unchanged stocks          |
| `rise_less_than_three` | Integer | Stocks with <3% gain      |
| `rise_three_to_five`   | Integer | Stocks with 3%-5% gain    |
| `rise_five_to_seven`   | Integer | Stocks with 5%-7% gain    |
| `rise_more_than_seven` | Integer | Stocks with >7% gain      |
| `fall_less_than_three` | Integer | Stocks with <3% decline   |
| `fall_three_to_five`   | Integer | Stocks with 3%-5% decline |
| `fall_five_to_seven`   | Integer | Stocks with 5%-7% decline |
| `fall_more_than_seven` | Integer | Stocks with >7% decline   |

***

### Global Indexes

Get a list of major global market indexes.

**Endpoint**

* Base path: `/common/v2/basic/market/indexes`
* Full path: `https://data.infoway.io/common/v2/basic/market/indexes`

**Response Example**

```json
{
  "data": {
    "indexes": [
      {"counter_id": "IX/US/.DJI", "name": "Dow Jones", "market": "US"},
      {"counter_id": "IX/US/.IXIC", "name": "NASDAQ", "market": "US"},
      {"counter_id": "IX/US/.SPX", "name": "S&P 500", "market": "US"},
      {"counter_id": "IX/HK/HSI", "name": "Hang Seng Index", "market": "HK"},
      {"counter_id": "IX/HK/HSTECH", "name": "Hang Seng TECH", "market": "HK"},
      {"counter_id": "IX/SH/000001", "name": "SSE Composite", "market": "CN"},
      {"counter_id": "IX/SZ/399001", "name": "SZSE Component", "market": "CN"}
    ]
  }
}
```

| Field        | Type   | Description |
| ------------ | ------ | ----------- |
| `counter_id` | String | Index ID    |
| `name`       | String | Index name  |
| `market`     | String | Market      |

***

### Leading Industries

Get today's top-performing industries and their leading stocks.

**Endpoint**

* Base path: `/common/v2/basic/market/leaders/{market}`
* Full path: `https://data.infoway.io/common/v2/basic/market/leaders/{market}`

**Path Parameters**

| Parameter | Type   | Required | Description | Example |
| --------- | ------ | -------- | ----------- | ------- |
| `market`  | String | Yes      | Market code | `HK`    |

**Query Parameters**

| Parameter | Type    | Required | Description                            | Example |
| --------- | ------- | -------- | -------------------------------------- | ------- |
| `limit`   | Integer | No       | Number of industries, 1-50, default 10 | `10`    |

**Response Example**

```json
{
  "market": "HK",
  "data": {
    "lists": [
      {
        "counter_id": "BK/HK/IN20351",
        "name": "Insurance Brokers",
        "chg": "0.1535",
        "leading_name": "ZhongMiao Holdings",
        "leading_last_done": "40.400",
        "leading_chg": "0.1717",
        "rise_num": 2,
        "fall_num": 0
      }
    ]
  }
}
```

| Field               | Type    | Description           |
| ------------------- | ------- | --------------------- |
| `counter_id`        | String  | Industry sector ID    |
| `name`              | String  | Industry name         |
| `chg`               | String  | Industry price change |
| `leading_name`      | String  | Leading stock name    |
| `leading_last_done` | String  | Leading stock price   |
| `leading_chg`       | String  | Leading stock change  |
| `rise_num`          | Integer | Advancing stocks      |
| `fall_num`          | Integer | Declining stocks      |

***

### Daily Market Commentary

Returns an auto-generated commentary of the day's market for the given market, ready to be shown in a homepage market-briefing slot.

**Endpoint**

* Base path: `/common/v2/basic/market/overview/{market}`
* Full path: `https://data.infoway.io/common/v2/basic/market/overview/{market}`

**Path Parameters**

| Parameter | Type   | Required | Description | Example |
| --------- | ------ | -------- | ----------- | ------- |
| `market`  | String | Yes      | Market code | `CN`    |

**Response Example**

```json
{
  "market": "CN",
  "overview": "The Shanghai Composite opened lower but closed up 0.2%, while the ChiNext Index fell 1%. Market breadth was strong with over 4,200 gainers. Lithium carbonate futures plunged about 6% on mine-restart concerns, dragging battery heavyweights and capping growth indices; agriculture and pharmaceuticals led."
}
```

| Field      | Type   | Description                                                                                              |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `market`   | String | Market code                                                                                              |
| `overview` | String | Commentary text, returned in Chinese or English according to `lang`; empty string when not yet available |

***

### Ranking Categories

Lists which ranking boards a market supports (gainers/losers, popularity, pre/post-market, etc.) and the indicators each board can be sorted by. Call this endpoint first to obtain the valid `key` and `sort` values before calling the ranking-data endpoint.

**Endpoint**

* Base path: `/common/v2/basic/market/rank/categories/{market}`
* Full path: `https://data.infoway.io/common/v2/basic/market/rank/categories/{market}`

**Path Parameters**

| Parameter | Type   | Required | Description | Example |
| --------- | ------ | -------- | ----------- | ------- |
| `market`  | String | Yes      | Market code | `CN`    |

**Response Example**

```json
{
  "market": "CN",
  "count": 7,
  "data": [
    {
      "key": "all",
      "name": "All",
      "type": "ST",
      "indicators": [
        { "key": "last_done", "name": "Last Price" },
        { "key": "chg", "name": "Change %" },
        { "key": "total_balance", "name": "Turnover" }
      ]
    }
  ]
}
```

| Field        | Type   | Description                                                                                   |
| ------------ | ------ | --------------------------------------------------------------------------------------------- |
| `key`        | String | Board identifier, used as the `key` path parameter of the ranking-data endpoint               |
| `name`       | String | Board name                                                                                    |
| `type`       | String | Instrument type of the board, `ST`=stock, `BK`=sector                                         |
| `indicators` | Array  | Indicators this board can be sorted by; their `key` values are valid for the `sort` parameter |

> \[!NOTE] The `indicators` array in the example above is truncated — stock boards expose 20+ sortable indicators (`five_min_chg`, `turnover_rate`, `amplitude`, `volume_rate`, `pb_ttm`, `market_cap`, `five_day_chg`, `this_year_chg`, …). Sector boards (`type=BK`) expose a different, shorter set including `rise` / `fall` (number of advancing / declining constituents). The US `us_pre` / `us_post` / `us_overnight` boards additionally expose session-specific indicators (`pre_chg`, `post_chg`, `uson_chg`, …) — use those instead of `chg` to rank by the pre-market, post-market or overnight session move.

Boards currently available per market (subject to upstream change — always trust the live response):

| Market | Boards                                                                                                                                                                                                                                                                                                                 |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CN`   | `all` All, `cn_connect` CN Connect, `cn_gem` GEM, `cn_star` Star, `heat_discuss` Mention, `heat_watchlist` Followers, `bk_industry` Industry Sectors                                                                                                                                                                   |
| `HK`   | `all` All, `hk_main` Main Board, `hk_gem` GEM, `hk_ipo` IPO, `hk_etf` All HK ETFs, `heat_trade` Trending, `heat_discuss` Mention, `heat_watchlist` Followers, `bk_industry` Industry Sectors, `bk_concept` Market Sectors                                                                                              |
| `US`   | `all` All, `us_concept` Chinese Concept, `us_popular` Popular Stocks, `us_etf` All US ETFs, `us_ipo` IPO, `heat_trade` Trending, `heat_discuss` Mention, `heat_watchlist` Followers, `us_pre` Pre Market, `us_post` Post Market, `us_overnight` Overnight, `bk_industry` Industry Sectors, `bk_concept` Market Sectors |

***

### Ranking Data (Top Gainers / Top Losers / Popularity)

Returns the constituents of a board sorted by the given indicator. **Top gainers = `sort=chg&order=desc`; top losers = `sort=chg&order=asc`; most active by turnover = `sort=total_balance&order=desc`.**

**Endpoint**

* Base path: `/common/v2/basic/market/rank/{market}/{key}`
* Full path: `https://data.infoway.io/common/v2/basic/market/rank/{market}/{key}`

**Path Parameters**

| Parameter | Type   | Required | Description                                           | Example |
| --------- | ------ | -------- | ----------------------------------------------------- | ------- |
| `market`  | String | Yes      | Market code                                           | `CN`    |
| `key`     | String | Yes      | Board identifier, see the Ranking Categories endpoint | `all`   |

**Query Parameters**

| Parameter | Type    | Required | Description                                                                    | Example |
| --------- | ------- | -------- | ------------------------------------------------------------------------------ | ------- |
| `sort`    | String  | No       | Sort indicator; must be one of the board's `indicators` keys, default `chg`    | `chg`   |
| `order`   | String  | No       | `desc` descending (top gainers) / `asc` ascending (top losers), default `desc` | `desc`  |
| `limit`   | Integer | No       | Number of results, 1-100, default 30                                           | `30`    |
| `offset`  | Integer | No       | Offset for pagination, default 0                                               | `0`     |

**Response Example**

```json
{
  "market": "CN",
  "key": "all",
  "name": "All",
  "sort": "chg",
  "order": "desc",
  "offset": 0,
  "limit": 1,
  "total": 7377,
  "count": 1,
  "data": [
    {
      "symbol": "300097.SZ",
      "counter_id": "ST/SZ/300097",
      "name": "Zhiyun Stock",
      "delay": false,
      "indicators": {
        "last_done": "10.54",
        "chg": "0.2005",
        "change": "1.76",
        "total_amount": "43060000",
        "total_balance": "453799962"
      }
    }
  ]
}
```

| Field        | Type    | Description                                                                   |
| ------------ | ------- | ----------------------------------------------------------------------------- |
| `total`      | Integer | Total number of instruments in this board (for pagination)                    |
| `count`      | Integer | Number of rows returned                                                       |
| `symbol`     | String  | Instrument code                                                               |
| `counter_id` | String  | Internal instrument ID                                                        |
| `name`       | String  | Instrument name                                                               |
| `delay`      | Boolean | Whether the quote is delayed                                                  |
| `indicators` | Object  | Indicator values, keyed by the indicator `key` values from Ranking Categories |

> \[!WARNING] Note: 1) Ratio-type fields (`chg`, `turnover_rate`, `amplitude`, `five_day_chg`, …) are decimal ratios, not percentages — `0.2005` means +20.05% and `-0.1998` means -19.98%; 2) the `indicators` object in the example above is truncated — the response always contains every indicator of that board (20+ for stock boards), not only the one named by `sort`; 3) when an indicator is not available for an instrument, an empty string `""` is returned (e.g. `five_day_chg` for a newly listed stock), so handle empty values when parsing; 4) `industry` is an industry name string and follows the `lang` parameter.

**Error Codes**

| HTTP | detail                                        | Description                                                                       |
| ---- | --------------------------------------------- | --------------------------------------------------------------------------------- |
| 400  | `Invalid market`                              | Market code is not supported                                                      |
| 400  | `Invalid key for market {market}. Valid: ...` | Board identifier is invalid; the response lists the valid values for that market  |
| 400  | `Invalid sort for key {key}. Valid: ...`      | Sort indicator does not belong to this board; the response lists the valid values |
| 400  | `Invalid order, must be desc or asc`          | Sort direction is invalid                                                         |

***