新規中小企業情報 API の共通仕様を記載しています。
リクエストの URL は、大文字・小文字が区別されません。
リクエストのパラメータは、URLのパスの一部、またはクエリパラメータで指定します。
URLのパスの一部で指定するパラメータは、リファレンスに ”{パラメータ名}” の形式で記載しています。
例
https://api.u10sme.go.jp/v1/corporations.{format}
※URLのパスの一部で指定するパラメータを省略した場合は、予期しない結果となります。
クエリパラメータは、URLに「?」を連結し、「パラメータ名=値」の形式で指定します。
複数のパラメータを指定する場合は、2つ目以降のパラメータを「&」で連結します。
例
https://api.u10sme.go.jp/v1/corporations.xml?limit=50 https://api.u10sme.go.jp/v1/corporations.xml?limit=50&offset=50
※リファレンスに記載のないクエリパラメータが指定された場合、そのパラメータは無視されます。
※省略不可のクエリパラメータを省略した場合、エラー(400:Bad Request) となります。
次に記載するパラメータは、各リクエストで共通のパラメータです。
パラメータ名 |
省略可否 |
説明 |
{format} |
必須 |
レスポンスデータの形式を指定します。 “json” :レスポンスデータがJSON形式で返ります。 “xml” :レスポンスデータがXML形式で返ります。 |
callback |
省略可 |
レスポンスをJSONPで受け取る場合、コールバック関数名を指定します。 ※{format} パラメータで ”xml” を指定している場合は無視されます。 ※各APIの説明内では、このパラメータの説明を省略しています。 |
APIは、HTTPSでのみアクセスできます。
APIは、"Access-Control-Allow-Origin" ヘッダの設定によりCross Origin Resource Sharing (CORS) に対応しています。
XMLHttpRequest Level 2 に対応したブラウザからクロス ドメイン アクセスを行うことができます。
APIは呼び出し元IPアドレス毎に利用回数制限を設けています。
1時間あたり、1,000回を超えてアクセスした場合、エラー(403:Forbidden) となります。
※制限の単位時間および回数は、予告なく変更する場合があります。
同じAPIを同じパラメータで何度も呼び出さないようにしたり、一度取得した結果はキャッシュしておく等、APIの呼び出し回数をなるべく減らすなどして利用されることを推奨します。
API の XML レスポンスは、下記の共通仕様に準拠します。
・XML形式のレスポンスデータは、「(リクエスト名※)Response」という名前のルート要素でラップされ、レスポンスのメインデータはルート要素の子要素 (トップレベル要素) に含まれます。
※ 一部のリクエストでは、リクエスト名と異なる場合があります。各APIのレスポンスXMLの内容を確認ください。
例:corporationsリクエストのXMLレスポンス
<corporationsResponse> ←ルート要素 <count>integer</count> ←トップレベル要素1 <corporations> ←トップレベル要素2 <corporation> ←トップレベル要素2の子要素 … </corporation> </corporations> </corporationsResponse>
・XML属性は使用されず、全てのデータがXML要素で返ります。
・データが含まれない要素は、次の条件で出力有無が決定されます。
- 配列以外の要素は、データが含まれない場合は要素が出力されません。
- トップレベル要素の配列型の要素は、データが0件でも空の配列要素が出力されます。
- トップレベル要素の子孫要素の配列型の要素は、データが0件の場合は出力されません。
・日付を表すデータはISO8601形式 (例:2012-10-29T09:00:00)の 文字列で返ります。
・データ値に改行が含まれる場合、改行コード「LF」が出力されます。
API の JSON レスポンスは、下記の共通仕様に準拠します。
・レスポンスは1個の連想配列 (ルート要素) を含むデータで出力され、連想配列のフィールド (トップレベル要素) にレスポンスのメインデータが含まれます。
例: corporationsリクエストのJSONレスポンス
{ ←ルート要素に相当 "count": {integer}, ←トップレベル要素1に相当 "corporations": [ ←トップレベル要素2に相当 { ←トップレベル要素2の子要素に相当 … } ] }
・データが含まれない要素は、次の条件で出力有無が決定されます。
- 配列以外の要素は、データが含まれない場合は要素が出力されません。
- トップレベル要素の配列型の要素は、データが0件でも空の配列要素が出力されます。
- トップレベル要素の子孫要素の配列型の要素は、データが0件の場合は出力されません。
・日付を表すデータはISO8601形式 (例:2012-10-29T09:00: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> <Message>エラーメッセージ</Message> </Error>
エラーレスポンス (JSON)
{ "message": "エラーメッセージ" }
※ リクエストURLの指定間違い等で、APIのURIに一致しなかった場合は、上記の形式のエラーレスポンスが返らない場合があります。