get_benefit
銘柄コードで株主優待を1件取得する。sections で返す情報を選ぶ(不要なものは返さない)。
basic (既定): 銘柄の基本情報。優待内容・権利確定日(vestingDates)・ 空クロス日(karaDates)・信用区分(lendingType)・制度信用の規制状態(systemLendingStatus: none/warn=注意喚起/prohibited=売禁)・増担保の最高料率倍率(marginRateMultiplier)・ 長期条件・難易度・株価・必要資金・実質利回り(actualYield)・ 現時点の一般信用残数(normalLendingStatus)・details(候補と長期保有条件)。
negativeInterests: 逆日歩(制度信用売りで発生しうる、金額が事前に確定しない追加費用)の履歴。 prev(前回権利付最終日の1件)/ worst10(過去ワースト10、逆日歩/日 の降順)/ latest(直近10日)。 negativeInterestPerDiem / highestNegativeInterestPerDiem は「円/株」の文字列で lendingDays 日分。 1日あたりは negativeInterestPerDiem / lendingDays。balancePrice はその日の建値。 逆日歩は過去実績であり将来を保証・予測するものではない点をユーザーに必ず伝えること。
remainingHistories: 一般信用売りの在庫ステータスの推移。prev(前回権利前3ヶ月)/ latest(直近1ヶ月)。
negativeInterests / remainingHistories は銘柄ごとに個別管理された詳細データが必要で、無い銘柄では notes に理由が入る。 basic のみ(既定)なら詳細データは取得しないため軽量。
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | 銘柄コード。例: "3397" | |
| sections | No | 返す情報の種類(配列)。省略時は ["basic"]。逆日歩履歴が欲しいときは ["basic","negativeInterests"]、在庫推移も含めるなら ["basic","negativeInterests","remainingHistories"] |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | 銘柄コード | |
| name | No | ||
| unit | No | 権利確定に必要な通常の株数(1単元) | |
| notes | No | 要求されたsectionの一部が取得できなかった場合の理由 | |
| price | No | 利回りや手数料の計算で使用している概算株価。現在の正確な株価ではない。取得できない銘柄はundefined | |
| anyDay | No | 基準日以外の「任意の日」にも保有状況を抜き打ち確認する旨が長期条件に明記されているか(要注意銘柄) | |
| rarity | No | 一般信用クロスの取得難易度(前回権利時の在庫推移から算出)。S(最難)>A>B>C>D>E(最易) | |
| update | No | 優待内容(details等)が最後に変更された日(YYYY-MM-DD)。新設や変更(株式分割による区分変更・優待内容の変更・長期優遇の廃止等)があった際に更新される。何が変わったかは updateNote を参照 | |
| details | No | 優待内容の詳細条件一覧 | |
| message | No | 銘柄が見つからない場合のメッセージ。このときcode以外の他フィールドは付かない | |
| siteUrl | No | ||
| summary | No | ||
| longType | No | 長期条件。通常は none/longAddition/longOnly のいずれか | |
| maxValue | No | 優待評価額(円)の最大値。優待の申込単位が複数ある場合、その中の最大の評価額 | |
| minValue | No | 優待評価額(円)。優待の申込単位が複数ある場合、その中の最小の評価額 | |
| karaDates | No | 空クロスが必要な月/月日パターン(vestingDatesとは別物) | |
| updateNote | No | update日時点で何が変わったか(または新設か)を記した短い注記。例: "新設" / "株式分割による区分変更。ポイントアップ。長期優遇を廃止" | |
| actualYield | No | 実利回り(%)。優待の申込単位ごとに(評価額 ÷ (株価×その単位の株数)) × 100 を計算し、達成可能な最良の値を採用する(必要な株数がminRequiredUnitsより多い単位が選ばれることがある)。長期保有条件付きの上位ランク・追加分(details[].longType='required'/'additional')はクロス(初回取得)では届かないため対象外。クロスの手数料・貸株料・逆日歩は一切含まない額面利回り | |
| description | No | ||
| lendingType | No | 制度信用区分。both=制度信用売り可 / buying_only=買いのみ可 / none=不可 | |
| benefitTypes | No | ||
| nextKaraDate | No | 次回の具体的な空クロス日(ISO文字列) | |
| vestingDates | No | 権利確定の月または月日パターン(年に依存しない繰り返しパターン) | |
| requiredFunds | No | 最小株数(minRequiredUnits)で優待を得るために必要な資金(円) = price × minRequiredUnits | |
| nextVestingDate | No | 次回の具体的な権利確定日(ISO文字列) | |
| karaDateConcrete | No | ||
| minRequiredUnits | No | この優待を得るために必要な最小株数。申込単位が複数ある場合はその中の最小株数 | |
| negativeInterests | No | sections に "negativeInterests" を指定し、この銘柄の逆日歩履歴データが存在するときだけ付く | |
| remainingHistories | No | sections に "remainingHistories" を指定し、この銘柄の一般信用在庫推移データが存在するときだけ付く | |
| normalLendingStatus | No | 証券会社別の一般信用在庫の現在ステータス | |
| prevLendingInterest | No | 前回の逆日歩率。直近1回(前回の権利付き最終日)の実績のみで、複数回の平均ではない。逆日歩額を1日あたり・株価に対する比率に換算した値(0.01=1日あたり1%)で、制度信用クロスのコスト目安に使う。過去複数回分の履歴は sections:["negativeInterests"] を参照 | |
| systemLendingStatus | No | 制度信用の規制状態。none=規制なし / warn=注意喚起 / prohibited=売禁。lendingTypeとは別軸で日々変動する | |
| vestingDateConcrete | No | 次回権利確定日(ISO文字列) | |
| marginRateMultiplier | No | 増担保金徴収措置による最高料率倍率(通常の委託保証金率に対する倍率。例: 10=10倍)。systemLendingStatusとは別の措置で、売禁・注意喚起と同時に付くことも単独で付くこともある。措置無しはundefined |