查詢與工具

Query Examples

提供 query 範例模板，幫助快速建立常見查詢模式。

GET/v2/query/examples

Overview#

Query Examples API 提供可重用的查詢範例模板，幫助快速組裝 `/v2/query` 請求。

範例資料用於開發接線，不代表即時行情或投資建議。

快速建立 query 請求 payload。
作為團隊內欄位契約範本。
搭配 `/v2/query/fields` 驗證欄位可用性。

Request#

可用 `entity_type` 先篩選 issuer/index 範例，再依 `id` 套用到查詢流程。

Query Parameters#

欄位	型別	Required	說明
entity_type	string	no	issuer 或 index。
limit	integer	no	回傳範例筆數上限。

Response Shape#

回應含 examples 陣列，每個項目帶有 query_template，可直接套用到 `/v2/query`。

{
  "api_version": "v2",
  "endpoint": "/v2/query/examples",
  "request_id": "req_qex_91a2b3c4",
  "plan_id": "developer",
  "entity_type": "issuer",
  "examples": [
    {
      "id": "issuer_profile_basic",
      "title": "Issuer 基本資料",
      "description": "查詢公司名稱、交易所與產業欄位。",
      "query_template": {
        "entity_type": "issuer",
        "entity_id": "2330",
        "fields": [
          "company_name",
          "exchange",
          "industry"
        ]
      }
    }
  ],
  "meta": {
    "rows_returned": 1
  }
}

Field 說明#

欄位路徑	型別	說明
examples[].id	string	範例識別碼。
examples[].title	string	範例標題。
examples[].description	string	範例說明。
examples[].query_template	object	可直接轉為 query 參數的模板。
meta.rows_returned	integer	回傳範例筆數。

Usage Notes / 使用建議#

此 endpoint 僅回傳範例模板，不回傳實際資料列。
搭配 `/v2/query` 與 `/v2/query/fields` 使用可降低整合成本。

Plan Requirement#

Routes：/v2/query、/v2/query/fields、/v2/query/examples
實際可用範圍與配額以控制台方案顯示為準

請求與回應

請求範例

curl --request GET \
  --url "https://api.twmarketdata.com/v2/query/examples?entity_type=issuer&limit=5" \
  --header "X-API-Key: your_api_key_here"

狀態碼

成功回傳查詢範例模板

JSON

{
  "api_version": "v2",
  "endpoint": "/v2/query/examples",
  "request_id": "req_qex_91a2b3c4",
  "plan_id": "developer",
  "entity_type": "issuer",
  "examples": [
    {
      "id": "issuer_profile_basic",
      "title": "Issuer 基本資料",
      "description": "查詢公司名稱、交易所與產業欄位。",
      "query_template": {
        "entity_type": "issuer",
        "entity_id": "2330",
        "fields": [
          "company_name",
          "exchange",
          "industry"
        ]
      }
    }
  ],
  "meta": {
    "rows_returned": 1
  }
}

欄位

型別

Required

說明

entity_type

string

issuer 或 index。

limit

integer

回傳範例筆數上限。

Response Shape#

回應含 examples 陣列，每個項目帶有 query_template，可直接套用到 `/v2/query`。

{ "api_version": "v2", "endpoint": "/v2/query/examples", "request_id": "req_qex_91a2b3c4", "plan_id": "developer", "entity_type": "issuer", "examples": [ { "id": "issuer_profile_basic", "title": "Issuer 基本資料", "description": "查詢公司名稱、交易所與產業欄位。", "query_template": { "entity_type": "issuer", "entity_id": "2330", "fields": [ "company_name", "exchange", "industry" ] } } ], "meta": { "rows_returned": 1 } }

欄位路徑

型別

說明

examples[].id

string

範例識別碼。

examples[].title

string

範例標題。

examples[].description

string

範例說明。

examples[].query_template

object

可直接轉為 query 參數的模板。

meta.rows_returned

integer

回傳範例筆數。