jquants-api 0.3.0

Unofficial async Rust client for the J-Quants API v2 (Japanese stock market data by JPX)
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
//! 各エンドポイントの検索条件。すべて `Default` を実装しているので
//! 必要な条件だけ指定して `..Default::default()` で埋められる。
//! 日付は API の仕様どおり `YYYY-MM-DD` または `YYYYMMDD` 形式の文字列で渡す。

type Params<'a> = Vec<(&'static str, &'a str)>;

fn push<'a>(params: &mut Params<'a>, key: &'static str, value: &'a Option<String>) {
    if let Some(v) = value {
        params.push((key, v.as_str()));
    }
}

/// 銘柄コード・日付・期間の共通条件
/// (日足・分足・バリュエーション指標・売買内訳・日々公表信用取引残高・配当・指数日足で使用)
#[derive(Debug, Clone, Default)]
pub struct CodeDateQuery {
    /// 銘柄コード(例: "7203")
    pub code: Option<String>,
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
    pub from: Option<String>,
    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
    pub to: Option<String>,
}

impl CodeDateQuery {
    /// 銘柄コードのみ指定するショートカット
    pub fn code(code: impl Into<String>) -> Self {
        Self {
            code: Some(code.into()),
            ..Self::default()
        }
    }

    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "code", &self.code);
        push(&mut p, "date", &self.date);
        push(&mut p, "from", &self.from);
        push(&mut p, "to", &self.to);
        p
    }
}

/// 上場銘柄マスタ(`/equities/master`)の条件
#[derive(Debug, Clone, Default)]
pub struct MasterQuery {
    /// 銘柄コード(例: "7203")
    pub code: Option<String>,
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
}

impl MasterQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "code", &self.code);
        push(&mut p, "date", &self.date);
        p
    }
}

/// 投資部門別売買状況(`/equities/investor-types`)の条件
#[derive(Debug, Clone, Default)]
pub struct InvestorTypesQuery {
    /// 市場区分(例: TSEPrime)
    pub section: Option<String>,
    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
    pub from: Option<String>,
    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
    pub to: Option<String>,
}

impl InvestorTypesQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "section", &self.section);
        push(&mut p, "from", &self.from);
        push(&mut p, "to", &self.to);
        p
    }
}

/// 営業日カレンダー(`/markets/calendar`)の条件
#[derive(Debug, Clone, Default)]
pub struct CalendarQuery {
    /// 休日区分(API パラメータ `holidayDivision`)
    pub holiday_division: Option<String>,
    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
    pub from: Option<String>,
    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
    pub to: Option<String>,
}

impl CalendarQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "holidayDivision", &self.holiday_division);
        push(&mut p, "from", &self.from);
        push(&mut p, "to", &self.to);
        p
    }
}

/// 信用取引残高(`/markets/margin-interest`)の条件。
/// API の仕様上 `code` / `date` / `published_date` のいずれかの指定が必須。
/// `published_date` は `date` / `from` / `to` と同時指定できない(API 側でエラーになる)
#[derive(Debug, Clone, Default)]
pub struct MarginInterestQuery {
    /// 銘柄コード(例: "7203")
    pub code: Option<String>,
    /// 申込日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
    pub from: Option<String>,
    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
    pub to: Option<String>,
    /// 公表日 (YYYY-MM-DD または YYYYMMDD)。2026-09-25 申込分以降の行だけが対象
    pub published_date: Option<String>,
}

impl MarginInterestQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "code", &self.code);
        push(&mut p, "date", &self.date);
        push(&mut p, "from", &self.from);
        push(&mut p, "to", &self.to);
        push(&mut p, "published_date", &self.published_date);
        p
    }
}

/// 業種別空売り比率(`/markets/short-ratio`)の条件
#[derive(Debug, Clone, Default)]
pub struct ShortRatioQuery {
    /// 33 業種コード
    pub s33: Option<String>,
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
    pub from: Option<String>,
    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
    pub to: Option<String>,
}

impl ShortRatioQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "s33", &self.s33);
        push(&mut p, "date", &self.date);
        push(&mut p, "from", &self.from);
        push(&mut p, "to", &self.to);
        p
    }
}

