# Earnings Announcement Dates (/fins/earnings-date)

`GET`    /v2/fins/earnings-date

## API Overview

This API provides the earnings announcement dates that listed companies have reported to the Tokyo Stock Exchange.\
It covers all listed issues that have submitted a report (including REITs), regardless of their fiscal year end, and provides the history of changes and "to be determined" announcements on a per-publication-date basis.

### Notes on this API

> **Info**
>
> - When a change to an earnings announcement date is reported, the previous data is not deleted; the revised scheduled date is added as a new record (queries by `code` return all records including the change history).
> - When a previously published earnings announcement date is later changed to "to be determined", SchDate is an empty string (`""`).
> - When querying by `scheduled_date`, only the most recently published record for each issue and fiscal quarter (1Q/2Q/3Q/FY) matches. Therefore, if a scheduled date has since been changed, the record does not match its pre-change scheduled date.
> - The data availability period of each plan is applied based on the publication date (`PubDate`). With `date`, specifying a date outside your plan's accessible range returns a 400 error. With `code` / `scheduled_date`, records published outside the range are not included in the results.

## Retrieve earnings announcement date data

`GET` `https://api.jquants.com/v2/fins/earnings-date`

Exactly one of `code` (issue code), `date` (publication date), or `scheduled_date` (scheduled announcement date) must be specified.\
The combinations of parameters and the corresponding responses are as follows.

- code: ✓, date: –, scheduled\_date: – → Publication history of scheduled dates for the specified issue

- code: –, date: ✓, scheduled\_date: – → Scheduled date data published or changed on the specified date, for all issues

- code: –, date: –, scheduled\_date: ✓ → Data for all issues whose currently effective scheduled announcement date is the specified date

* Specifying two or more parameters at the same time results in a 400 error.\\
* If no matching data exists, an empty array (`"data": []`) is returned.

### Requests

### Headers

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| x-api-key | string | Required | API key     |

### Query Parameters

| Parameter       | Type   | Required | Description                                                                                              |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| code            | string | Optional | Issue code (e.g. 86970 or 8697)                                                                          |
| date            | string | Optional | Publication date (e.g. 20250620 or 2025-06-20)                                                           |
| scheduled\_date | string | Optional | Scheduled earnings announcement date (e.g. 20250805 or 2025-08-05)                                       |
| pagination\_key | string | Optional | String to specify the starting point of the search Set the pagination\_key returned by a previous search |

### Sample Code

/v2/fins/earnings-date

**cURL**

```bash
curl -G https://api.jquants.com/v2/fins/earnings-date \
-H "x-api-key: {{apiKey}}" \
-d code="{{code}}"
```

**JavaScript**

```javascript
import axios from 'axios'

const client = axios.create({
baseURL: 'https://api.jquants.com',
headers: { 'x-api-key': '{{apiKey}}' },
})

await client.get('/v2/fins/earnings-date', {
params: {
  code: '{{code}}',
},
})
```

**Python**

```python
import requests

headers = {"x-api-key": "{{apiKey}}"}
resp = requests.get(
  "https://api.jquants.com/v2/fins/earnings-date",
  params={"code": "{{code}}"},
  headers=headers,
)
print(resp.json())
```

### Responses

### Results

| Parameter | Type   | Required | Description                                                                                    |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| PubDate   | string | Required | Publication date (YYYY-MM-DD) The date on which this scheduled date was published or changed   |
| SchDate   | string | Required | Scheduled earnings announcement date (YYYY-MM-DD) An empty string (`""`) when to be determined |
| FQName    | string | Required | Fiscal quarter (1Q / 2Q / 3Q / FY)                                                             |
| FYE       | string | Required | Fiscal year end (MMDD)                                                                         |
| Code      | string | Required | Issue code (5 digits)                                                                          |
| CoName    | string | Required | Company name (Japanese)                                                                        |
| CoNameEn  | string | Required | Company name (English)                                                                         |

Note: Company names (CoName / CoNameEn) reflect the data as of PubDate.

### Sample Response

```bash {{ title: "200:OK" }}
{
    "data": [
        {
            "PubDate": "2025-06-03",
            "SchDate": "2025-07-30",
            "FQName": "1Q",
            "FYE": "0331",
            "Code": "86970",
            "CoName": "日本取引所グループ",
            "CoNameEn": "Japan Exchange Group,Inc."
        }
    ],
    "pagination_key": "value1.value2."
}
```