J-Quants API
View as Markdown

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

  • Missing values and absent records:
    • When a previously published earnings announcement date is later changed to "to be determined", SchDate is an empty string (""). This is normal information indicating that the scheduled date has become undetermined, for example due to a postponement of the earnings announcement; it is not missing or defective data.
  • Fiscal year end (FYE): FYE is the fiscal year end as of the publication date, in 4-digit MMDD format. Only a fiscal year ending at the end of February is expressed as 0299 (99 denotes the month end, because the last day of February varies by year); all other fiscal year ends are expressed as actual dates (e.g., 0331, 1231). Some issues have a fiscal year end that is not a month end (e.g., 0220). When a change of fiscal year end is reported, records with different FYE values coexist in the history for the same issue and fiscal quarter.
  • 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.
  • We do not provide the date and time when each data item became available on J-Quants. For update frequency and approximate update times, see Update Timing of Provided Data.
  • Questions we have received about data specifications are also answered in the FAQ (Data & Specs).

Data correction policy

  • A change of the scheduled date or a change to "to be determined" is added as a new record with a different publication date (PubDate), rather than overwriting the existing record.
  • Previously published records are also retained, so you can retrieve the history of publications and changes of the scheduled date by specifying code.
  • In this service, we may add or overwrite data due to data deficiencies or omissions. In such cases, the correction history is recorded on Data Correction History and Known issues, so please refer to it.
    Note: In these cases, neither the correction history nor pre-correction data is provided via the API, CSV, or other means.

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.

codedatescheduled_dateResults
Publication history of scheduled dates for the specified issue
Scheduled date data published or changed on the specified date, for all issues
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

x-api-keystringrequired

API key

Query Parameters

codestringoptional

Issue code (e.g. 86970 or 8697)

datestringoptional

Publication date (e.g. 20250620 or 2025-06-20)

scheduled_datestringoptional

Scheduled earnings announcement date (e.g. 20250805 or 2025-08-05)

pagination_keystringoptional

String to specify the starting point of the search
Set the pagination_key returned by a previous search

Sample Code

Request

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

Responses

Results

PubDatestring
Publication date (YYYY-MM-DD)
The date on which this scheduled date was published or changed. It means the publication date on which the record actually became available at that point in the past.
SchDatestring
Scheduled earnings announcement date (YYYY-MM-DD)
An empty string ("") when to be determined
FQNamestring
Fiscal quarter (1Q / 2Q / 3Q / FY)
FYEstring
Fiscal year end (MMDD, as of the publication date)
0299 for a fiscal year ending at the end of February
Codestring
Issue code (5 digits)
CoNamestring
Company name (Japanese)
CoNameEnstring
Company name (English)

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

Sample Response

{
    "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."
}

Was this page helpful?