--- title: 単位とスケール sidebar: order: 3 --- 数値フィールドの単位はレスポンスに機械可読な形で付与されます（self-describing）。AI クライアントや自動処理が桁を取り違えないためのものです。 ## 単位語彙 | 識別子 | 意味 | 使用例 | | --- | --- | --- | | `jpy` | 円 | 株価・売上高・営業利益などの財務金額・時価総額・企業価値（EV） | | `jpy_per_share` | 円/株 | EPS・BPS・DPS | | `percent` | %（10.1 = 10.1%） | ROE・配当利回り・前年比 | | `ratio` | 比率の生値（0.7763 = 77.63%） | 株主資本比率・配当性向・女性役員比率・男女賃金格差 | | `points` | ポイント（%ポイント差） | ROE 変化幅（3年前比）・ROE 要因分解の寄与 | | `times` | 倍（無次元） | PER・PBR・信用倍率 | | `shares` | 株 | 発行済株式数・出来高・保有株数・信用残 | | `people` | 人 | 従業員数・株主数・女性役員数 | | `t_co2e` | トンCO2換算（t-CO2e） | GHG 排出量 Scope1 / Scope2 / Scope3 | | `days` | 日 | 上場後経過日数・逆日歩日数 | | `years` | 年 | 連続増配年数・平均年齢 | | `months` | 月 | 手元流動性比率（現金が月商の何ヶ月分か） | | `count` | 回・件などの無次元カウント | テクニカル指標値・連続回数・合成スコア（ピオトロスキー F スコア等） | 単位を持たないフィールド（スクリーニング指標カタログの `type: enum` など）では `unit` は `null` になります。 次の 2 つはレスポンスには現れませんが、`/screening` の `filters` でしきい値の単位として指定できます（[スクリーニングのしきい値には単位を書けます](#スクリーニングのしきい値には単位を書けます)）。 | 識別子 | 意味 | 用途 | | --- | --- | --- | | `million_jpy` | 百万円 | しきい値の指定のみ | | `hundred_million_jpy` | 億円 | しきい値の指定のみ（MCP の指標カタログでは時価総額・EV の `unit` として返ります） | 金額は円で返すため桁が大きくなります。JavaScript の `JSON.parse` は 9,007,199,254,740,991（約 9,007 兆）を超えると精度が落ちます。収録されている単一項目の最大値は約 434 兆円（総資産）で上限の 1/20 ですが、複数項目・複数社を合算する場合は留意してください。 ## `ratio` と `percent` — 同じ概念でも単位は同じとは限りません `ratio` は 1.0 = 100% のスケール、`percent` は 100 = 100% のスケールです（どちらも 100% を超える値・負の値を取りえます。例: 配当性向）。**同じ「自己資本比率」でも、エンドポイントによってどちらで返すかが異なります**。値そのものは正しく、単位識別子が両者を区別しています。 | エンドポイント | フィールド | `unit` | 例（任天堂 FY2026） | | --- | --- | --- | --- | | `/financials` | `equity_ratio` | `ratio` | 0.7763 | | `/indicators` | `equity_ratio` | `ratio` | 0.7763 | | `/indicators` | `equity_ratio_computed` | `percent` | 77.63 | | `/screening/fields` | `equityRatio` | `ratio` | 0.7763 | `/indicators` では**報告値と計算値が別のキーで併存します**。`equity_ratio`・`roe`・`bps` は提出書類に記載された報告値、`equity_ratio_computed`・`roe_computed`・`bps_computed` は財務諸表の数値から算出した計算値で、算出方法が異なるため値は一致しません。 数値を解釈するときは、フィールド名ではなく必ずレスポンスの `unit`（`/screening` は `GET /screening/fields` の `unit`）を見てください。 ## スクリーニングのしきい値には単位を書けます `/screening` の `filters` は `field:op:value:unit` の 4 セグメントで書けます。`unit` を書くと、その単位で書かれたしきい値をサーバがフィールドの単位へ換算します。 ``` # 「時価総額 1,000 億円以上」 GET /v1/screening?filters=marketCap:gte:1000:hundred_million_jpy # 「自己資本比率 70% 以上」（equityRatio の unit は ratio だが percent で書ける） GET /v1/screening?filters=equityRatio:gte:70:percent ``` 換算は**同じ種類の単位のあいだだけ**で行います。金額（`jpy`・`million_jpy`・`hundred_million_jpy`）と比率（`ratio`・`percent`）が対象で、`times`（倍）や `jpy_per_share`（円/株）のように換算相手を持たない単位はそのフィールドの単位しか受け付けません。フィールドと換算できない単位を書いた場合は、受け付ける単位を添えた 400 が返ります（黙って別の意味で解釈されることはありません）。 ``` # 400 invalid_parameter: per の unit は times GET /v1/screening?filters=per:lte:15:percent ``` 換算が起きる単位を明示したしきい値は、後述の旧単位ガードの対象外です。`marketCap:gte:1000:hundred_million_jpy` は「1,000 億円」として曖昧さなく解釈されます。フィールド自身の単位をそのまま書いた場合（`marketCap:gte:1000:jpy`）は数値が省略時と同じなので、ガードの対象に含まれます。 MCP ツール `screen_securities` では `metric_filters[].unit` が同じ役割を持ちます。ただし MCP の金額フィールドは公開済み契約のため単位が億円で、外部 REST（円）とは異なります。どちらの面でも `GET /screening/fields` / `irbank://screening/fields` の `unit` が正です。 ### 単位を省略した場合 `unit` を省略した 3 セグメント（`field:op:value`）は、**そのフィールドの `unit` でしきい値を書いた**ものとして扱います。`unit: ratio` のフィールドに百分率のしきい値を渡してもリクエストとしては妥当なので**エラーにはならず、単に 0 件になります**。 ``` # 「自己資本比率 70% 以上」のつもり → 0 件（1.0 = 100% のスケールに 70 は現れない） GET /v1/screening?filters=equityRatio:gte:70 # 単位を省略するなら、フィールドの unit（ratio）に合わせて 0.7 と書く GET /v1/screening?filters=equityRatio:gte:0.7 ``` 金額のフィールド（`unit: jpy` の `marketCap`・`enterpriseValue`）も同じく円で指定します。こちらは旧単位（億円）とみられるしきい値を 400 で弾き、円での書き方を案内します。 ``` # 「時価総額 1,000 億円以上」のつもり → 400（1,000 円と解釈されるのを防ぐ） GET /v1/screening?filters=marketCap:gte:1000 # 正しい書き方（unit: jpy なので円で書く） GET /v1/screening?filters=marketCap:gte:100000000000 # 億円のまま書くなら単位を添える（この場合は 400 にならない） GET /v1/screening?filters=marketCap:gte:1000:hundred_million_jpy ``` 400 になるのは、しきい値が 0 より大きく 100 万円未満で、かつ**換算が起きなかった**場合（単位の省略、または `unit: jpy` の明示）です。`marketCap:gte:0` のような下限なしの指定はそのまま使えます。 `unit: ratio` のフィールド（`equityRatio`・`payoutRatio`・`ratioOfFemaleDirectors`・`ratioOfFemaleManagers`・`ratioOfMaleEmployeesTakingChildcareLeave`・`wageGap*`）は 70% を `0.7`、`unit: percent` のフィールド（`roe`・`dividendYield` など）は 70% を `70` と書きます。`unit: times`（`per`・`pbr`・`pegRatio`・`deRatio` など）は倍率で、比率ではありません。各フィールドがどちらかは `GET /screening/fields` の `unit` と `note` で確認できます。 なお、レスポンスの `metrics[].value` は指定した単位に関係なく、常にフィールドの `unit` で返ります。