J-Quants API

https://jpx.gitbook.io/j-quants-ja/
Admin
J-Quants API is a financial data service that provides historical stock prices and corporate...
Tokens:142,093
Snippets:371
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Fetch Short Selling Positions (Python)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/short_selling_positions

Example of how to fetch short selling positions data using Python's requests library. It demonstrates setting up headers with an idToken and making a GET request.

```Python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/markets/short_selling_positions?code=86970&calculated_date=20240801", headers=headers)
r.json()
```

--------------------------------

### API Call Sample - Python

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/futures

Example of how to call the Futures API using Python's requests library. It shows how to set up the headers with the authorization token and make a GET request to the API.

```python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/derivatives/futures?date=20230324", headers=headers)
r.json()
```

--------------------------------

### Example API Call (Python)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trading_calendar

This Python code snippet shows how to fetch trading calendar data using the requests library. It sets up the necessary headers with an authorization token and makes a GET request to the API endpoint with specified query parameters.

```Python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/markets/trading_calendar?holidaydivision=1&from=20220101&to=20221231", headers=headers)
r.json()
```

--------------------------------

### Example Error Response (Unexpected Error)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/short_selling_positions

An example of an error response for an unexpected server-side issue.

```JSON
{
    "message": "Unexpected error. Please try again later."
}
```

--------------------------------

### Fetch Dividend Data (Python)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/dividend

Example of how to fetch dividend data using Python's requests library. It demonstrates setting up the authorization header with an idToken and making a GET request to the dividend API.

```python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/fins/dividend?code=86970", headers=headers)
r.json()
```

--------------------------------

### J-Quants API Reference

Source: https://jpx.gitbook.io/j-quants-ja/api-reference

This section outlines the J-Quants API specifications, detailing various endpoints for accessing financial data. It includes information on quick start guides, common API considerations, and how to read the API documentation.

```APIDOC
API Reference:

Quick Start Guide:
  - Link: https://colab.research.google.com/github/J-Quants/jquants-api-quick-start/blob/master/jquants-api-quick-start.ipynb
  - Description: Provides a quick start guide using Google Colaboratory for the J-Quants API.

API Common Considerations:
  - Link: https://jpx.gitbook.io/j-quants-ja/api-reference/attention
  - Description: Refers to common important notes regarding API usage.

How to Read API Specifications:
  - Link: https://jpx.gitbook.io/j-quants-ja/api-reference/howtoread
  - Description: Explains how to interpret the API specification pages.

Access Key Related (/token):
  - Refresh Token Acquisition (/token/auth_user): https://jpx.gitbook.io/j-quants-ja/api-reference/refreshtoken
  - ID Token Acquisition (/token/auth_refresh): https://jpx.gitbook.io/j-quants-ja/api-reference/idtoken

Listed Company Information (/listed):
  - Listed Company List (/listed/info): https://jpx.gitbook.io/j-quants-ja/api-reference/listed_info

Stock Price Related (/prices):
  - Daily OHLC Prices (/prices/daily_quotes): https://jpx.gitbook.io/j-quants-ja/api-reference/daily_quotes
  - Morning Session OHLC Prices (/prices/prices_am): https://jpx.gitbook.io/j-quants-ja/api-reference/prices_am

Market Information Related (/markets):
  - Investment Segment Information (/markets/trades_spec): https://jpx.gitbook.io/j-quants-ja/api-reference/trades_spec
  - Margin Trading Weekly Balance (/markets/weekly_margin_interest): https://jpx.gitbook.io/j-quants-ja/api-reference/weekly_margin_interest
  - Sector Short Selling Ratio (/markets/short_selling): https://jpx.gitbook.io/j-quants-ja/api-reference/short_selling
  - Short Selling Position Report (/markets/short_selling_positions): https://jpx.gitbook.io/j-quants-ja/api-reference/short_selling_positions
  - Trading Breakdown Data (/markets/breakdown): https://jpx.gitbook.io/j-quants-ja/api-reference/breakdown
  - Trading Calendar (/markets/trading_calendar): https://jpx.gitbook.io/j-quants-ja/api-reference/trading_calendar

Index Information (/indices):
  - TOPIX Index OHLC (/indices/topix): https://jpx.gitbook.io/j-quants-ja/api-reference/topix

Financial Information Related (/fins):
  - Financial Information (/fins/statements): https://jpx.gitbook.io/j-quants-ja/api-reference/statements
  - Financial Statements (BS/PL) (/fins/fs_details): https://jpx.gitbook.io/j-quants-ja/api-reference/statements-1
  - Dividend Information (/fins/dividend): https://jpx.gitbook.io/j-quants-ja/api-reference/dividend
  - Earnings Announcement Schedule (/fins/announcement): https://jpx.gitbook.io/j-quants-ja/api-reference/announcement

Option Information (/option):
  - Nikkei 225 Option OHLC (/option/index_option): https://jpx.gitbook.io/j-quants-ja/api-reference/index_option

Derivative Product Information (/derivatives):
  - Futures OHLC (/derivatives/futures): https://jpx.gitbook.io/j-quants-ja/api-reference/futures
  - Options OHLC (/derivatives/options): https://jpx.gitbook.io/j-quants-ja/api-reference/options

Navigation:
  - Previous: API Usage Flow (https://jpx.gitbook.io/j-quants-ja/outline/getstarted)
  - Next: API Common Considerations (https://jpx.gitbook.io/j-quants-ja/api-reference/attention)
```

