WebAPI利用マニュアル

第2版

改定履歴
版数

発行日

改定内容

１2024/4/1

初版発行

22024/4/1

P.13、21 インバランス料金単価取得APIのリクエストURLを修正
P.16、22 インバランス料金単価算定根拠取得APIのリクエストURLを修正

1

目次
１．はじめに
1.1
1.2
1.3
1.4

「WebAPI」の役割
本マニュアルの使い方
アクセスプロトコル
利用規約

２．WebAPIでできること
2.1 WebAPI概要
2.1.1 インバランス料金単価取得API
2.1.2 インバランス料金単価算定根拠取得API

３．各WebAPIの詳細説明
3.1 インバランス料金単価取得API
3.2 インバランス料金単価算定根拠取得API
3.3 httpステータスコード

４．利用例
５．用語説明2

１．はじめに31.１「WebAPI」の役割

本マニュアルは，一般利用者が，インバランス単価中央算定システム（以下，ICS）にWebサービスで要求を送信して取得結果を受信するための一般利用者向けアプリケーションインタフェース（以下，WebAPI）仕様を規定します。
本WebAPIは，利用者のアプリケーションからICSのWebサービスに向けて送信される取得用API実行要求を受信時に，同Webサービス上で実行され，取得結果を利用者のアプリケーションに送信します。

リクエストパラメータ送信元

ICS①取得用API実行要求受信

利用者のアプリケーション

Webサービス②取得結果を送信

4

1.２

本マニュアルの使い方

本マニュアルは，ICSと接続するクライアントシステム開発者を主対象として，本WebAPIの仕様，操作処理等を説明します。また，本マニュアルの利用には，HTTPSやAPIの仕組みなどのWebサービスの知識が必要です。

5

1.3

アクセスプロトコル

本WebAPIでは，アクセスプロトコルとしてHTTPSを採用し，任意のパラメータを設定したリクエストURLで通信を行います。
ここでリクエストURLとは，ICSからデータを取得する際，当該データの対象となるパラメータを付与したURLであり，利用者はあらかじめ定義されたフォーマットでリクエストURLを作成する必要があります。詳細については，「３．各WebAPIの詳細説明」に記載します。

6

1.4

利用規約

本WebAPIのご利用開始前に，下記の利用規約を必ずお読みいただき，ご同意の上ご利用いただくようお願いします。また，本WebAPIの利用において，サーバへの負荷を考慮し，各種APIへのリトライは，30秒間隔で5回までとしていただくようお願いします。万一ご同意いただけない場合には，ご利用をお控えください。ご利用いただいた場合には，下記の利用規約に記載の諸条件すべてにご同意いただいたものとさせていただきます。
利用規約
https://www.imbalanceprices-cs.jp/show/footer/terms_of_use.pdf

7

２．WebAPIでできること

8

2.1

WebAPI概要■ICSのWebサービスで利用できるWebAPIは下表に示す2種類です。
No

12

API名

インバランス料金単価取得API

インバランス料金単価算定根拠取得API

データ形式

動作説明

CSV

対象年月・リビジョンを指定し，インバランス料金単価データをCSV形式で取得します。
対象年月・リビジョンの指定がない場合，最新年月であり，その最新年月のうち最新リビジョンのインバランス料金単価データをCSV形式で取得します。

CSV

対象年月・リビジョンを指定し，インバランス料金単価算定根拠データをCSV形式で取得します。
対象年月・リビジョンの指定がない場合，最新年月であり，その最新年月のうち最新リビジョンのインバランス料金単価算定根拠データをCSV形式で取得します。

9

WebAPI
インバランス料金単価

2.1.1

インバランス料金単価取得API

・指定された年月のインバランス料金単価をまとめたCSVデータを取得します。
・以下の年月，リビジョンのデータが取得可能です。
①最新年月の，最新リビジョン②指定された対象年月の，最新リビジョン③指定された対象年月の，指定されたリビジョン

・取得可能な期間は，インバランス料金単価ファイルの公表直後 ≦ システム時刻＜（該当ファイルの対象年度の5年後の年度末）です。
＜例＞ 2024年4月を指定した場合2024年4月2030年3月31日23:59

取得可能な期間・「インバランス料金単価取得API 」の詳細は， 3.1節 を参照してください。

10

WebAPI
インバランス料金単価算定根拠

2.1.2