/// 空売り残高報告(`/markets/short-sale-report`)の条件
#[derive(Debug, Clone, Default)]
pub struct ShortSaleReportQuery {
    /// 銘柄コード(例: "7203")
    pub code: Option<String>,
    /// 公表日 (YYYY-MM-DD または YYYYMMDD)
    pub disc_date: Option<String>,
    /// 公表日の開始日
    pub disc_date_from: Option<String>,
    /// 公表日の終了日
    pub disc_date_to: Option<String>,
    /// 計算日 (YYYY-MM-DD または YYYYMMDD)
    pub calc_date: Option<String>,
}

impl ShortSaleReportQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "code", &self.code);
        push(&mut p, "disc_date", &self.disc_date);
        push(&mut p, "disc_date_from", &self.disc_date_from);
        push(&mut p, "disc_date_to", &self.disc_date_to);
        push(&mut p, "calc_date", &self.calc_date);
        p
    }
}

/// 期間のみの条件(`/indices/bars/daily/topix`)
#[derive(Debug, Clone, Default)]
pub struct RangeQuery {
    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
    pub from: Option<String>,
    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
    pub to: Option<String>,
}

impl RangeQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "from", &self.from);
        push(&mut p, "to", &self.to);
        p
    }
}

/// 先物四本値(`/derivatives/bars/daily/futures`)の条件
#[derive(Debug, Clone, Default)]
pub struct FuturesBarsQuery {
    /// 商品区分(例: TOPIXF/NK225F)
    pub category: Option<String>,
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 中心限月フラグ(API パラメータ `contractFlag`)
    pub contract_flag: Option<String>,
}

impl FuturesBarsQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "category", &self.category);
        push(&mut p, "date", &self.date);
        push(&mut p, "contractFlag", &self.contract_flag);
        p
    }
}

/// オプション四本値(`/derivatives/bars/daily/options`)の条件
#[derive(Debug, Clone, Default)]
pub struct OptionsBarsQuery {
    /// 商品区分(例: TOPIXF/NK225F)
    pub category: Option<String>,
    /// 銘柄コード(例: "7203")
    pub code: Option<String>,
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 中心限月フラグ(API パラメータ `contractFlag`)
    pub contract_flag: Option<String>,
}

impl OptionsBarsQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "category", &self.category);
        push(&mut p, "code", &self.code);
        push(&mut p, "date", &self.date);
        push(&mut p, "contractFlag", &self.contract_flag);
        p
    }
}

/// 財務系 cursor エンドポイント(`/fins/summary` `/fins/details`)の条件
#[derive(Debug, Clone, Default)]
pub struct FinsQuery {
    /// 銘柄コード(例: "7203")
    pub code: Option<String>,
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 前回応答の `cursor` を渡すと差分取得になる
    pub cursor: Option<String>,
}

impl FinsQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "code", &self.code);
        push(&mut p, "date", &self.date);
        push(&mut p, "cursor", &self.cursor);
        p
    }
}

/// 決算発表予定日(`/fins/earnings-date`)の条件。
/// API の仕様上 `code` / `date` / `scheduled_date` のいずれか 1 つの指定が必須
#[derive(Debug, Clone, Default)]
pub struct EarningsDateQuery {
    /// 銘柄コード(5桁、例: "86970")
    pub code: Option<String>,
    /// 公表日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 決算発表予定日 (YYYY-MM-DD または YYYYMMDD)
    pub scheduled_date: Option<String>,
}

impl EarningsDateQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "code", &self.code);
        push(&mut p, "date", &self.date);
        push(&mut p, "scheduled_date", &self.scheduled_date);
        p
    }
}

/// EDINET 系エンドポイント(`/edinet/*`)共通の条件。
/// `edinet_code` と `code` は同時指定できない(API 側でエラーになる)
#[derive(Debug, Clone, Default)]
pub struct EdinetQuery {
    /// 提出者・発行者の EDINET コード(例: "E03814")
    pub edinet_code: Option<String>,
    /// 銘柄コード(例: "86970")
    pub code: Option<String>,
    /// 提出日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
}

impl EdinetQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "edinet_code", &self.edinet_code);
        push(&mut p, "code", &self.code);
        push(&mut p, "date", &self.date);
        p
    }
}