--------------------------------

### Python Example for Listed Info API

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/listed_info

Shows how to fetch data from the /v1/listed/info API endpoint using Python's requests library. An idToken is needed for authentication.

```python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/listed/info", headers=headers)
r.json()
```

--------------------------------

### J-Quants API Usage Guide

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/howtoread

Information on how to interpret API requests and responses, including details on request parameters and response formats.

```APIDOC
API Request Details:
  - Refer to the 'リクエストの詳細' section for information on constructing API requests, including required parameters and their formats.

API Response Details:
  - Refer to the 'レスポンスの詳細' section for understanding the structure and content of API responses.

Response Parameter Format:
  - Refer to the 'レスポンスパラメータの形式' section for details on the data types and formats of parameters within API responses.

Sample Code:
  - Refer to the 'サンプルコード' section for practical examples of how to use the J-Quants API.
```

--------------------------------

### Fetch Financial Statement Details (Python)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/statements-1

Example of how to fetch financial statement details using Python's requests library. It shows how to set up the headers with the idToken and make a GET request to the API.

```python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/fins/fs_details?code=86970&date=20230130", headers=headers)
r.json()

```

--------------------------------

### Successful Response Example

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trading_calendar

This is an example of a successful response from the Trading Calendar API, returning a list of trading calendar entries with their respective dates and holiday divisions.

```json
{
    "trading_calendar": [
        {
            "Date": "2015-04-01", 
            "HolidayDivision": "1"
        }
    ]
}
```

--------------------------------

### Successful API Response Example

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/listed_info

Example JSON response for a successful request to the J-Quants listed info API, containing detailed information about a listed company.

```JSON
{
    "info": [
        {
            "Date": "2022-11-11",
            "Code": "86970",
            "CompanyName": "日本取引所グループ",
            "CompanyNameEnglish": "Japan Exchange Group,Inc.",
            "Sector17Code": "16",
            "Sector17CodeName": "金融（除く銀行）",
            "Sector33Code": "7200",
            "Sector33CodeName": "その他金融業",
            "ScaleCategory": "TOPIX Large70",
            "MarketCode": "0111",
            "MarketCodeName": "プライム",
            "MarginCode": "1",
            "MarginCodeName": "信用"
        }
    ]
}
```

--------------------------------

