# HK Stock Symbols Directory
Search active Hong Kong stock symbols and company names.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** GET
- **HTTP Endpoint:** https://api.gugudata.io/v1/stock/hk/symbols
- **Response Type:** application/json; charset=utf-8
- **DEMO Endpoint:** https://api.gugudata.io/v1/stock/hk/symbols/demo
- **Live Demo:** https://gugudata.io/demo/hk-stock-symbols
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/hk-stock-symbols/llm
- **Raw Markdown:** https://gugudata.io/details/hk-stock-symbols/llm.md
## Remote MCP
- **MCP Endpoint:** https://mcp.gugudata.io/mcp
- **MCP Guide:** https://gugudata.io/mcp/
- **Authorization:** OAuth authorization opens in the browser; do not paste appkeys into MCP clients.
- **Tool Scope:** MCP clients receive GuGuData API tools available to the authorized account.
## Data & API Features
- Active Hong Kong-listed symbols: Browse a maintained directory of active securities identified by their five-digit market symbols.
- English and Chinese name search: Search by symbol, exchange English short name, or Chinese display name from one endpoint.
- Stable symbol-ordered pagination: Build predictable directories and selectors with ordered pages and a total matching record count.
- Symbol validation: Check user-supplied Hong Kong symbols before using them in portfolios, research, or market-data workflows.
- Security selector enrichment: Display recognizable English and Chinese names alongside five-digit symbols in finance applications.
- Reference-data workflows: Support watchlists, onboarding, portfolio tools, security masters, and research interfaces without quote data.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| query | string | false | | Optional case-insensitive substring matched against the five-digit symbol, English short name, and Chinese display name. Unicode NFKC normalization and surrounding whitespace trimming apply; maximum 100 Unicode characters. |
| pageIndex | integer | false | 1 | One-based page index. Values below 1 return HTTP and business status 400. |
| pageSize | integer | false | 20 | Records per page. Omitted or zero uses 20, values from 1 to 20 are preserved, values above 20 are reduced to 20, and negative values return HTTP and business status 400. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| dataStatus | object | Response metadata for the directory lookup. |
| dataStatus.requestParameter | string | Privacy-safe summary of the normalized request. |
| dataStatus.statusCode | integer | Application-level status code. |
| dataStatus.statusDescription | string | Human-readable application status message. |
| dataStatus.responseDateTime | string | Time at which the response was generated. |
| dataStatus.dataTotalCount | integer | Number of matching or returned records for this request. |
| data | array<object> | Symbol-ordered result page. The array is empty when no records match. |
| data[].symbol | string | Five-digit Hong Kong-listed security symbol. |
| data[].stockName | string | Exchange English short name. |
| data[].stockChineseName | string | Chinese display name. |
## API Response Status Codes
| Status Code | Explanation of Status Code | Remarks |
| --- | --- | --- |
| 200 | Request processed successfully. | Some endpoints expose a separate application-level status field in the response body, such as `dataStatus.statusCode`. |
| 400 | Invalid request parameters or request format. | Check required fields, data types, and request body format. |
| 401 | Missing or unknown application key. | Provide a valid `appkey` with the request. |
| 403 | The application key is recognized but access is not allowed. | The key may be expired, inactive, or not permitted for the requested API. |
| 429 | Request rate or trial usage limit exceeded. | Reduce request frequency and retry with backoff. If a trial allowance is exhausted, check Trial Keys for remaining requests and subscribe to continue. |
| 500 | Internal service error. | Retry later or contact support if the error persists. |
| 503 | The symbol directory is temporarily unavailable. | Retry later or contact support if the error persists. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/v1/stock/hk/symbols?appkey=YOUR_APPKEY&query=YOUR_VALUE&pageIndex=1&pageSize=20'
```