Skip to main content

jquants_api/
query.rs

1//! 各エンドポイントの検索条件。すべて `Default` を実装しているので
2//! 必要な条件だけ指定して `..Default::default()` で埋められる。
3//! 日付は API の仕様どおり `YYYY-MM-DD` または `YYYYMMDD` 形式の文字列で渡す。
4
5type Params<'a> = Vec<(&'static str, &'a str)>;
6
7fn push<'a>(params: &mut Params<'a>, key: &'static str, value: &'a Option<String>) {
8    if let Some(v) = value {
9        params.push((key, v.as_str()));
10    }
11}
12
13/// 銘柄コード・日付・期間の共通条件
14/// (日足・分足・バリュエーション指標・売買内訳・日々公表信用取引残高・配当・指数日足で使用)
15#[derive(Debug, Clone, Default)]
16pub struct CodeDateQuery {
17    /// 銘柄コード(例: "7203")
18    pub code: Option<String>,
19    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
20    pub date: Option<String>,
21    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
22    pub from: Option<String>,
23    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
24    pub to: Option<String>,
25}
26
27impl CodeDateQuery {
28    /// 銘柄コードのみ指定するショートカット
29    pub fn code(code: impl Into<String>) -> Self {
30        Self {
31            code: Some(code.into()),
32            ..Self::default()
33        }
34    }
35
36    pub(crate) fn params(&self) -> Params<'_> {
37        let mut p = Vec::new();
38        push(&mut p, "code", &self.code);
39        push(&mut p, "date", &self.date);
40        push(&mut p, "from", &self.from);
41        push(&mut p, "to", &self.to);
42        p
43    }
44}
45
46/// 上場銘柄マスタ(`/equities/master`)の条件
47#[derive(Debug, Clone, Default)]
48pub struct MasterQuery {
49    /// 銘柄コード(例: "7203")
50    pub code: Option<String>,
51    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
52    pub date: Option<String>,
53}
54
55impl MasterQuery {
56    pub(crate) fn params(&self) -> Params<'_> {
57        let mut p = Vec::new();
58        push(&mut p, "code", &self.code);
59        push(&mut p, "date", &self.date);
60        p
61    }
62}
63
64/// 投資部門別売買状況(`/equities/investor-types`)の条件
65#[derive(Debug, Clone, Default)]
66pub struct InvestorTypesQuery {
67    /// 市場区分(例: TSEPrime)
68    pub section: Option<String>,
69    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
70    pub from: Option<String>,
71    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
72    pub to: Option<String>,
73}
74
75impl InvestorTypesQuery {
76    pub(crate) fn params(&self) -> Params<'_> {
77        let mut p = Vec::new();
78        push(&mut p, "section", &self.section);
79        push(&mut p, "from", &self.from);
80        push(&mut p, "to", &self.to);
81        p
82    }
83}
84
85/// 営業日カレンダー(`/markets/calendar`)の条件
86#[derive(Debug, Clone, Default)]
87pub struct CalendarQuery {
88    /// 休日区分(API パラメータ `holidayDivision`)
89    pub holiday_division: Option<String>,
90    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
91    pub from: Option<String>,
92    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
93    pub to: Option<String>,
94}
95
96impl CalendarQuery {
97    pub(crate) fn params(&self) -> Params<'_> {
98        let mut p = Vec::new();
99        push(&mut p, "holidayDivision", &self.holiday_division);
100        push(&mut p, "from", &self.from);
101        push(&mut p, "to", &self.to);
102        p
103    }
104}
105
106/// 信用取引残高(`/markets/margin-interest`)の条件。
107/// API の仕様上 `code` / `date` / `published_date` のいずれかの指定が必須。
108/// `published_date` は `date` / `from` / `to` と同時指定できない(API 側でエラーになる)
109#[derive(Debug, Clone, Default)]
110pub struct MarginInterestQuery {
111    /// 銘柄コード(例: "7203")
112    pub code: Option<String>,
113    /// 申込日 (YYYY-MM-DD または YYYYMMDD)
114    pub date: Option<String>,
115    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
116    pub from: Option<String>,
117    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
118    pub to: Option<String>,
119    /// 公表日 (YYYY-MM-DD または YYYYMMDD)。2026-09-25 申込分以降の行だけが対象
120    pub published_date: Option<String>,
121}
122
123impl MarginInterestQuery {
124    pub(crate) fn params(&self) -> Params<'_> {
125        let mut p = Vec::new();
126        push(&mut p, "code", &self.code);
127        push(&mut p, "date", &self.date);
128        push(&mut p, "from", &self.from);
129        push(&mut p, "to", &self.to);
130        push(&mut p, "published_date", &self.published_date);
131        p
132    }
133}
134
135/// 業種別空売り比率(`/markets/short-ratio`)の条件
136#[derive(Debug, Clone, Default)]
137pub struct ShortRatioQuery {
138    /// 33 業種コード
139    pub s33: Option<String>,
140    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
141    pub date: Option<String>,
142    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
143    pub from: Option<String>,
144    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
145    pub to: Option<String>,
146}
147
148impl ShortRatioQuery {
149    pub(crate) fn params(&self) -> Params<'_> {
150        let mut p = Vec::new();
151        push(&mut p, "s33", &self.s33);
152        push(&mut p, "date", &self.date);
153        push(&mut p, "from", &self.from);
154        push(&mut p, "to", &self.to);
155        p
156    }
157}
158
159/// 空売り残高報告(`/markets/short-sale-report`)の条件
160#[derive(Debug, Clone, Default)]
161pub struct ShortSaleReportQuery {
162    /// 銘柄コード(例: "7203")
163    pub code: Option<String>,
164    /// 公表日 (YYYY-MM-DD または YYYYMMDD)
165    pub disc_date: Option<String>,
166    /// 公表日の開始日
167    pub disc_date_from: Option<String>,
168    /// 公表日の終了日
169    pub disc_date_to: Option<String>,
170    /// 計算日 (YYYY-MM-DD または YYYYMMDD)
171    pub calc_date: Option<String>,
172}
173
174impl ShortSaleReportQuery {
175    pub(crate) fn params(&self) -> Params<'_> {
176        let mut p = Vec::new();
177        push(&mut p, "code", &self.code);
178        push(&mut p, "disc_date", &self.disc_date);
179        push(&mut p, "disc_date_from", &self.disc_date_from);
180        push(&mut p, "disc_date_to", &self.disc_date_to);
181        push(&mut p, "calc_date", &self.calc_date);
182        p
183    }
184}
185
186/// 期間のみの条件(`/indices/bars/daily/topix`)
187#[derive(Debug, Clone, Default)]
188pub struct RangeQuery {
189    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
190    pub from: Option<String>,
191    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
192    pub to: Option<String>,
193}
194
195impl RangeQuery {
196    pub(crate) fn params(&self) -> Params<'_> {
197        let mut p = Vec::new();
198        push(&mut p, "from", &self.from);
199        push(&mut p, "to", &self.to);
200        p
201    }
202}
203
204/// 先物四本値(`/derivatives/bars/daily/futures`)の条件
205#[derive(Debug, Clone, Default)]
206pub struct FuturesBarsQuery {
207    /// 商品区分(例: TOPIXF/NK225F)
208    pub category: Option<String>,
209    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
210    pub date: Option<String>,
211    /// 中心限月フラグ(API パラメータ `contractFlag`)
212    pub contract_flag: Option<String>,
213}
214
215impl FuturesBarsQuery {
216    pub(crate) fn params(&self) -> Params<'_> {
217        let mut p = Vec::new();
218        push(&mut p, "category", &self.category);
219        push(&mut p, "date", &self.date);
220        push(&mut p, "contractFlag", &self.contract_flag);
221        p
222    }
223}
224
225/// オプション四本値(`/derivatives/bars/daily/options`)の条件
226#[derive(Debug, Clone, Default)]
227pub struct OptionsBarsQuery {
228    /// 商品区分(例: TOPIXF/NK225F)
229    pub category: Option<String>,
230    /// 銘柄コード(例: "7203")
231    pub code: Option<String>,
232    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
233    pub date: Option<String>,
234    /// 中心限月フラグ(API パラメータ `contractFlag`)
235    pub contract_flag: Option<String>,
236}
237
238impl OptionsBarsQuery {
239    pub(crate) fn params(&self) -> Params<'_> {
240        let mut p = Vec::new();
241        push(&mut p, "category", &self.category);
242        push(&mut p, "code", &self.code);
243        push(&mut p, "date", &self.date);
244        push(&mut p, "contractFlag", &self.contract_flag);
245        p
246    }
247}
248
249/// 財務系 cursor エンドポイント(`/fins/summary` `/fins/details`)の条件
250#[derive(Debug, Clone, Default)]
251pub struct FinsQuery {
252    /// 銘柄コード(例: "7203")
253    pub code: Option<String>,
254    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
255    pub date: Option<String>,
256    /// 前回応答の `cursor` を渡すと差分取得になる
257    pub cursor: Option<String>,
258}
259
260impl FinsQuery {
261    pub(crate) fn params(&self) -> Params<'_> {
262        let mut p = Vec::new();
263        push(&mut p, "code", &self.code);
264        push(&mut p, "date", &self.date);
265        push(&mut p, "cursor", &self.cursor);
266        p
267    }
268}
269
270/// 決算発表予定日(`/fins/earnings-date`)の条件。
271/// API の仕様上 `code` / `date` / `scheduled_date` のいずれか 1 つの指定が必須
272#[derive(Debug, Clone, Default)]
273pub struct EarningsDateQuery {
274    /// 銘柄コード(5桁、例: "86970")
275    pub code: Option<String>,
276    /// 公表日 (YYYY-MM-DD または YYYYMMDD)
277    pub date: Option<String>,
278    /// 決算発表予定日 (YYYY-MM-DD または YYYYMMDD)
279    pub scheduled_date: Option<String>,
280}
281
282impl EarningsDateQuery {
283    pub(crate) fn params(&self) -> Params<'_> {
284        let mut p = Vec::new();
285        push(&mut p, "code", &self.code);
286        push(&mut p, "date", &self.date);
287        push(&mut p, "scheduled_date", &self.scheduled_date);
288        p
289    }
290}
291
292/// EDINET 系エンドポイント(`/edinet/*`)共通の条件。
293/// `edinet_code` と `code` は同時指定できない(API 側でエラーになる)
294#[derive(Debug, Clone, Default)]
295pub struct EdinetQuery {
296    /// 提出者・発行者の EDINET コード(例: "E03814")
297    pub edinet_code: Option<String>,
298    /// 銘柄コード(例: "86970")
299    pub code: Option<String>,
300    /// 提出日 (YYYY-MM-DD または YYYYMMDD)
301    pub date: Option<String>,
302}
303
304impl EdinetQuery {
305    pub(crate) fn params(&self) -> Params<'_> {
306        let mut p = Vec::new();
307        push(&mut p, "edinet_code", &self.edinet_code);
308        push(&mut p, "code", &self.code);
309        push(&mut p, "date", &self.date);
310        p
311    }
312}
313
314/// 適時開示一覧(`/td/list`)の条件
315#[derive(Debug, Clone, Default)]
316pub struct TdListQuery {
317    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
318    pub date: Option<String>,
319    /// 銘柄コード(例: "7203")
320    pub code: Option<String>,
321    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
322    pub from: Option<String>,
323    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
324    pub to: Option<String>,
325    /// 開示項目コード(API パラメータ `discItems`)
326    pub disc_items: Option<String>,
327    /// 前回応答の `cursor` を渡すと差分取得になる
328    pub cursor: Option<String>,
329}
330
331impl TdListQuery {
332    pub(crate) fn params(&self) -> Params<'_> {
333        let mut p = Vec::new();
334        push(&mut p, "date", &self.date);
335        push(&mut p, "code", &self.code);
336        push(&mut p, "from", &self.from);
337        push(&mut p, "to", &self.to);
338        push(&mut p, "discItems", &self.disc_items);
339        push(&mut p, "cursor", &self.cursor);
340        p
341    }
342}
343
344/// 一括ダウンロード一覧(`/bulk/list`)の条件
345#[derive(Debug, Clone, Default)]
346pub struct BulkListQuery {
347    /// 対象エンドポイントのパス(例: `/equities/bars/daily`。先頭の `/` は省略可)
348    pub endpoint: Option<String>,
349    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
350    pub date: Option<String>,
351    /// 期間の開始日 (YYYY-MM-DD または YYYYMMDD)
352    pub from: Option<String>,
353    /// 期間の終了日 (YYYY-MM-DD または YYYYMMDD)
354    pub to: Option<String>,
355}
356
357impl BulkListQuery {
358    pub(crate) fn params(&self) -> (Option<String>, Params<'_>) {
359        let endpoint = normalize_endpoint(&self.endpoint);
360        let mut p = Vec::new();
361        push(&mut p, "date", &self.date);
362        push(&mut p, "from", &self.from);
363        push(&mut p, "to", &self.to);
364        (endpoint, p)
365    }
366}
367
368/// 一括ダウンロード URL 取得(`/bulk/get`)の条件
369#[derive(Debug, Clone, Default)]
370pub struct BulkGetQuery {
371    /// `/bulk/list` が返した `key`
372    pub key: Option<String>,
373    /// 対象エンドポイントのパス(先頭の `/` は省略可)
374    pub endpoint: Option<String>,
375    /// 対象日 (YYYY-MM-DD または YYYYMMDD)
376    pub date: Option<String>,
377}
378
379impl BulkGetQuery {
380    pub(crate) fn params(&self) -> (Option<String>, Params<'_>) {
381        let endpoint = normalize_endpoint(&self.endpoint);
382        let mut p = Vec::new();
383        push(&mut p, "key", &self.key);
384        push(&mut p, "date", &self.date);
385        (endpoint, p)
386    }
387}
388
389/// endpoint パラメータの先頭に `/` を補完する
390fn normalize_endpoint(endpoint: &Option<String>) -> Option<String> {
391    endpoint.as_ref().map(|e| {
392        if e.starts_with('/') {
393            e.clone()
394        } else {
395            format!("/{e}")
396        }
397    })
398}
399
400#[cfg(test)]
401mod tests {
402    use super::*;
403
404    #[test]
405    fn code_date_query_skips_none() {
406        let q = CodeDateQuery {
407            code: Some("86970".into()),
408            from: Some("2026-01-01".into()),
409            ..Default::default()
410        };
411        assert_eq!(q.params(), vec![("code", "86970"), ("from", "2026-01-01")]);
412    }
413
414    #[test]
415    fn code_date_query_empty() {
416        assert!(CodeDateQuery::default().params().is_empty());
417    }
418
419    #[test]
420    fn code_shortcut() {
421        let q = CodeDateQuery::code("7203");
422        assert_eq!(q.params(), vec![("code", "7203")]);
423    }
424
425    #[test]
426    fn margin_interest_query_sends_published_date() {
427        let q = MarginInterestQuery {
428            code: Some("86970".into()),
429            published_date: Some("2026-09-28".into()),
430            ..Default::default()
431        };
432        assert_eq!(
433            q.params(),
434            vec![("code", "86970"), ("published_date", "2026-09-28")]
435        );
436    }
437
438    #[test]
439    fn calendar_query_uses_camel_case_param() {
440        let q = CalendarQuery {
441            holiday_division: Some("1".into()),
442            ..Default::default()
443        };
444        assert_eq!(q.params(), vec![("holidayDivision", "1")]);
445    }
446
447    #[test]
448    fn bulk_query_normalizes_endpoint() {
449        let (endpoint, _) = BulkListQuery {
450            endpoint: Some("equities/bars/daily".into()),
451            ..Default::default()
452        }
453        .params();
454        assert_eq!(endpoint.as_deref(), Some("/equities/bars/daily"));
455
456        let (endpoint, _) = BulkGetQuery {
457            endpoint: Some("/equities/bars/daily".into()),
458            ..Default::default()
459        }
460        .params();
461        assert_eq!(endpoint.as_deref(), Some("/equities/bars/daily"));
462    }
463}