/// 適時開示一覧(`/td/list`)の条件
#[derive(Debug, Clone, Default)]
pub struct TdListQuery {
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 銘柄コード(例: "7203")
    pub code: Option<String>,
    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
    pub from: Option<String>,
    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
    pub to: Option<String>,
    /// 開示項目コード(API パラメータ `discItems`)
    pub disc_items: Option<String>,
    /// 前回応答の `cursor` を渡すと差分取得になる
    pub cursor: Option<String>,
}

impl TdListQuery {
    pub(crate) fn params(&self) -> Params<'_> {
        let mut p = Vec::new();
        push(&mut p, "date", &self.date);
        push(&mut p, "code", &self.code);
        push(&mut p, "from", &self.from);
        push(&mut p, "to", &self.to);
        push(&mut p, "discItems", &self.disc_items);
        push(&mut p, "cursor", &self.cursor);
        p
    }
}

/// 一括ダウンロード一覧(`/bulk/list`)の条件
#[derive(Debug, Clone, Default)]
pub struct BulkListQuery {
    /// 対象エンドポイントのパス(例: `/equities/bars/daily`。先頭の `/` は省略可)
    pub endpoint: Option<String>,
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
    pub from: Option<String>,
    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
    pub to: Option<String>,
}

impl BulkListQuery {
    pub(crate) fn params(&self) -> (Option<String>, Params<'_>) {
        let endpoint = normalize_endpoint(&self.endpoint);
        let mut p = Vec::new();
        push(&mut p, "date", &self.date);
        push(&mut p, "from", &self.from);
        push(&mut p, "to", &self.to);
        (endpoint, p)
    }
}

/// 一括ダウンロード URL 取得(`/bulk/get`)の条件
#[derive(Debug, Clone, Default)]
pub struct BulkGetQuery {
    /// `/bulk/list` が返した `key`
    pub key: Option<String>,
    /// 対象エンドポイントのパス(先頭の `/` は省略可)
    pub endpoint: Option<String>,
    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
    pub date: Option<String>,
}

impl BulkGetQuery {
    pub(crate) fn params(&self) -> (Option<String>, Params<'_>) {
        let endpoint = normalize_endpoint(&self.endpoint);
        let mut p = Vec::new();
        push(&mut p, "key", &self.key);
        push(&mut p, "date", &self.date);
        (endpoint, p)
    }
}

/// endpoint パラメータの先頭に `/` を補完する
fn normalize_endpoint(endpoint: &Option<String>) -> Option<String> {
    endpoint.as_ref().map(|e| {
        if e.starts_with('/') {
            e.clone()
        } else {
            format!("/{e}")
        }
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn code_date_query_skips_none() {
        let q = CodeDateQuery {
            code: Some("86970".into()),
            from: Some("2026-01-01".into()),
            ..Default::default()
        };
        assert_eq!(q.params(), vec![("code", "86970"), ("from", "2026-01-01")]);
    }

    #[test]
    fn code_date_query_empty() {
        assert!(CodeDateQuery::default().params().is_empty());
    }

    #[test]
    fn code_shortcut() {
        let q = CodeDateQuery::code("7203");
        assert_eq!(q.params(), vec![("code", "7203")]);
    }

    #[test]
    fn margin_interest_query_sends_published_date() {
        let q = MarginInterestQuery {
            code: Some("86970".into()),
            published_date: Some("2026-09-28".into()),
            ..Default::default()
        };
        assert_eq!(
            q.params(),
            vec![("code", "86970"), ("published_date", "2026-09-28")]
        );
    }

    #[test]
    fn calendar_query_uses_camel_case_param() {
        let q = CalendarQuery {
            holiday_division: Some("1".into()),
            ..Default::default()
        };
        assert_eq!(q.params(), vec![("holidayDivision", "1")]);
    }

    #[test]
    fn bulk_query_normalizes_endpoint() {
        let (endpoint, _) = BulkListQuery {
            endpoint: Some("equities/bars/daily".into()),
            ..Default::default()
        }
        .params();
        assert_eq!(endpoint.as_deref(), Some("/equities/bars/daily"));

        let (endpoint, _) = BulkGetQuery {
            endpoint: Some("/equities/bars/daily".into()),
            ..Default::default()
        }
        .params();
        assert_eq!(endpoint.as_deref(), Some("/equities/bars/daily"));
    }
}