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

# Earnings Calendar

> Query stock earnings calendar by date range and market area (cn/hk/us). Returns fiscal year, quarter, and filing dates for earnings reports

## 查询股票财报日历

**URL:** `/v1/stock/earnings-calendar`\
**方法:** `POST`\
**描述:** 根据市场区域和日期范围查询股票财报发布日历。

### 请求参数

| 参数名         | 类型     | 必填 | 描述                        |
| ----------- | ------ | -- | ------------------------- |
| market      | string | 是  | 股票市场：cn（中国）、hk（香港）、us（美国） |
| symbol      | string | 否  | 股票代码（可选，用于查询特定股票）         |
| start\_date | string | 是  | 开始日期（格式：YYYY-MM-DD）       |
| end\_date   | string | 是  | 结束日期（格式：YYYY-MM-DD）       |

### 响应参数

| 参数名     | 类型      | 描述       |
| ------- | ------- | -------- |
| status  | integer | HTTP 状态码 |
| code    | integer | 业务状态码    |
| message | string  | 响应消息     |
| data    | object  | 响应数据     |

#### data 对象结构

| 参数名   | 类型    | 描述       |
| ----- | ----- | -------- |
| items | array | 财报发布项目列表 |

#### 财报项目对象结构

| 参数名         | 类型     | 描述               |
| ----------- | ------ | ---------------- |
| symbol      | string | 股票代码             |
| name        | string | 公司名称             |
| fillingDate | string | 财报发布日期（ISO 8601） |

### 示例代码

#### cURL 示例

```bash theme={null}
curl -X POST "https://api.reportify.cn/v1/stock/earnings-calendar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market": "hk",
    "start_date": "2025-08-01",
    "end_date": "2025-08-31"
  }'
```

#### Python 示例

```python theme={null}
import requests

url = "https://api.reportify.cn/v1/stock/earnings-calendar"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "market": "hk",
    "start_date": "2025-08-01",
    "end_date": "2025-08-31"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(f"状态码: {result['status']}")
print(f"财报发布数量: {len(result['data']['items'])}")

for item in result['data']['items']:
    print(f"\n股票代码: {item['symbol']}")
    print(f"公司名称: {item['name']}")
    print(f"发布日期: {item['fillingDate']}")
```

#### Python 示例（查询特定股票）

```python theme={null}
import requests

url = "https://api.reportify.cn/v1/stock/earnings-calendar"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "market": "cn",
    "symbol": "000300",
    "start_date": "2025-11-20",
    "end_date": "2025-12-31"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result['data']['items']:
    item = result['data']['items'][0]
    print(f"股票代码: {item['symbol']}")
    print(f"公司名称: {item['name']}")
    print(f"财报发布日期: {item['fillingDate']}")
else:
    print("指定股票代码在指定日期范围内没有财报发布")
```

### 响应示例

#### 成功响应（有数据）

```json theme={null}
{
  "status": 200,
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "symbol": "01997",
        "name": "九龙仓置业",
        "fillingDate": "2025-08-07T00:00:00+08:00"
      },
      {
        "symbol": "00087",
        "name": "太古股份公司B",
        "fillingDate": "2025-08-07T00:00:00+08:00"
      },
      {
        "symbol": "00019",
        "name": "太古股份公司A",
        "fillingDate": "2025-08-07T00:00:00+08:00"
      }
    ]
  }
}
```

#### 成功响应（无数据）

```json theme={null}
{
  "status": 200,
  "code": 0,
  "message": "",
  "data": {
    "items": []
  }
}
```

### 注意事项

* **market 参数值**：
  * `cn` - 中国 A 股市场
  * `hk` - 香港股票市场
  * `us` - 美国股票市场
* **日期格式**：`start_date` 和 `end_date` 必须使用 `YYYY-MM-DD` 格式
* **日期范围**：建议查询范围不超过 3 个月，以获得最佳性能
* **symbol 参数**：可选参数，不提供时返回该时间段内所有股票的财报日历
* **时间格式**：`fillingDate` 使用 ISO 8601 格式，包含时区信息
* **排序**：结果按 `fillingDate` 升序排列
* **空响应**：如果 `data.items` 为空数组，说明指定股票代码在指定日期范围内没有财报发布


## OpenAPI

````yaml POST /v1/stock/earnings-calendar
openapi: 3.1.0
info:
  title: Reportify API
  version: 1.0.0
  description: API documentation for Reportify's document management and search services.
servers:
  - url: https://api.reportify.cn
    description: Production server
security:
  - BearerAuth: []
paths:
  /v1/stock/earnings-calendar:
    post:
      tags:
        - openapi-stock-tools
      summary: Stock Earnings Calendar
      description: >-
        Query stock earnings calendar by date range and market area (cn/hk/us).
        Returns fiscal year, quarter, and filing dates for earnings reports
      operationId: stock_earnings_calendar_reportify_api_v1_stock_earnings_calendar_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StockEarningsCalendarInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockAPIResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    StockEarningsCalendarInput:
      properties:
        market:
          type: string
          enum:
            - cn
            - hk
            - us
          title: Market
          description: 'Stock market: cn, hk, or us'
          example: cn
        symbol:
          type: string
          title: Symbol
          description: Stock symbol (optional)
          example: '000300'
        start_date:
          type: string
          title: Start Date
          description: Start date (YYYY-MM-DD)
          example: '2025-11-20'
        end_date:
          type: string
          title: End Date
          description: End date (YYYY-MM-DD)
          example: '2025-12-31'
      type: object
      required:
        - market
        - start_date
        - end_date
      title: StockEarningsCalendarInput
      description: Input schema for StockEarningsCalendarTool
    StockAPIResponse:
      properties:
        status:
          type: integer
          title: Status
          description: HTTP status code
        code:
          type: integer
          title: Code
          description: Response code (0 for success)
        message:
          type: string
          title: Message
          description: Response message
        data:
          type: object
          title: Data
          description: Response data (structure varies by endpoint)
      type: object
      title: StockAPIResponse
      description: Generic response wrapper from stock API
    ErrorResponse:
      properties:
        status:
          type: integer
          title: Status
          description: HTTP status code
        code:
          type: integer
          title: Code
          description: Error code
        message:
          type: string
          title: Message
          description: Error message
      type: object
      title: ErrorResponse
      description: Standard error response
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your Bearer token

````