株主優待を検索する。複数条件を組み合わせて絞り込める。

【重要: vestingDates と karaDates の違い】 vestingDates（権利確定日）: 現物保有で優待を得るための権利確定月日。「○月に権利確定する銘柄」はこちら。 karaDates（空クロス日）: 権利確定日だけでなく別の日付にも株を一定数保有する必要がある銘柄の、その追加保有日。 端株保有だけでは条件を満たせず、その日付にクロス取引（空クロス）で株数を確保する必要がある。 「○月に空クロスが必要な銘柄」→ karaDate="MM" または karaDateFrom/karaDateTo で検索する。 vestingDate で検索しても空クロス対象の銘柄は正しく絞り込めない。

【信用取引区分 lendingType】 both=制度信用売り可。制度信用でクロスができる buying_only=制度信用買いのみ可、売りが使えないため制度信用ではクロスができない none=信用取引不可

【制度信用の規制 systemLendingStatus】各結果に付く。none=規制なし / warn=注意喚起(増担保・申込停止等) / prohibited=売禁(制度信用の新規売り停止)。lendingType(構造的な区分)とは別で、日々変動する。 ・売禁の銘柄だけ / 除外したい → sellProhibited=true / false ・注意喚起の銘柄だけ / 除外したい → sellCaution=true / false ・売禁または注意喚起(要注意銘柄)だけ / 除外したい → sellRestricted=true / false データ未取得の銘柄は「規制なし」として扱う。

【増担保 marginRateMultiplier】各結果に付く。増担保金徴収措置による最高料率倍率(例: 10=10倍)。 systemLendingStatusとは別の措置で、売禁・注意喚起と同時に付くことも単独で付くこともある。措置無しはundefined。 ・倍率で絞り込みたい → minMarginRateMultiplier / maxMarginRateMultiplier(措置無しの銘柄は対象外になる)

【長期条件】longType: none=なし / longAddition=長期優遇 / longOnly=長期必須 【難易度】rarity: 前回権利時の一般信用在庫の推移(証券会社別)から算出した「一般信用クロスでの 確保しやすさ」。canNormalSelling_* / minRemain_* とは別の、過去実績ベースの総合指標。 S(最難。在庫がほぼ出回らない)>A>B>C>D>E(最易。常時潤沢) ※minRarity='A' → AかSの銘柄のみ 【一般信用売り】canNormalSelling_*: enableSelling=売り可(空売含) / enableLongSelling=長期売りのみ可 / notEnableSelling=不可 【一般信用残】minRemain_sbi/gmo: few=△以上 / remaining=◎のみ。minRemain_rakuten/kabucom/smbc: 数量指定 【利回り】actualYield(%): 優待の申込単位ごとに (評価額 ÷ (株価×その単位の株数)) × 100 を計算し、 達成可能な最良の値を採用する(必要株数がminRequiredUnitsと異なる場合がある)。 長期保有条件(details[].longType='required'/'additional')付きの上位ランク・追加分はクロス (初回取得)では届かないため対象外(longTypeが無い基本額のみで計算)。 クロスの手数料・貸株料・逆日歩は一切含まない額面利回り。 ※minValue/maxValue(評価額の最小値/最大値)・minRequiredUnits(必要株数の最小値)は、それぞれ独立の別統計であり 同じ申込単位の値とは限らない(actualYieldの算出には使わない)。 【手取り利回り】netYield(%): (優待評価額 - 必要クロスコスト)/必要資金×100。必要クロスコストに逆日歩は 含まない(一般信用クロスのみが対象で、逆日歩が発生する制度信用は含まないため)。 ・各結果に crossCost(必要クロスコスト)/crossCostBroker/crossCostSellMethod/netValue/netYield が付く。 ・比較対象は「今この銘柄で実際にできる一般信用クロス」に限る: - その証券会社で一般信用売りの取り扱いがあり(enableShort/enableUnlimited)、かつ残数がある - 短期(general_short)は SBI/GMO/楽天のみ。約定日が売建可能日以降であること - 制度信用クロスは常に対象外(逆日歩リスクがあるため netYield には含めない) ・上記を満たす手段が1つも無い銘柄、株価・優待評価額・権利確定日が無い銘柄、 今からでは決済が間に合わない銘柄には netYield が付かない(= 今すぐ得できる優待の指標)。 ・「手数料を引いても得な優待」は minNetYield / sortBy:netYield で絞る。 ・返す数件には常に付くが、sortBy:netYield / minNetYield / maxNetYield を指定したときだけ 全候補に対して計算する(それ以外は最終ページの数件のみ計算)。 ・使ったプラン設定(ゼロ革命/コース/大口優遇/約定日)はヘッダー行に出る。ユーザーの実際の契約と 違う場合は sbiZeroRevolution / rakutenCourse / kabucomLargeLot / date 等で指定し直せることを案内すること。 【逆日歩】prevLendingInterest: 直近1回(前回の権利付き最終日)の逆日歩実績のみ(平均ではない)を、 1日あたり・株価に対する比率に換算した値(0.01=1日あたり1%)。制度信用クロスのコスト目安に使う。 過去複数回の履歴(ワースト10・直近10日)や一般信用在庫の推移は get_benefit に sections:["negativeInterests"] / ["remainingHistories"] を指定して取得する。 【並べ替え】sortBy / order で並べ替え、件数は limit で指定する(省略時20件。sortByとは独立)。 「手取り利回り順トップ10」→ sortBy:netYield と limit:10 を両方指定する(sortByだけでは10件に絞らない)。 他に「必要資金の少ない順」→ requiredFunds、「前回逆日歩が高い順」→ prevLendingInterest(一般信用推奨候補)。 sortBy 省略時は並べ替えなし。

【出力フィールドの読み方】 unit/minRequiredUnits: 権利確定日に必要な通常の株数 details[]: 優待の詳細条件一覧。各要素に以下が含まれる: candidates[].unit: その条件での必要株数 longType: 'additional'=長期優遇 / 'required'=長期必須 longCondition: 長期保有条件の概要テキスト（例: "継続保有期間1年以上"） longConditionDetail: 長期保有条件の詳細テキスト 「空クロスで必要な株数を教えて」→ details[].longConditionDetail のテキストから株数を読み取る 「長期条件を教えて」→ details[].longCondition と details[].longConditionDetail を参照する 「空クロスの有無」→ karaDates の有無を確認する（details の longType とは別物）

【details[].candidates の金額と vestingDates（複数権利月）の対応】 vestingDates が複数ある銘柄（例: ["03","09"]=年2回）で、candidates[].detail に月の但し書き （「3月のみ」「(9月)」等）が無い場合、その金額(value)は権利月ごとに同額が適用される （例: vestingDates=["03","09"], detail="500円分" → 3月に500円分・9月にも500円分もらえる。 年間合計は1000円分であり、「9月分かどうか不明」ではない）。 一方、detail に特定の月が明記されている場合（例:「(3月のみ)クオカード3,000円相当 (9月)クオカード2,000円分」）は、 明記された月にのみその内容が適用され、他の月は別の候補行（candidates の別要素）を参照する。 「○月にもらえる優待は？」と聞かれたら、月の但し書きが無い限り vestingDates に含まれる 全ての月で同じ内容がもらえると回答すること（「不明」「要確認」と答えない）。