### Fetch TOPIX Data using Python

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/topix

Example of how to fetch TOPIX daily data using the Python requests library. It demonstrates setting the Authorization header.

```Python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/indices/topix", headers=headers)
r.json()
```

--------------------------------

### J-Quants API Call Sample (Dividend Data)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/dividend

Example of how to call the J-Quants API to retrieve dividend data.

```APIDOC
Example Usage:
GET https://api.jpx.co.jp/fins/dividend?code=1234&date_from=2023-01-01&date_to=2023-12-31

Response Example:
[
  {
    "code": "1234",
    "announcement_date": "2023-05-15",
    "ex_dividend_date": "2023-06-30",
    "payment_date": "2023-07-20",
    "dividend_amount": 50.00
  }
]
```

--------------------------------

### Example API Call (Curl)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trading_calendar

This example demonstrates how to call the Trading Calendar API using curl. It includes setting an authorization token and specifying a holiday division and date range for the query.

```curl
idToken=<YOUR idToken> && curl https://api.jquants.com/v1/markets/trading_calendar?holidaydivision=1&from=20220101&to=20221231 -H "Authorization: Bearer $idToken"
```

--------------------------------

### Error Response Example (Unexpected Error)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trading_calendar

This is an example of an unexpected error message returned by the API, suggesting the user try again later.

```json
{
    "message": "Unexpected error. Please try again later."
}
```

--------------------------------

### Error Response Examples

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/listed_info

Examples of JSON error responses from the J-Quants API, illustrating different error scenarios such as invalid tokens, unexpected errors, and payload size issues.

```JSON
{
    "message": "The incoming token is invalid or expired."
}
```

```JSON
{
    "message": "Unexpected error. Please try again later."
}
```

```JSON
{
    "message": "Response data is too large. Specify parameters to reduce the acquired data range."
}
```

--------------------------------

### JPX API - Example Financial Statement JSON

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/statements

Provides an example of the JSON structure returned by the JPX Statements API, detailing various financial metrics for a company.

