US Stock Symbols Directory API Integration Guide

Search active US stock ticker symbols and company names using case-insensitive substring matching. Results are ordered by symbol and paginated. Use the directory for ticker lookup and reference data workflows, not live prices, trading eligibility, or investment recommendations.

Start here: Try the live demo or view the current API details.

API details

Item	Value
API name	US Stock Symbols Directory
Category	Metadata APIs
Method	GET
Endpoint	https://api.gugudata.io/v1/stock/us/symbols
Content type	query parameters
Demo endpoint	https://api.gugudata.io/v1/stock/us/symbols/demo
Detail page	https://gugudata.io/details/us-stock-symbols
OpenAPI JSON	https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json

When to use this API

• Search United States stock symbols and company names.
• Build ticker lookup in finance tools.
• Normalize US market symbol metadata.

Request parameters

This endpoint accepts parameters through the query string. Keep appkey out of client-side public code and send it only from trusted server-side environments.

Parameter	Type	Required	Default	Description
appkey	string	Yes	-	Application key, in the query string only.
query	string	No	Empty	Substring normalized with Unicode NFKC and trimmed; at most 100 Unicode code points, without control characters. Empty input lists all active records.
pageIndex	integer	No	1	One-based page index; values below 1 fail.
pageSize	integer	No	20	Missing or zero uses 20; 1–20 is preserved; values above 20 use 20. Negative values fail.

Example request

curl -G "https://api.gugudata.io/v1/stock/us/symbols" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "query=AAPL" \
  --data-urlencode "pageIndex=1" \
  --data-urlencode "pageSize=20"

Response fields

Successful requests return HTTP 200 and the existing business status code 100. The data field is an array of objects, not strings. No matches return an empty array. If a page is beyond the last page, data is empty but dataTotalCount still reports the total matching records. Do not infer the total from the current page length.

Field	Type	Required	Description
dataStatus	object	Yes	Response metadata. dataStatus.statusCode is a response body status field, not the HTTP status code.
dataStatus.requestParameter	string	Yes	Search and pagination values without AppKey.
dataStatus.statusCode	integer	Yes	Response body status field. Successful demo responses currently return 100.
dataStatus.statusDescription	string	Yes	Response body status message. Successful demo responses currently return a Chinese message.
dataStatus.responseDateTime	string	Yes	Response time in yyyy-MM-dd HH:mm:ss.SSS format.
dataStatus.dataTotalCount	integer	Yes	Total number of records that match the request.
data	array<object>	Yes	Rows on the requested page, at most 20.
data[].symbol	string or null	No	Ticker symbol from the dataset.
data[].stockName	string or null	No	Company name from the dataset.

Response example

This is an illustrative response shape, not a current data or total-count snapshot.

{
  "dataStatus": {
    "statusCode": 100,
    "statusDescription": "请求成功。",
    "responseDateTime": "2026-09-08 10:00:00.123",
    "dataTotalCount": 1,
    "requestParameter": "query=AAPL&pageindex=1&pagesize=20"
  },
  "data": [{"symbol": "AAPL", "stockName": "Apple Inc."}]
}

HTTP status codes

Use the HTTP status code for transport-level handling. If the response body contains dataStatus.statusCode, treat it as an application-level status field in the JSON payload.

HTTP status	Meaning	Recommended handling
200	Request processed successfully.	Parse the documented response body for the endpoint result.
400	Invalid request parameters or request format.	Check required fields, data types, and request body format.
401	Missing or unknown application key.	Send a valid appkey with the request.
403	The application key is recognized but access is not allowed.	Check subscription, trial state, and endpoint access.
429	Request rate or trial usage limit exceeded.	Reduce concurrency or retry after the limit window resets.
500	Internal service error.	Retry later or contact support if the error persists.
503	Directory temporarily unavailable; business code 500.	Handle the failure explicitly and try again later.

Implementation notes

The Demo lists the first page with up to five records. It performs a real directory query and caches successful results for 15 minutes. X-GuGuData-Demo-Mode is live or cached; X-GuGuData-Generated-At identifies generation time. Failure does not create a successful cache entry. A Demo sample is not the complete directory.

• Validate required parameters before sending the request so 400 responses are easier to diagnose.
• Keep server-side retries conservative for 429, 500, and 503 responses.
• Cache stable metadata responses when your use case allows it, especially for lookup and directory endpoints.
• Log the HTTP status code and dataStatus.statusDescription together for easier debugging.
• Use the demo endpoint for a quick connectivity check, then switch to the authenticated endpoint for production data.

FAQ

Where is the official API detail page?

The official detail page is https://gugudata.io/details/us-stock-symbols. It is the best place to review the latest public endpoint information before publishing or integrating.

Should I handle dataStatus.statusCode as the HTTP status code?

No. Use the HTTP status code for request-level behavior such as authentication, permission, rate limiting, and server errors. Use dataStatus.statusCode only as the response body status field when it is present.

Can I use the demo endpoint in production?

No. The demo endpoint is for quick testing and examples. Use the authenticated endpoint with your appkey for production workflows.

Related GuGuData APIs

• HK stock symbols

For more developer APIs, visit GuGuData.