インバランス料金単価算定根拠取得API

・指定された年月のインバランス料金単価算定根拠をまとめたCSVデータを取得します。
・以下の年月，リビジョンのデータが取得可能です。
①最新年月の，最新リビジョン②指定された対象年月の，最新リビジョン③指定された対象年月の，指定されたリビジョン

・取得可能な期間は，インバランス料金単価算定根拠ファイルの公表直後 ≦ システム時刻＜（該当ファイルの対象年度の5年後の年度末）です。
＜例＞ 2024年4月を指定した場合2024年4月

2030年3月31日23:59

取得可能な期間・「インバランス料金単価算定根拠取得API」の詳細は， 3.2節 を参照してください。

11

３．各WebAPIの詳細説明

12

3.1

インバランス料金単価取得API・リクエストに関しては以下の通りです。
■リクエストURL
https://www.imbalanceprices-cs.jp/api/1.0/imb/price/{対象年月}/{リビジョン}（※ {}は含まない， {} 内は可変）
上記URLの{}内のパラメータを指定することで，APIによりインバランス料金単価を取得できます。
ただし，取得するデータの対象年月を指定しない場合は，最新年月かつ最新リビジョンを取得できます。また， リビジョンを指定しない場合は，最新リビジョンを取得できます。
■リクエストパラメータ
No.

項

１

対象年月

２目

リビジョン

必須説

明-

YYYYMM形式で指定（YYYY：0000～9999，MM：01～12 ）
指定なし時はCSVデータが存在する最新年月-

指定なし時は対象年月のうち最新リビジョン※ 対象年月を指定しなかった場合は指定不可※ 入力フォーマットについては以降を参照

13

3.1

インバランス料金単価取得API■リビジョンの入力フォーマットについて
フォーマット：整数(1～99）
・初回公表時は，「1」・更新された場合は，整数部1加算※ インバランス料金単価ファイルが更新時，同時にインバランス料金算定根拠ファイルも更新されます。

(例) 2022年4月の初回公表時
インバランス料金単価ファイル：1

インバランス料金算定根拠ファイル： 1.00
↓両ファイルが同時更新
インバランス料金単価ファイル：2

インバランス料金算定根拠ファイル： 2.00

14

3.1

インバランス料金単価取得API

・レスポンスに関しては以下の通りです。
■ レスポンスヘッダー
Content-Type: text/csv; charset=MS932■レスポンスパラメータ
No.
１２

項 目
ステータス
インバランス料金単価
CSV

必須説

明

〇

3.3 httpステータスコードを参照-

ステータスコードが200の場合，リクエストに合わせた内容のインバラン
ス料金単価CSVを返却
取得するデータ項目については，インバランス料金情報公表Webサイトからダウンロードできる「インバランス料金単価ファイル」と同等

15

3.2

インバランス料金単価算定根拠取得API・リクエストに関しては以下の通りです。
■リクエストURL
https://www.imbalanceprices-cs.jp/api/1.0/imb/basis/{対象年月}/{リビジョン}（※ {}は含まない， {} 内は可変）
上記URLの{}内のパラメータを指定することで，APIによりインバランス料金単価算定根拠を取得できます。
ただし，取得するデータの対象年月を指定しない場合は，最新年月かつ最新リビジョンを取得できます。また， リビジョンを指定しない場合は，最新リビジョンを取得できます。
■リクエストパラメータNo.

項

１

対象年月

２目

リビジョン

必須説明

-

YYYYMM形式で指定（YYYY：0000～9999，MM：01～12 ）
指定なし時はCSVデータが存在する最新年月-

指定なし時は対象年月のうち最新リビジョン※ 対象年月を指定しなかった場合は指定不可※ 入力フォーマットについては以降を参照

16

3.2

インバランス料金単価算定根拠取得API■リビジョンの入力フォーマットについて
フォーマット：小数（1.00～99.99)
・初回公表時は，「1.00」
・インバランス料金単価算定根拠ファイルのみ更新された場合は，整数部不変，小数部「0.01」加算
・インバランス料金単価ファイルと同時更新時，インバランス料金単価算定根拠ファイルは整数部1加算，小数部00。
(例) 2022年4月の初回公表時
インバランス料金単価ファイル：1

インバランス料金算定根拠ファイル： 1.00↓
「インバランス料金単価算定根拠ファイル」のみ更新
インバランス料金単価ファイル：1

