Skip to content

Latest commit

 

History

History
248 lines (187 loc) · 9.37 KB

README.md

File metadata and controls

248 lines (187 loc) · 9.37 KB
Raw

J-Quants API Client

Build Status Crates.io License: MIT

Table of Contents

Overview

The J-Quants API Client is a Rust implementation designed to provide seamless access to various J-Quants API endpoints. It facilitates efficient data retrieval and manipulation through asynchronous processing, ensuring fast and reliable communication.

What is J-Quants?

J-Quants is a financial data platform provided by JPX Market Innovation & Research, Inc. (JPXI).

It offers access to a wide range of financial data through its API, enabling developers, analysts, and investors to integrate and analyze financial information effectively.

To use the J-Quants API, you must register for an account. A Free plan is available, allowing users to access the API without any cost. You can register for an account below.

For an in-depth understanding of the data provided, service usage, and API specifications, please refer to the following resources:

Features

  • Asynchronous Processing: Ensures fast and efficient data communication.
  • Comprehensive API Support: Access to authentication, data retrieval, and more.
  • Pagination Handling: Easily manage paginated data responses.
  • Error Handling: Robust error management for reliable operations.
  • Plan-Specific, Type-Safe Clients: Provides clients tailored to each subscription plan, allowing for type-safe usage specific to individual plans.
  • Automatic ID Token Refresh: Automatically handles the renewal of ID tokens, ensuring uninterrupted API access without manual intervention.
  • Secure Authentication Management: Does not store email addresses and passwords in memory; they are immediately discarded after use to ensure security.

Prerequisites

  • Rust: Ensure you have Rust installed.
  • Tokio: Asynchronous runtime used by the client.

Installation

Ensure Rust is installed on your system. Then, add the jquants-api-client to your Cargo.toml:

[dependencies]
jquants-api-client = "0.1.0"

Supported APIs

The J-Quants API Client currently supports the following APIs:

Authentication

API Endpoint Description Status
/token/auth_user Refresh Token Implemented
/token/auth_refresh ID Token Implemented

Data Retrieval

API Endpoint Description Status
/listed/info Listed Issue Information Implemented
/prices/daily_quotes Stock Prices (OHLC) Implemented
/fins/statements Financial Data Implemented
/fins/announcement Earnings Calendar Implemented
/markets/trading_calendar Trading Calendar Implemented
/markets/trades_spec Trading by Type of Investors Implemented
/indices/topix TOPIX Prices (OHLC) Implemented
/indices Indices (OHLC) Implemented
/option/index_option Index Option Prices (OHLC) Implemented
/derivatives/futures Futures (OHLC) Implemented
/derivatives/options Options (OHLC) Implemented
/markets/weekly_margin_interest Margin Trading Outstandings Implemented
/markets/short_selling Short Sale Value and Ratio by Sector Implemented
/markets/breakdown Breakdown Trading Data Implemented
/prices/prices_am Morning Session Stock Prices (OHLC) Implemented
/fins/dividend Cash Dividend Data Implemented
/fins/fs_details Financial Statement Data (BS/PL) Implemented

Client Usage Example

Below are examples of how to use the J-Quants API client.

Standard Fetch

This example demonstrates a basic fetch operation to retrieve listed issue information.

use jquants_api_client::{
    JQuantsFreePlanClient, ListedIssueInfoApi,
};
use tokio;

#[tokio::main]
async fn main() {
    // Replace with your actual refresh token.
    // Ensure you keep your refresh token secure and do not expose it in public repositories.
    let refresh_token = "YOUR_REFRESH_TOKEN";

    // Initialize the client with the refresh token
    let client = JQuantsFreePlanClient::new_from_refresh_token(refresh_token);

    // Make the API call to get listed issue information for code "2789"
    match client.get_listed_issue_info().code("2789").send().await {
        Ok(info) => println!("Listed Information: {:?}", info),
        Err(e) => eprintln!("Error: {:?}", e),
    }
}

Pagination

This example demonstrates how to handle paginated responses when retrieving daily stock prices.

use futures::stream::StreamExt;
use jquants_api_client::{
    JQuantsFreePlanClient, DailyStockPricesApi, Paginatable,
};
use tokio;

#[tokio::main]
async fn main() {
    // Replace with your actual refresh token.
    // Ensure you keep your refresh token secure and do not expose it in public repositories.
    let refresh_token = "YOUR_REFRESH_TOKEN";

    // Initialize the client with the refresh token
    let client = JQuantsFreePlanClient::new_from_refresh_token(refresh_token);

    // Create a stream to fetch paginated daily stock prices
    let mut stream = client
        .get_daily_stock_prices()
        .code("27890")
        .date("2024-08-01")
        .fetch_pages_stream();

    // Iterate through each page in the stream
    while let Some(response) = stream.next().await {
        match response {
            Ok(daily_stock_prices_response) => {
                println!("{daily_stock_prices_response:?}");
            }
            Err(e) => {
                eprintln!("Error: {e}");
            }
        }
    }
}

Additional Examples

For more detailed examples, please refer to the examples directory in the repository.

Note: For security reasons, never commit or expose your refresh tokens or any other sensitive information in your code repositories.

Testing

Run unit tests using the following command:

cargo test

To run specific tests or see detailed output, you can use:

cargo test -- --nocapture

Contributing

Contributions are welcome! To ensure a smooth process, please follow these guidelines:

  1. Fork the Repository: Click the "Fork" button at the top of this page to create your own fork.
  2. Clone Your Fork: 
    git clone https://github.com/your-username/jquants-api-client-rust.git
cd jquants-api-client-rust
  3. Create a Branch: 
    git checkout -b feature/your-feature-name
  4. Make Your Changes: Implement your feature or fix.
  5. Run Tests: Ensure all tests pass. 
    cargo test
  6. Commit Your Changes: 
    git commit -m "Add feature: your feature description"
  7. Push to Your Fork: 
    git push origin feature/your-feature-name
  8. Create a Pull Request: Go to the original repository and create a pull request from your fork.

Note: Never commit or expose your refresh tokens or any other sensitive information in your code repositories.

Reporting Issues

If you encounter any bugs or have feature suggestions, please open an issue on the Issues page.

Documents

Comprehensive documentation is available here.

For API reference, visit the API Specifications (English), API Specifications (Japanese).

Feedback

We value your feedback! If you have any suggestions or encounter issues, please open an issue or reach out directly.

License

This project is licensed under the MIT License.