> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tickdb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 其他日曆

> 按類別查詢宏觀數據、休市、會議等其他財經事件。

## 套餐權限

| 套餐 | 可用 |
| - | :-: |
| 免費版 | ❌ |
| 基礎版 | ✅ |
| 專業版 | ✅ |
| 全量套餐（A 股、港股、美股） | ✅ |
| 企業版 | ✅ |

## 注意事項

* 必須傳入一種 `category`；財報、股息、拆股和新股事件請使用各自的專用日曆接口。
* `from` 預設為目前 UTC 日期；`to` 預設為 `from` 後 7 天。日期範圍包含兩端。
* 預設每頁 100 條，最多 500 條。第一頁不傳 `cursor`；後續保持篩選條件不變，並將上一頁的 `page.next_cursor` 原樣傳入，直到其為 `null`。若首次未傳日期，後續頁請使用首個回應的 `data.from`、`data.to` 固定日期範圍。
* API Key 僅允許部分市場時，必須傳入獲准的 `market`；沒有對應事件時返回空 `events` 陣列。

## 支援市場

| 市場 | 示例 |
| - | - |
| 美股 | US |
| 港股 | HK |
| A股 | CN |

## 請求參數

| 參數 | 必填 | 說明 |
| - | :-: | - |
| `from` | 否 | 開始日期，格式 `YYYY-MM-DD` |
| `to` | 否 | 結束日期，格式 `YYYY-MM-DD` |
| `category` | 是 | 其他事件類別，取值見下表 |
| `market` | 否\* | 市場篩選：`US`、`HK`、`CN`；市場受限的 API Key 必填 |
| `symbols` | 否 | 股票代碼，以英文逗號分隔，最多 50 個 |
| `limit` | 否 | 每頁數量，`1–500`，預設 `100` |
| `cursor` | 否 | 下一頁遊標；第一頁不傳 |

## category 取值

| 取值 | 說明 |
| - | - |
| `macrodata` | 宏觀經濟數據公布 |
| `closed` | 市場休市 |
| `meeting` | 會議 |
| `merge` | 併購與合併 |
| `halt_resume` | 停復牌 |
| `special_treatment` | 特別處理 |
| `special_treatment_start` | 特別處理開始 |
| `special_treatment_end` | 特別處理結束 |
| `listing_status` | 上市狀態 |
| `listing_suspension` | 暫停上市 |
| `listing_resumption` | 恢復上市 |
| `delisting` | 退市 |
| `lockup_expiry` | 限售股解禁 |

