use crate::error::Error;
use crate::limiter::{Plan, RateLimiter};
use crate::models::{
AmBar, ApiErrorResponse, ApiResponse, Breakdown, BulkGetResponse, BulkListItem, Calendar,
CrossShareholdingsDoc, CursorPage, DailyBar, EarningsCalendar, EarningsDate, FinsDetails,
FinsDividend, FinsSummary, FuturesBar, IndexDailyBar, InvestorType, LargeVolumeShareholdersDoc,
MajorShareholdersDoc, MarginAlert, MarginInterest, MinuteBar, Options225Bar, OptionsBar,
ShortRatio, ShortSaleReport, StockMaster, TdBulk, TdFiles, TdList, TopixDailyBar, Valuation,
};
use crate::query::{
BulkGetQuery, BulkListQuery, CalendarQuery, CodeDateQuery, EarningsDateQuery, EdinetQuery,
FinsQuery, FuturesBarsQuery, InvestorTypesQuery, MarginInterestQuery, MasterQuery,
OptionsBarsQuery, RangeQuery, ShortRatioQuery, ShortSaleReportQuery, TdListQuery,
};
use serde::de::DeserializeOwned;
use std::sync::Arc;
pub const DEFAULT_BASE_URL: &str = "https://api.jquants.com/v2";
const HEADER_API_KEY: &str = "x-api-key";
#[derive(Debug, Clone)]
pub struct JQuantsClient {
http: reqwest::Client,
api_key: String,
base_url: String,
limiter: Option<Arc<RateLimiter>>,
}
impl JQuantsClient {
pub fn new(api_key: impl Into<String>) -> Self {
Self {
http: reqwest::Client::new(),
api_key: api_key.into(),
base_url: DEFAULT_BASE_URL.to_string(),
limiter: None,
}
}
pub fn from_env() -> Result<Self, Error> {
let api_key = std::env::var("JQUANTS_API_KEY").map_err(|_| Error::MissingApiKey)?;
Ok(Self::new(api_key))
}
pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
self.base_url = base_url.into();
self
}
pub fn with_http_client(mut self, http: reqwest::Client) -> Self {
self.http = http;
self
}
pub fn with_plan(self, plan: Plan) -> Self {
self.with_rate_limit(plan.requests_per_minute())
}
pub fn with_rate_limit(mut self, requests_per_minute: u32) -> Self {
self.limiter = if requests_per_minute == 0 {
None
} else {
Some(Arc::new(RateLimiter::per_minute(requests_per_minute)))
};
self
}
async fn throttle(&self) {
if let Some(limiter) = &self.limiter {
limiter.acquire().await;
}
}
async fn api_error(response: reqwest::Response, status: u16) -> Error {
let message = match response.json::<ApiErrorResponse>().await {
Ok(body) => body.message,
Err(_) => format!("HTTP {status}"),
};
Error::Api { status, message }
}
fn decode<T: DeserializeOwned>(text: &str) -> Result<T, Error> {
serde_json::from_str(text).map_err(|e| Error::Decode {
source: e,
body: text.chars().take(500).collect(),
})
}
async fn get_paginated<T: DeserializeOwned>(
&self,
path: &str,
params: &[(&str, &str)],
) -> Result<CursorPage<T>, Error> {
let url = format!("{}{}", self.base_url, path);
let mut items: Vec<T> = Vec::new();
let mut pagination_key: Option<String> = None;
let mut cursor: Option<String> = None;
loop {
self.throttle().await;
let mut request = self
.http
.get(&url)
.header(HEADER_API_KEY, &self.api_key)
.query(params);
if let Some(ref pk) = pagination_key {
request = request.query(&[("pagination_key", pk.as_str())]);
}
let response = request.send().await?;
let status = response.status().as_u16();
match status {
200 => {
let text = response.text().await?;
let body: ApiResponse<T> = Self::decode(&text)?;
items.extend(body.data);
if body.cursor.is_some() {
cursor = body.cursor;
}
match body.pagination_key {
Some(key) => pagination_key = Some(key),
None => break,
}
}
210 => break,
_ => return Err(Self::api_error(response, status).await),
}
}
Ok(CursorPage { items, cursor })
}
async fn get_all<T: DeserializeOwned>(
&self,
path: &str,
params: &[(&str, &str)],
) -> Result<Vec<T>, Error> {
Ok(self.get_paginated(path, params).await?.items)
}
async fn get_object<T: DeserializeOwned>(
&self,
path: &str,
params: &[(&str, &str)],
) -> Result<T, Error> {
let url = format!("{}{}", self.base_url, path);
self.throttle().await;
let response = self
.http
.get(&url)
.header(HEADER_API_KEY, &self.api_key)
.query(params)
.send()
.await?;
let status = response.status().as_u16();
if status == 200 {
let text = response.text().await?;
Self::decode(&text)
} else {
Err(Self::api_error(response, status).await)
}
}
pub async fn master(&self, query: &MasterQuery) -> Result<Vec<StockMaster>, Error> {
self.get_all("/equities/master", &query.params()).await
}
pub async fn daily_bars(&self, query: &CodeDateQuery) -> Result<Vec<DailyBar>, Error> {
self.get_all("/equities/bars/daily", &query.params()).await
}
pub async fn am_bars(&self, code: Option<&str>) -> Result<Vec<AmBar>, Error> {
let params: Vec<(&str, &str)> = code.map(|c| ("code", c)).into_iter().collect();
self.get_all("/equities/bars/daily/am", ¶ms).await
}
pub async fn minute_bars(&self, query: &CodeDateQuery) -> Result<Vec<MinuteBar>, Error> {
self.get_all("/equities/bars/minute", &query.params()).await
}
pub async fn valuation(&self, query: &CodeDateQuery) -> Result<Vec<Valuation>, Error> {
self.get_all("/equities/valuation", &query.params()).await
}
pub async fn earnings_calendar(&self) -> Result<Vec<EarningsCalendar>, Error> {
self.get_all("/equities/earnings-calendar", &[]).await
}
pub async fn investor_types(
&self,
query: &InvestorTypesQuery,
) -> Result<Vec<InvestorType>, Error> {
self.get_all("/equities/investor-types", &query.params())
.await
}
pub async fn breakdown(&self, query: &CodeDateQuery) -> Result<Vec<Breakdown>, Error> {
self.get_all("/markets/breakdown", &query.params()).await
}
pub async fn trading_calendar(&self, query: &CalendarQuery) -> Result<Vec<Calendar>, Error> {
self.get_all("/markets/calendar", &query.params()).await
}
pub async fn margin_alert(&self, query: &CodeDateQuery) -> Result<Vec<MarginAlert>, Error> {
self.get_all("/markets/margin-alert", &query.params()).await
}
pub async fn margin_interest(
&self,
query: &MarginInterestQuery,
) -> Result<Vec<MarginInterest>, Error> {
self.get_all("/markets/margin-interest", &query.params())
.await
}
pub async fn short_ratio(&self, query: &ShortRatioQuery) -> Result<Vec<ShortRatio>, Error> {
self.get_all("/markets/short-ratio", &query.params()).await
}
pub async fn short_sale_report(
&self,
query: &ShortSaleReportQuery,
) -> Result<Vec<ShortSaleReport>, Error> {
self.get_all("/markets/short-sale-report", &query.params())
.await
}
pub async fn index_daily_bars(
&self,
query: &CodeDateQuery,
) -> Result<Vec<IndexDailyBar>, Error> {
self.get_all("/indices/bars/daily", &query.params()).await
}
pub async fn topix_daily_bars(&self, query: &RangeQuery) -> Result<Vec<TopixDailyBar>, Error> {
self.get_all("/indices/bars/daily/topix", &query.params())
.await
}
pub async fn futures_bars(&self, query: &FuturesBarsQuery) -> Result<Vec<FuturesBar>, Error> {
self.get_all("/derivatives/bars/daily/futures", &query.params())
.await
}
pub async fn options_bars(&self, query: &OptionsBarsQuery) -> Result<Vec<OptionsBar>, Error> {
self.get_all("/derivatives/bars/daily/options", &query.params())
.await
}
pub async fn options_225_bars(&self, date: Option<&str>) -> Result<Vec<Options225Bar>, Error> {
let params: Vec<(&str, &str)> = date.map(|d| ("date", d)).into_iter().collect();
self.get_all("/derivatives/bars/daily/options/225", ¶ms)
.await
}
pub async fn fins_summary(&self, query: &FinsQuery) -> Result<CursorPage<FinsSummary>, Error> {
self.get_paginated("/fins/summary", &query.params()).await
}
pub async fn fins_details(&self, query: &FinsQuery) -> Result<CursorPage<FinsDetails>, Error> {
self.get_paginated("/fins/details", &query.params()).await
}
pub async fn fins_dividend(&self, query: &CodeDateQuery) -> Result<Vec<FinsDividend>, Error> {
self.get_all("/fins/dividend", &query.params()).await
}
pub async fn fins_earnings_date(
&self,
query: &EarningsDateQuery,
) -> Result<Vec<EarningsDate>, Error> {
self.get_all("/fins/earnings-date", &query.params()).await
}
pub async fn edinet_major_shareholders(
&self,
query: &EdinetQuery,
) -> Result<Vec<MajorShareholdersDoc>, Error> {
self.get_all("/edinet/major-shareholders", &query.params())
.await
}
pub async fn edinet_cross_shareholdings(
&self,
query: &EdinetQuery,
) -> Result<Vec<CrossShareholdingsDoc>, Error> {
self.get_all("/edinet/cross-shareholdings", &query.params())
.await
}
pub async fn edinet_large_volume_shareholders(
&self,
query: &EdinetQuery,
) -> Result<Vec<LargeVolumeShareholdersDoc>, Error> {
self.get_all("/edinet/large-volume-shareholders", &query.params())
.await
}
pub async fn td_list(&self, query: &TdListQuery) -> Result<CursorPage<TdList>, Error> {
self.get_paginated("/td/list", &query.params()).await
}
pub async fn td_bulk(&self) -> Result<TdBulk, Error> {
self.get_object("/td/bulk", &[]).await
}
pub async fn td_files(&self, disc_no: &str, docs: Option<&str>) -> Result<TdFiles, Error> {
let mut params = vec![("discNo", disc_no)];
if let Some(d) = docs {
params.push(("docs", d));
}
self.get_object("/td/files", ¶ms).await
}
pub async fn bulk_list(&self, query: &BulkListQuery) -> Result<Vec<BulkListItem>, Error> {
let (endpoint, mut params) = query.params();
if let Some(ref e) = endpoint {
params.push(("endpoint", e.as_str()));
}
self.get_all("/bulk/list", ¶ms).await
}
pub async fn bulk_get(&self, query: &BulkGetQuery) -> Result<String, Error> {
let (endpoint, mut params) = query.params();
if let Some(ref e) = endpoint {
params.push(("endpoint", e.as_str()));
}
let body: BulkGetResponse = self.get_object("/bulk/get", ¶ms).await?;
Ok(body.url)
}
}