```JSON
{
    "statements": [
        {
              "DisclosedDate": "2023-01-30",
              "DisclosedTime": "12:00:00",
              "LocalCode": "86970",
              "DisclosureNumber": "20230127594871",
              "TypeOfDocument": "3QFinancialStatements_Consolidated_IFRS",
              "TypeOfCurrentPeriod": "3Q",
              "CurrentPeriodStartDate": "2022-04-01",
              "CurrentPeriodEndDate": "2022-12-31",
              "CurrentFiscalYearStartDate": "2022-04-01",
              "CurrentFiscalYearEndDate": "2023-03-31",
              "NextFiscalYearStartDate": "",
              "NextFiscalYearEndDate": "",
              "NetSales": "100529000000",
              "OperatingProfit": "51765000000",
              "OrdinaryProfit": "",
              "Profit": "35175000000",
              "EarningsPerShare": "66.76",
              "DilutedEarningsPerShare": "",
              "TotalAssets": "79205861000000",
              "Equity": "320021000000",
              "EquityToAssetRatio": "0.004",
              "BookValuePerShare": "",
              "CashFlowsFromOperatingActivities": "",
              "CashFlowsFromInvestingActivities": "",
              "CashFlowsFromFinancingActivities": "",
              "CashAndEquivalents": "91135000000",
              "ResultDividendPerShare1stQuarter": "",
              "ResultDividendPerShare2ndQuarter": "26.0",
              "ResultDividendPerShare3rdQuarter": "",
              "ResultDividendPerShareFiscalYearEnd": "",
              "ResultDividendPerShareAnnual": "",
              "DistributionsPerUnit(REIT)": "",
              "ResultTotalDividendPaidAnnual": "",
              "ResultPayoutRatioAnnual": "",
              "ForecastDividendPerShare1stQuarter": "",
              "ForecastDividendPerShare2ndQuarter": "",
              "ForecastDividendPerShare3rdQuarter": "",
              "ForecastDividendPerShareFiscalYearEnd": "36.0",
              "ForecastDividendPerShareAnnual": "62.0",
              "ForecastDistributionsPerUnit(REIT)": "",
              "ForecastTotalDividendPaidAnnual": "",
              "ForecastPayoutRatioAnnual": "",
              "NextYearForecastDividendPerShare1stQuarter": "",
              "NextYearForecastDividendPerShare2ndQuarter": "",
              "NextYearForecastDividendPerShare3rdQuarter": "",
              "NextYearForecastDividendPerShareFiscalYearEnd": "",
              "NextYearForecastDividendPerShareAnnual": "",
              "NextYearForecastDistributionsPerUnit(REIT)": "",
              "NextYearForecastPayoutRatioAnnual": "",
              "ForecastNetSales2ndQuarter": "",
              "ForecastOperatingProfit2ndQuarter": "",
              "ForecastOrdinaryProfit2ndQuarter": "",
              "ForecastProfit2ndQuarter": "",
              "ForecastEarningsPerShare2ndQuarter": "",
              "NextYearForecastNetSales2ndQuarter": "",
              "NextYearForecastOperatingProfit2ndQuarter": "",
              "NextYearForecastOrdinaryProfit2ndQuarter": "",
              "NextYearForecastProfit2ndQuarter": "",
              "NextYearForecastEarningsPerShare2ndQuarter": "",
              "ForecastNetSales": "132500000000",
              "ForecastOperatingProfit": "65500000000",
              "ForecastOrdinaryProfit": "",
              "ForecastProfit": "45000000000",
              "ForecastEarningsPerShare": "85.42",
              "NextYearForecastNetSales": "",
              "NextYearForecastOperatingProfit": "",
              "NextYearForecastOrdinaryProfit": "",
              "NextYearForecastProfit": "",
              "NextYearForecastEarningsPerShare": "",
              "MaterialChangesInSubsidiaries": "false",
              "SignificantChangesInTheScopeOfConsolidation": "",
              "ChangesBasedOnRevisionsOfAccountingStandard": "false",
              "ChangesOtherThanOnesBasedOnRevisionsOfAccountingStandard": "false",
              "ChangesInAccountingEstimates": "true",
              "RetrospectiveRestatement": "",
              "NumberOfIssuedAndOutstandingSharesAtTheEndOfFiscalYearIncludingTreasuryStock": "528578441",
              "NumberOfTreasuryStockAtTheEndOfFiscalYear": "1861043"
        }
    ]
}
```

--------------------------------

### Example Error Response (Invalid Token)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/short_selling_positions

An example of an error response indicating an invalid or expired authentication token.

```JSON
{
    "message": "The incoming token is invalid or expired."
}
```

--------------------------------

### Curl Example for Listed Info API

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/listed_info

Demonstrates how to call the /v1/listed/info API endpoint using Curl. Requires a valid idToken for authorization.

```curl
idToken=<YOUR idToken> && curl https://api.jquants.com/v1/listed/info -H "Authorization: Bearer $idToken"
```

--------------------------------

### API Call Sample - cURL

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/futures

Example of how to call the Futures API using cURL. It demonstrates how to include the authorization token and specify the date for retrieving futures data.

```curl
idToken=<YOUR idToken> && curl https://api.jquants.com/v1/derivatives/futures?date=20230324 -H "Authorization: Bearer $idToken"
```

--------------------------------

### Fetch TOPIX Data using cURL

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/topix

Example of how to fetch TOPIX daily data using cURL. It requires setting an Authorization header with your access token.

```curl
idToken=<YOUR idToken> && curl https://api.jquants.com/v1/indices/topix -H "Authorization: Bearer $idToken"
```

--------------------------------

### J-Quants Credit Balance Inquiry

Source: https://jpx.gitbook.io/j-quants-ja/faq/plan