## 請求範例

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.tickdb.ai/v1/fundamentals/calendar/other?from=2026-09-21&to=2026-09-28&market=US&category=macrodata&limit=100"
```

## 返回欄位說明

成功回應包含頂層 `code`、`data` 和 `page`。

| 欄位 | 說明 |
| - | - |
| code | 業務狀態碼，成功為 `0`。 |
| data | 當前頁的日期範圍和事件資料。 |
| └─ from | 查詢開始日期，`YYYY-MM-DD`。 |
| └─ to | 查詢結束日期，`YYYY-MM-DD`。 |
| └─ events | 當前頁事件列表；無事件時為空陣列。 |
|   └─ event\_datetime | 事件時間，UTC 日期時間字串。 |
|   └─ market | 所屬市場。 |
|   └─ symbol | 關聯產品代碼；不適用時可能為空。 |
|   └─ category | 事件細分類別，可能比請求類別更具體。 |
|   └─ event\_type | 事件類型。 |
|   └─ content | 事件內容。 |
|   └─ counter\_name | 關聯名稱；可能為 `null`。 |
|   └─ currency | 幣種；可能為 `null`。 |
|   └─ star | 重要程度。 |
|   └─ date\_type | 事件日期類型；可能為 `null`。 |
|   └─ data | 可選的事件附加資料陣列。 |
|     └─ key | 附加資料鍵名。 |
|     └─ value\_raw | 原始值；可能為 `null`。 |
|     └─ value\_text | 顯示值；可能為 `null`。 |
|     └─ value\_type | 值類型。 |
| page | 分頁資訊。 |
| └─ next\_cursor | 下一頁遊標；末頁為 `null`。 |
| └─ limit | 當前分頁上限。 |


## OpenAPI

````yaml openapi.zh-Hant.yaml GET /v1/fundamentals/calendar/other
openapi: 3.1.0
info:
  title: TickDB API
  description: TickDB 統一即時行情數據 API，提供 REST 和 WebSocket 接入。
  version: 1.0.3
  contact:
    email: support@tickdb.ai
servers:
  - url: https://api.tickdb.ai
    description: 正式環境
security:
  - ApiKeyAuth: []
paths:
  /v1/fundamentals/calendar/other:
    get:
      tags:
        - fundamentals-events
      summary: 其他日曆
      description: 按類別查詢宏觀數據、休市、會議等其他財經事件。
      operationId: getFundamentalsCalendarOther
      parameters:
        - $ref: '#/components/parameters/CalendarFromQuery'
        - $ref: '#/components/parameters/CalendarToQuery'
        - $ref: '#/components/parameters/CalendarOtherCategoryQuery'
        - $ref: '#/components/parameters/CalendarMarketQuery'
        - $ref: '#/components/parameters/CalendarSymbolsQuery'
        - $ref: '#/components/parameters/CalendarLimitQuery'
        - $ref: '#/components/parameters/CursorQuery'
      responses:
        '200':
          $ref: '#/components/responses/CalendarResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  parameters:
    CalendarFromQuery:
      name: from
      in: query
      required: false
      schema:
        type: string
        format: date
      description: 開始日期，格式 `YYYY-MM-DD`
    CalendarToQuery:
      name: to
      in: query
      required: false
      schema:
        type: string
        format: date
      description: 結束日期，格式 `YYYY-MM-DD`
    CalendarOtherCategoryQuery:
      name: category
      in: query
      required: true
      schema:
        type: string
        enum:
          - macrodata
          - closed
          - meeting
          - merge
          - halt_resume
          - special_treatment
          - special_treatment_start
          - special_treatment_end
          - listing_status
          - listing_suspension
          - listing_resumption
          - delisting
          - lockup_expiry
      description: 其他事件類別，取值見下表
    CalendarMarketQuery:
      name: market
      in: query
      required: false
      schema:
        type: string
        enum:
          - US
          - HK
          - CN
      description: 市場篩選：`US`、`HK`、`CN`；市場受限的 API Key 必填
    CalendarSymbolsQuery:
      name: symbols
      in: query
      required: false
      schema:
        type: string
        minLength: 1
        examples:
          - AAPL.US
          - AAPL.US,700.HK,600519.SH
      description: 股票代碼，以英文逗號分隔，最多 50 個
    CalendarLimitQuery:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
      description: 每頁數量，`1–500`，預設 `100`
    CursorQuery:
      name: cursor
      in: query
      required: false
      schema:
        type: string
        minLength: 1
      description: 下一頁遊標；第一頁不傳
  responses:
    CalendarResponse:
      description: 財報日曆回應。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CalendarEnvelope'
    ErrorResponse:
      description: >-
        錯誤回應。常見 HTTP 狀態包括
        400（參數錯誤）、401（驗證失敗）、403（權限或配額限制）、404（無符合條件的數據）、429（請求頻率限制）及 503（服務暫不可用）。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            missingAPIKey:
              summary: 缺少 API Key
              value:
                code: '1002'
                message: API key is required. Provide via X-API-Key header
                error: '1002'
            missingKind:
              summary: 缺少必填參數
              value:
                code: 40001
                message: kind is required
                data: null
            endpointForbidden:
              summary: API Key 無權存取此介面
              value:
                code: 3009
                message: This endpoint is not allowed for your API key
                data: null
            marketForbidden:
              summary: API Key 未開放該市場
              value:
                code: 3010
                message: Fundamentals market not allowed for your API key
                data:
                  market: US
            noAvailableSource:
              summary: 數據暫不可用
              value:
                code: 5003
                message: Data is temporarily unavailable
                data: null
            notFound:
              summary: 無符合條件的數據
              value:
                code: 40404
                message: shareholder detail not found
                data: null
            businessNoData:
              summary: 查詢條件沒有有效業務數據
              value:
                code: 40405
                message: valuation time series not found
                data: null
  schemas:
    CalendarEnvelope:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          required:
            - page
          properties:
            data:
              $ref: '#/components/schemas/CalendarData'
            page:
              $ref: '#/components/schemas/CalendarPage'
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: TickDB API 業務錯誤碼；可能是整數或字串，客戶端應先轉為字串再比較。
          oneOf:
            - type: integer
            - type: string
        message:
          type: string
          description: 錯誤說明。
        error:
          type: string
          description: 相容錯誤標識；僅部分錯誤回應返回。
        data:
          description: 可選的錯誤上下文；可能是 null、物件或陣列。
          oneOf:
            - type: 'null'
            - type: object
              additionalProperties: true
            - type: array
              items: {}
    SuccessEnvelope:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          const: 0
          description: 業務狀態碼，成功為 `0`。
    CalendarData:
      type: object
      required:
        - from
        - to
        - events
      properties:
        from:
          type: string
          format: date
          description: 查詢開始日期，`YYYY-MM-DD`。
        to:
          type: string
          format: date
          description: 查詢結束日期，`YYYY-MM-DD`。
        events:
          type: array
          description: 當前頁事件列表；無事件時為空陣列。
          maxItems: 500
          items:
            $ref: '#/components/schemas/FullCalendarEvent'
      additionalProperties: false
    CalendarPage:
      type: object
      required:
        - next_cursor
        - limit
      properties:
        next_cursor:
          type:
            - string
            - 'null'
          description: 下一頁遊標；末頁為 `null`。
        limit:
          type: integer
          minimum: 1
          maximum: 500
          description: 當前分頁上限。
      additionalProperties: false
    FullCalendarEvent:
      type: object
      required:
        - category
        - content
        - counter_name
        - currency
        - date_type
        - event_datetime
        - event_type
        - market
        - star
        - symbol
      properties:
        category:
          type: string
          description: 事件細分類別，可能比請求類別更具體。
        event_datetime:
          type: string
          format: date-time
          description: 事件時間，UTC 日期時間字串。
        symbol:
          type: string
          description: 關聯產品代碼；不適用時可能為空。
        market:
          type: string
          enum:
            - US
            - HK
            - CN
          description: 所屬市場。
        event_type:
          type: string
          description: 事件類型。
        content:
          type: string
          description: 事件內容。
        counter_name:
          type:
            - string
            - 'null'
          description: 關聯名稱；可能為 `null`。
        date_type:
          type:
            - string
            - 'null'
          description: 事件日期類型；可能為 `null`。
        star:
          type: integer
          description: 重要程度。
        currency:
          type:
            - string
            - 'null'
          description: 幣種；可能為 `null`。
        issue_price:
          type:
            - string
            - 'null'
          description: 新股發行價格；僅相關事件返回，價格不可用時為 `null`。
        data:
          type: array
          description: 事件附加資料；沒有附加資料時省略。
          items:
            $ref: '#/components/schemas/CalendarEventData'
      additionalProperties: false
    CalendarEventData:
      type: object
      required:
        - key
        - value_type
        - value_text
        - value_raw
      properties:
        key:
          type: string
          description: 附加資料鍵名。
        value_type:
          type: string
          description: 值類型。
        value_text:
          type:
            - string
            - 'null'
          description: 顯示值；可能為 `null`。
        value_raw:
          type:
            - string
            - 'null'
          description: 原始值；可能為 `null`。
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.