支援制度情報提供サービス API V2 リファレンス

API共通仕様

支援制度情報提供サービス API の共通仕様を記載しています。

リクエスト

URL

リクエストの URL は、大文字・小文字が区別されません。

 

パラメータ

リクエストのパラメータは、URLのパスの一部、またはクエリパラメータで指定します。

 

URLのパスの一部で指定するパラメータは、リファレンスに ”{パラメータ名}” の形式で記載しています。

http://api.r-assistance.go.jp/v2/supports.{format}
http://api.r-assistance.go.jp/v2/supports/{id}.{format}

※URLのパスの一部で指定するパラメータを省略した場合は、予期しない結果となります。

 

クエリパラメータは、URLに「?」を連結し、「パラメータ名=値」の形式で指定します。
複数のパラメータを指定する場合は、2つ目以降のパラメータを「&」で連結します。

http://api.r-assistance.go.jp/v2/supports.xml?count=50
http://api.r-assistance.go.jp/v2/supports.xml?count=50&page=1

※リファレンスに記載のないクエリパラメータが指定された場合、そのパラメータは無視されます。

※省略不可のクエリパラメータを省略した場合、エラー(400:Bad Request) となります。

 

共通のパラメータ

次に記載するパラメータは、各リクエストで共通のパラメータです。

パラメータ名

省略可否

説明

{format}

必須

レスポンスデータの形式を指定します。

“xml” :レスポンスデータがXML形式で返ります。

“json” :レスポンスデータがJSON形式で返ります。

※一部のAPI (openumリクエスト) は、”xml”のみ指定可能です。

appkey

必須

常に0を指定してください。

※0以外の値を指定した場合、エラー(401:Unauthorized) となります。

callback

省略可

レスポンスをJSONPで受け取る場合、コールバック関数名を指定します。

※{format} パラメータで ”xml” を指定している場合は無視されます。

※各APIの説明内では、このパラメータの説明を省略しています。

 

SSLアクセス

APIは、HTTPSでアクセスすることもできます。HTTPSでアクセスする場合は、リクエストURLのプロトコルをHTTPSに変更します。

https://api.r-assistance.go.jp/v2/supports.xml

 

CORS

APIは、"Access-Control-Allow-Origin" ヘッダの設定によりCross Origin Resource Sharing (CORS) に対応しています。

XMLHttpRequest Level 2 に対応したブラウザからクロス ドメイン アクセスを行うことができます。

 

利用回数制限

APIは呼び出し元IPアドレス毎に利用回数制限を設けています。

1時間あたり、5,000回を超えてアクセスした場合、エラー(403:Forbidden) となります。

※制限の単位時間および回数は、予告なく変更する場合があります。

同じAPIを同じパラメータで何度も呼び出さないようにしたり、一度取得した結果はキャッシュしておく等、APIの呼び出し回数をなるべく減らすなどして利用されることを推奨します。

 

レスポンス

XML

API の XML レスポンスは、下記の共通仕様に準拠します。

 

・XML形式のレスポンスデータは、「(リクエスト名※)_response」という名前のルート要素でラップされ、レスポンスのメインデータはルート要素の子要素 (トップレベル要素) に含まれます。

※ 一部のリクエストでは、リクエスト名と異なる場合があります。各APIのレスポンスXMLの内容を確認ください。

 

例:supportsリクエストのXMLレスポンス

<supports_response>                       ←ルート要素
    <total_count>integer</total_count>    ←トップレベル要素1
    <supports>                            ←トップレベル要素2
        <support>                         ←トップレベル要素2の子要素
            …
        </support>
    </supports>
</supports_response>

 

・XML属性は使用されず、全てのデータがXML要素で返ります。

・データが含まれない要素は、次の条件で出力有無が決定されます。

  - 配列以外の要素は、データが含まれない場合は要素が出力されません。

  - トップレベル要素の配列型の要素は、データが0件でも空の配列要素が出力されます。

  - トップレベル要素の子孫要素の配列型の要素は、データが0件の場合は出力されません。

・日付を表すデータはISO8601形式 (例:2012-10-29T09:00:00+09:00)の 文字列で返ります。

・データ値に改行が含まれる場合、改行コード「LF」が出力されます。

 

JSON

API の JSON レスポンスは、下記の共通仕様に準拠します。

 

・レスポンスは1個の連想配列 (ルート要素) を含むデータで出力され、連想配列のフィールド (トップレベル要素) にレスポンスのメインデータが含まれます。

 

例: supportsリクエストのJSONレスポンス

{                                ←ルート要素に相当
    "total_count": {integer},    ←トップレベル要素1に相当
    "supports": [                ←トップレベル要素2に相当
        {                        ←トップレベル要素2の子要素に相当
            …
        }
    ]
}

 

・データが含まれない要素は、次の条件で出力有無が決定されます。

  - 配列以外の要素は、データが含まれない場合は要素が出力されません。

  - トップレベル要素の配列型の要素は、データが0件でも空の配列要素が出力されます。

  - トップレベル要素の子孫要素の配列型の要素は、データが0件の場合は出力されません。

・日付を表すデータはISO8601形式 (例:2012-10-29T09:00:00+09:00)の 文字列で返ります。

・データ値に改行が含まれる場合、” \u000a”(LF) が出力されます。

 

エラー

APIのリクエストでエラーが発生した場合は、次のエラーコードおよびレスポンスを出力します。

 

エラーコード

コード

説明

400

Bad request. 渡されたパラメータの内容が APIで期待されたものと一致しない場合。

401

Unauthorized. 許可されていないアクセスであった場合。

403

Forbidden. APIの利用回数制限を超えている場合。

404

Not found. 指定されたURLが存在しない場合。

500

Internal Server Error. サーバーの内部エラーなどの問題によってデータを返すことができない場合。

503

Service unavailable. サーバーが高負荷の状態や、メンテナンス中などの理由によりデータを返すことができない場合。

 

エラーレスポンス (XML)

<error_response>
    <error>
        <message>エラーメッセージ</message>
    </error>
</error_response>

エラーレスポンス (JSON)

{
    "error": {
        "message": "エラーメッセージ"
    }
}

 

※ リクエストURLの指定間違い等で、APIのURIに一致しなかった場合は、上記の形式のエラーレスポンスが返らない場合があります。

その他

Web APIの機能停止

今後、廃止となるAPIが出てきた場合は、APIリファレンスページにて非推奨の旨を記載し、一定期間はそのまま利用できる状態とします。
また、可能であれば代替えの新しいAPIを用意し、リファレンスページにて推奨します。

Web APIの仕様変更

APIの仕様変更については、既存機能に影響が大きいと考えられるもの (※1) については、廃止予定と同様の扱いとし、代替えの新しいAPIを用意します。
また、影響の度合いが少ないと考えられるもの (※2) は、事前にAPIリファレンスページにて告知を行うこととします。

※1 APIを利用するプログラムの修正が必要と考えられる変更。

※2 APIを利用するプログラムの修正が必要なケースが少ないと考えられる変更。
   (例:リクエストのパラメータ追加、レスポンスへの新規フィールド追加)