Explains how users can check their credit balance, which may arise from plan changes or other adjustments. It guides users on where to find this information within their account.

```APIDOC
Credit Balance Check:
  - Credit balances resulting from subscription plan changes or usage can be viewed in the 'Applied Balance' section of receipts.
  - To check available credit balance before making a plan change, users can view the plan change details within the Stripe interface.
```

--------------------------------

### API Call Sample - Breakdown Endpoint

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/breakdown

Demonstrates how to call the J-Quants API to retrieve breakdown data for a specific code and date. Includes examples for both cURL and Python.

```curl
idToken=<YOUR idToken> && curl https://api.jquants.com/v1/markets/breakdown?code=86970&date=20230324 -H "Authorization: Bearer $idToken"
```

```python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/markets/breakdown?code=86970&date=20230324", headers=headers)
r.json()
```

--------------------------------

### Index Option API Call (Python)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/index_option

Example of how to call the Index Option API using Python's requests library. Requires an idToken for authorization.

```python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/option/index_option?date=20230324", headers=headers)
r.json()
```

--------------------------------

### J-Quants API 利用目的とデータ利用に関するFAQ

Source: https://jpx.gitbook.io/j-quants-ja/faq/usage

J-Quants APIの利用目的、営利目的の定義、私的利用の範囲、ブログやインターネット記事でのデータ利用、卒論執筆での利用、サブスクリプションキャンセル後やプラン変更後のデータ利用に関する質問と回答をまとめたものです。

```ja
J-Quants APIはどのような用途で利用できますか？
> J-Quants APIは個人の方の私的利用に限定したサービスです。法人による利用や、個人の方であってもデータの第三者配信やデータを利用したアプリの提供などは、営利・非営利を問わず利用は禁止されています。これら利用につきましては別途お問合せください。

営利目的とはどのような利用を指しますか？
> 営利目的とは、J-Quants APIで配信されるデータ（以下「本データ」）の外部配信、本データを利用した情報配信または本データを利用したアプリ・サービスの第三者配信等をいいます。

私的利用とはどのような利用を指しますか？
> 私的利用とは、ご自身の投資分析のための利用やポートフォリオ管理等を指します。本データを用いて投資分析した結果を、継続反復して第三者に提供・配信する行為は私的利用に該当しません。
> また、第三者から提供されるポートフォリオ管理等サービスに本データを利用することは可能ですが、本データを第三者が閲覧できる状態である時には私的利用には該当しませんのでご注意ください。

ブログやインターネット記事にJ-Quants APIのデータを利用することはできますか？
> ご自身の分析結果や分析手法を公開いただくことは構いません。
> ただし、J-Quants APIで取得したデータそのものを閲覧できる形で配布・シェアすることは禁止されていますのでご注意ください。

卒論の執筆には利用できますか？
> 学術利用に関しては、学生の方の自身の卒業論文の執筆に限って利用することは可能ですが、授業・ゼミ等でのクラス・集団による利用、教職員の方による授業・指導を目的とする利用、および研究者としての論文執筆・学会発表等を目的とした利用は禁止されています。これら利用をご予定の方につきましては別途お問合せください。

サブスクリプションのキャンセルまたは退会後に、データを利用することは可能ですか？
> できません。J-Quants APIはデータ販売ではなく、データを利用するサービスですので、サブスクリプションのキャンセルまたは退会後にはそれまで取得したデータの削除をお願いいたします。
> サブスクリプションのキャンセルまたは退会した場合であっても、それまで取得したデータの扱いは利用規約に準じます。サブスクリプションのキャンセルまたは退会後に本データを利用することは禁止されます。

プラン変更後、変更前のプランのデータを利用することは可能ですか？
> J-Quants APIはデータ販売ではなく、データを利用するサービスですので、プラン変更後にはそれまで上位プランで取得したデータ利用はできません。データの削除をお願いいたします。
```

--------------------------------