インバランス料金算定根拠ファイル： 1.01↓
両ファイルが同時更新
インバランス料金単価ファイル：2

インバランス料金算定根拠ファイル： 2.00

17

3.2

インバランス料金単価算定根拠取得API・レスポンスに関しては以下の通りです。
■ レスポンスヘッダー
Content-Type: text/csv; charset=MS932■レスポンスパラメータ
No.
１２項 目
ステータス

インバランス料金単価算定根拠CSV

必須説

明

〇

3.3 httpステータスコードを参照-

ステータスコードが200の場合，リクエストに合わせた内容のインバラン
ス料金単価算定根拠CSVを返却取得できるデータ項目については，インバランス料金情報公表Webサイトからダウンロードできる「インバランス料金単価算定根拠ファイル」と同等

18

3.3

httpステータスコード

・ WebAPIによる処理結果が設定されるhttpステータスコードに関しては以下の通りです。
■ httpステータスコード
ステータスコード200

説明リクエストが成功し，ICSのサーバで正常に受け付けた
リクエストは成功したが，返却するデータが存在しない

204

（例）
・指定された対象年月に対応する指定されたリビジョンが存在しない
・取得可能な期間の対象外（取得可能な期間は2.1.1項，2.1.2項を参照）

503

公表ファイル作成中のため，再度リクエストが必要

Exception等を参照して個別に対処が必要

上記以外

（例）
・400：クライアント側のエラーで，リクエストパラメータが不正である
・404：URLが不正である

19

4．利用例20利用例・各WebAPIの利用例は以下の通りです。
■インバランス料金単価取得API
No.

ケース

リクエストURL

１

最新年月および最新リビジョンのインバランス料金単価ファイルのデータを取得する場合

https://www.imbalanceprices-cs.jp/api/1.0/imb/price/２

対象年月を2023年4月に指定し，最新リビジョンのインバランス料金単価ファイルのデータを取得する場合

https://www.imbalanceprices-cs.jp/api/1.0/imb/price/202304

3

対象年月を2023年4月に指定し，リビ
ジョン2のインバランス料金単価ファイルのデータを取得する場合

https://www.imbalanceprices-cs.jp/api/1.0/imb/price/202304/2

21利用例・各WebAPIの利用例は以下の通りです。
■インバランス料金単価算定根拠取得API
No.

ケース

リクエストURL

１

最新年月および最新リビジョンのインバランス料金単価算定根拠ファイルのデータを取得する場合

https://www.imbalanceprices-cs.jp/api/1.0/imb/basis/２

対象年月を2023年4月に指定し，最新リビジョンのインバランス料金単価算
定根拠ファイルのデータを取得する場
合https://www.imbalanceprices-cs.jp/api/1.0/imb/basis/202304

3

対象年月を2023年4月に指定し，リビジョン2.01のインバランス料金単価算定根拠ファイルのデータを取得する場
合https://www.imbalanceprices-cs.jp/api/1.0/imb/basis/202304/2.01

22

5．用語説明

23

用語説明
No

用語説明

1

ICS

インバランス料金単価中央算定システム（Imbalance prices Calculation Service)2

インバランス料金単価ファイルインバランス料金単価[円/kWh]を記載したファイル

3

インバランス料金単価算定根拠ファイル

インバランス料金単価を算出するために用いた諸元を記載したファイル
ある月の公表ファイルが，最初に公表されてから何回 改訂 ・ 更新 されたかを識別するための番号。インバランス料金単価ファイルは整数(1～99），インバラン
ス料金算定根拠ファイルは小数（1.00～99.99) であり初回公表時はそれぞれ「1」，「1.00」となる。
その後，両者が同時更新された場合は整数部1加算，小数部00となり，インバラン
ス料金単価算定根拠ファイルのみ更新された場合※は，整数部不変，小数部「0.01」加算となる。
※インバランス料金単価ファイルのみが更新されることはありません。

4

リビジョン

(例) 2022年4月の初回公表時
インバランス料金単価ファイル：1
インバランス料金算定根拠ファイル： 1.00↓
「インバランス料金単価算定根拠ファイル」のみ更新
インバランス料金単価ファイル：1
インバランス料金算定根拠ファイル： 1.01↓
両ファイルが同時更新
インバランス料金単価ファイル：2
インバランス料金算定根拠ファイル： 2.00
24