### J-Quants API認証フロー

Source: https://jpx.gitbook.io/j-quants-ja/outline/getstarted

J-Quants APIを利用するための認証フローを説明します。これには、リフレッシュトークンの取得と、それを用いたIDトークンの取得が含まれます。リフレッシュトークンは1週間、IDトークンは24時間で失効します。

```APIDOC
API利用までの流れ:

1. **ユーザ登録とサブスクリプションプラン登録**
   - ランディングページ ([https://jpx-jquants.com/](https://jpx-jquants.com/)) からユーザ登録とサブスクリプションプランの登録を行います（初回のみ）。

2. **リフレッシュトークン取得**
   - API利用の都度、リフレッシュトークンを取得します。
   - **方法1:** メニューページ ([https://jpx-jquants.com/dashboard/menu/](https://jpx-jquants.com/dashboard/menu/)) にログインし、リフレッシュトークンをコピーします。
   - **方法2:** APIを利用して取得します。
     - **有償版:** `https://api.jquants.com/v1/token/auth_user`
     - **Beta版:** `https://api.jpx-jquants.com/v1/token/auth_user`
   - リフレッシュトークンは1週間で失効します。

3. **IDトークン取得**
   - 取得したリフレッシュトークンを用いて、IDトークンを取得します。
   - **API:** `/token/auth_refresh` ([https://jpx.gitbook.io/j-quants-ja/api-reference/idtoken](https://jpx.gitbook.io/j-quants-ja/api-reference/idtoken))
   - IDトークンは24時間で失効します。

4. **API利用**
   - 取得したIDトークンを用いて、各APIをご利用ください。
   - 詳細なAPI仕様は [API仕様](https://jpx.gitbook.io/j-quants-ja/api-reference) を参照してください。
```

--------------------------------

### J-Quants API Common Considerations

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/attention

General guidelines and considerations for using the J-Quants API, including rate limits, pagination, and Gzip compression.

```APIDOC
Rate Limits:
  - Information on API request rate limits is available at [https://jpx.gitbook.io/j-quants-ja/api-reference/attention#rtorimittonitsuite].

Response Paging:
  - Details on how to handle paginated API responses can be found at [https://jpx.gitbook.io/j-quants-ja/api-reference/attention#resuponsunopjingunitsuite].

Gzip Compression:
  - Information regarding the Gzip compression of API responses is available at [https://jpx.gitbook.io/j-quants-ja/api-reference/attention#gzip].
```

--------------------------------

### JPX J-Quants API - Fetch Trades Spec (Python)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trades_spec

Example of how to fetch trades specification data from the JPX J-Quants API using Python's requests library. It shows how to set up headers with an authorization token and make a GET request to the API endpoint.

```python
import requests
import json
idToken = "YOUR idToken"
headers = {'Authorization': 'Bearer {}'.format(idToken)}
r = requests.get("https://api.jquants.com/v1/markets/trades_spec?section=TSEPrime&from=20230324&to=20230403", headers=headers)
r.json()
```

--------------------------------

### J-Quants API Call Sample Code

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/futures

Illustrates how to make API calls to J-Quants, demonstrating the structure of requests and responses for accessing financial data.

```APIDOC
# Example: Fetching daily stock quotes for a specific security
import requests

base_url = "https://api.jpx.co.jp/v1"
endpoint = "/prices/daily_quotes"
security_code = "8601"
date = "2023-10-27"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

params = {
    "security_code": security_code,
    "date": date
}

response = requests.get(f"{base_url}{endpoint}", headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code}")
    print(response.text)
```

--------------------------------

### J-Quants API Response Pagination Example

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/attention

Demonstrates how to retrieve all data from the J-Quants API when responses are paginated. It shows a loop that continues to fetch data using the `pagination_key` until all records are retrieved. This is crucial for handling large datasets efficiently.

```python
import requests
import json
# 通常の検索
idToken ="YOUR idToken"
headers ={"Authorization":"Bearer {}".format(idToken)}
r_get = requests.get("https://api.jquants.com/v1/method?query=param", headers=headers)
data = r_get.json()["data"]
# 大容量データが返却された場合の再検索
# データ量により複数ページ取得できる場合があるため、pagination_keyが含まれる限り、再検索を実施
while"pagination_key"in r_get.json():
    pagination_key = r_get.json()["pagination_key"]
    r_get = requests.get(f"https://api.jquants.com/v1/method?query=param&pagination_key={pagination_key}", headers=headers)
    data += r_get.json()["data"]
```

--------------------------------

### Error Response Example (Invalid Token)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trading_calendar

This example shows the API's response when an invalid or expired authentication token is provided.

```json
{
    "message": "The incoming token is invalid or expired."
}
```

--------------------------------

### Example Error Response (Payload Too Large)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/short_selling_positions

An example of an error response when the requested data exceeds the payload size limit, suggesting parameter adjustments.

```JSON
{
    "message": "Response data is too large. Specify parameters to reduce the acquired data range."
}
```

--------------------------------

### J-Quants Subscription Plans

Source: https://jpx.gitbook.io/j-quants-ja/faq/plan

Details the available subscription plans: Free, Light, Standard, and Premium. It also mentions the requirement for credit card registration for paid plans and the immediate application of plan changes.

```APIDOC
Subscription Plans:
  - Free Plan: Data is delayed by 12 weeks.
  - Light Plan: Paid plan, requires credit card registration.
  - Standard Plan: Paid plan, requires credit card registration.
  - Premium Plan: Paid plan, requires credit card registration.

Plan Change Policy:
  - Changes can be made at any time and are applied immediately.
  - Only one plan change is allowed per month.
  - Changes to lower-tier paid plans or to the free plan within a billing cycle result in credit balance issuance for the remaining period.
  - Credit balances are automatically applied to future paid plan payments.
  - Plan changes can be managed via a link to the 'My Page' after logging into the J-Quants API.

Free Plan Expiration:
  - The Free Plan is valid for one year and automatically cancels afterward.
  - Users can re-register for the Free Plan after it expires.
```

--------------------------------

### JPX J-Quants Trades Data Example

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trades_spec

An example JSON response containing trades data for a specific period. It includes various financial metrics broken down by participant type.

```JSON
{
    "trades_spec": [
        {
            "PublishedDate":"2017-01-13",
            "StartDate":"2017-01-04",
            "EndDate":"2017-01-06",
            "Section":"TSE1st",
            "ProprietarySales":1311271004,
            "ProprietaryPurchases":1453326508,
            "ProprietaryTotal":2764597512,
            "ProprietaryBalance":142055504,
            "BrokerageSales":7165529005,
            "BrokeragePurchases":7030019854,
            "BrokerageTotal":14195548859,
            "BrokerageBalance":-135509151,
            "TotalSales":8476800009,
            "TotalPurchases":8483346362,
            "TotalTotal":16960146371,
            "TotalBalance":6546353,
            "IndividualsSales":1401711615,
            "IndividualsPurchases":1161801155,
            "IndividualsTotal":2563512770,
            "IndividualsBalance":-239910460,
            "ForeignersSales":5094891735,
            "ForeignersPurchases":5317151774,
            "ForeignersTotal":10412043509,
            "ForeignersBalance":222260039,
            "SecuritiesCosSales":76381455,
            "SecuritiesCosPurchases":61700100,
            "SecuritiesCosTotal":138081555,
            "SecuritiesCosBalance":-14681355,
            "InvestmentTrustsSales":168705109,
            "InvestmentTrustsPurchases":124389642,
            "InvestmentTrustsTotal":293094751,
            "InvestmentTrustsBalance":-44315467,
            "BusinessCosSales":71217959,
            "BusinessCosPurchases":63526641,
            "BusinessCosTotal":134744600,
            "BusinessCosBalance":-7691318,
            "OtherCosSales":10745152,
            "OtherCosPurchases":15687836,
            "OtherCosTotal":26432988,
            "OtherCosBalance":4942684,
            "InsuranceCosSales":15926202,
            "InsuranceCosPurchases":9831555,
            "InsuranceCosTotal":25757757,
            "InsuranceCosBalance":-6094647,
            "CityBKsRegionalBKsEtcSales":10606789,
            "CityBKsRegionalBKsEtcPurchases":8843871,
            "CityBKsRegionalBKsEtcTotal":19450660,
            "CityBKsRegionalBKsEtcBalance":-1762918,
            "TrustBanksSales":292932297,
            "TrustBanksPurchases":245322795,
            "TrustBanksTotal":538255092,
            "TrustBanksBalance":-47609502,
            "OtherFinancialInstitutionsSales":22410692,
            "OtherFinancialInstitutionsPurchases":21764485,
            "OtherFinancialInstitutionsTotal":44175177,
            "OtherFinancialInstitutionsBalance":-646207
        }
    ],
    "pagination_key": "value1.value2."
}
```

--------------------------------

### J-Quants API General Notes and Usage

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/statements

Provides general guidelines and important considerations for using the J-Quants API, including how to interpret the API documentation and common parameters.

```APIDOC
API Common Notes:
  - Details on API usage and important considerations.

How to Read API Specifications:
  - Explanation of the structure and elements within the API documentation.

Parameters and Responses:
  - General information about request parameters and the structure of API responses.

Quarterly Financial Information:
  - Specifics on retrieving quarterly financial data.

Data Item Overview:
  - Description of the available data fields and their meanings.

API Call Sample Code:
  - Examples of how to make API calls.
```

--------------------------------

### Index Option API Call (Curl)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/index_option

Example of how to call the Index Option API using Curl. Requires an idToken for authorization.

```curl
idToken=<YOUR idToken> && curl https://api.jquants.com/v1/option/index_option?date=20230324 -H "Authorization: Bearer $idToken"
```

--------------------------------

### Example Success Response

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/short_selling_positions

A sample JSON response for a successful API call to retrieve short selling positions. It includes details for a specific stock, such as disclosure and calculation dates, short seller information, and position ratios.

```JSON
{
    "short_selling_positions": [
      {
        "DisclosedDate": "2024-08-01",
        "CalculatedDate": "2024-07-31",
        "Code": "13660",
        "ShortSellerName": "個人",
        "ShortSellerAddress": "",
        "DiscretionaryInvestmentContractorName": "",
        "DiscretionaryInvestmentContractorAddress": "",
        "InvestmentFundName": "",
        "ShortPositionsToSharesOutstandingRatio": 0.0053,
        "ShortPositionsInSharesNumber": 140000,
        "ShortPositionsInTradingUnitsNumber": 140000,
        "CalculationInPreviousReportingDate": "2024-07-22",
        "ShortPositionsInPreviousReportingRatio": 0.0043,
        "Notes": ""
      }
    ],
    "pagination_key": "value1.value2."
}
```

--------------------------------

### Error Response Example (Generic)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trading_calendar

This JSON structure represents a generic error message returned by the API when an issue occurs during the request processing.

```json
{
    "message": <Error Message>
}
```

--------------------------------

### Example Error Response (Generic)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/short_selling_positions

A generic JSON structure for error responses from the API, typically containing a 'message' field to describe the error.

```JSON
{
    "message": <Error Message>
}
```

--------------------------------

### Error Response Example (Payload Too Large)

Source: https://jpx.gitbook.io/j-quants-ja/api-reference/trading_calendar

This error message indicates that the response data is too large, advising the user to specify parameters to reduce the data range.

```json
{
    "message": "Response data is too large. Specify parameters to reduce the acquired data range."
}
```
Tokens:
Raw