全国道路施設点検データベース
登録用 API 基本仕様書

国土交通省

― 目次 ―

1. 本概要書の目的 ......................................................... 1
2. 登録用 API 基本仕様書の定義仕様項目 ..................................... 2
3. 登録用 API の定義 ...................................................... 3
API 接続方式....................................................................3
通信プロトコル ................................................................3
REST 対応 ..................................................................3
エンドポイント（接続先 URL） ..................................................3
バージョンコード ...............................................................3
日本語の文字コード ...........................................................3
施設種類ごとのデータ内容概要 ......................................................3
施設の種類ごとの ID について....................................................3リクエスト ........................................................................4
施設データの登録 API .........................................................4
処理状況監視 API ...........................................................4
付属ファイル登録 API ..........................................................4レスポンス .......................................................................5
JSON 形式のデータ ............................................................5
エラーレスポンス ...............................................................6
API 一覧........................................................................7
データ登録 API の処理フロー .................................................7
データ登録 API 一覧 ..........................................................8
各 API において指定するパラメータ ....................................................9(1) 施設データ登録 API............................................................9(2) 処理状況監視 API ...........................................................10(3) 付属ファイルの登録 API ........................................................11
パラメータの定義における留意事項 ...................................................13パラメータ構造 ...............................................................13パラメータ名 .................................................................13選択肢 ....................................................................13複数年データ................................................................13
日付表記の統一.............................................................13

利用制限 ......................................................................14
利用申請 ......................................................................14
認証機能 .....................................................................14
API キー方式 ..............................................................14
利用規約 .....................................................................14

4. 用語集 ................................................................ 15

1. 本概要書の目的
登録用 API 基本仕様書は、「全国道路施設データベース」において、各道路施設データベースに対し、オンラインにて道路構造物に関する諸元や点検データ等を登録するための API に関する基本仕様書です。
登録用 API 基本仕様書は、以下の 3 点の資料で構成しています。
・登録 API 基本仕様書（本書）・API リファレンスサンプル「基本仕様書」は、上記 API の基本的な記述仕様を示すものとします。
（2019 年 3 月 28 日 API テクニカルガイドブック((内閣官房情報通信技術(IT)総合戦略室))に準拠）「API リファレンスサンプル」は、API による呼出しや実行結果の詳細仕様例のサンプルを示すものとします。
尚、「API リファレンスサンプル」の概要を 4.リファレンスサンプルの概要に示します。

尚、登録用 API のセキュリティ対策については、取り扱う情報の機密性を確保するために API キー方式を採用しています。

12. 登録用 API 基本仕様書の定義仕様項目
本登録用 API 基本仕様書における定義項目は以下のとおり。
項

題名内容

3.1

API 接続方式

API の接続プロトコル等の仕様

3.2

施設種類ごとの ID について

施設種類ごとに異なるデータ項目等の仕様

3.3

リクエスト

API 呼び出し時のパラメータ等

3.4

レスポンス

API 呼び出し結果の仕様

3.5.

データ登録 API の一覧

施設データ登録 API の概要と API 一覧

3.6

各 API において指定するパラメータ

施設データの登録 API ごとに取得できるデータの仕様

3.7

パラメータの定義における留意事項

API のパラメータの命名仕様など

3.8

利用制限

API の利用を制限する場合の仕様

3.9

利用申請

認証を要する API を利用するための必要な申請について

3.10

認証機能本 API で採用する認証方式について

3.11

利用規約

本 API を利用する上での仕様

2

3. 登録用 API の定義
API 接続方式
通信プロトコル
セキュアな HTTP プロトコルである HTTPS によって通信を行う。
API を設置するサーバは TLS(SSL)対応を必須とする。TLS のバージョンは 1.2 以降とする。
REST 対応
本 API のデータ参照様式は、REST(記述方式)に則った仕様を基本とする。
エンドポイント（接続先 URL）
接続先の URL は以下の仕様とする
https://{API 設置サーバのドメイン}/xROAD/api/{バージョンコード}/{リソース名}?{検索条件}
リソース名とは参照するデータの種類を表し、リソース名の後ろに検索条件を記述するものとする。
リソース名や検索条件の内容については後述する。
バージョンコードバージョンコードは頭文字 v + バージョン数字とし、エンドポイントに含めて記述される。
例えばバージョン 1 なら「v1」と記述する。
日本語の文字コード
本 API を利用した通信上で、日本語を扱う場合の文字コードは UTF-8 とする。
施設種類ごとのデータ内容概要
施設の種類ごとの ID について
本 API による施設データの参照は、施設の種類ごとにサーバが異なるため、URL を分別する。
以下に URL 内にて、施設の種類を区別するための ID を示す。
ID

意味

bridge道路橋

tunnel

トンネル

shed

シェッド

culvert

大型カルバート

pedestrian_deck

横断歩道橋

overhead_signage

門型標識

pavement

舗装

earthwork

道路土工構造物(大型カルバートを除く)

signage標識

lighting

照明

3

リクエスト
施設データの登録 API
REST の仕様に則って、POST メソッドを用いる。
登録する施設データは JSON 形式のファイルを用いる。
アップロードする施設データファイルの仕様• ファイル形式は、JSON 形式にとする。(RFC8259)• 文字コードは UTF-8 とする。
• 項目名の省略、独自の項目名の利用は禁止とする。
• 特殊記号、機種依存文字の利用は禁止とする。
• 施設 ID+点検年度で一意のデータとする。
• 施設アップロードファイルの項目名については、別紙「公開用 API 基礎項目パラメータ名一覧」を参照。
ただし、今後新たに追加されるデータ項目のパラメータ名は、「3.７」の留意事項に従って命名し、上記パラメータ名の扱いは、本 API 基本仕様書の API の記述ルールに準じる。
処理状況監視 API
REST の仕様に則って、GET メソッドを用いる。
付属ファイル登録 API
REST の仕様に則って、POST メソッドを用いる。

4

レスポンス
JSON 形式のデータ
JSON 形式の文字列として、以下のデータを返す。

• metadata
API の内容やリクエスト情報など• resultset
エラーの有無や内容など• result
GET メソッドの場合は取得したデータを、それ以外の場合は処理結果を返す。
上記の要素を下表に再掲する。
No.

区分

1

metadata

プロパティ名
title

必須◯

内容
データの内容を示すタイトル

2

detail3

parameter◯

リクエスト時に渡されたパラメータ

is_error◯

処理にエラーがある場合は true。ない場合は false

4

resultset

データの内容説明5error_title

エラーのタイトル。is_error が true の場合は必須

6error_detail

エラーの詳細─

処理結果

8result

レスポンス例（正常）{"metadata": {"title": "施設データの登録","detail": "施設データの登録","parameter": {"type": 1}},"resultset": {"is_error": false},"result": {(処理結果)}}

5レスポンス例（エラー）{"metadata": {"title": "施設データの登録","detail": "施設データの登録","parameter": {"type": 1}},"resultset": {"is_error": true,"error_title": "file が指定されていません""error_detail": "file が指定されていません"}}

エラーレスポンス
処理中に致命的なエラーが発生した場合、適切な HTTP レスポンスコードとエラー内容を JSON 形式で返す。
No.

レスポンスコード内容

1400

リクエスト内容に問題有り

2401

認証エラー

3

404

存在しない API にアクセスされた

4429

一定時間内のアクセス数超過

5500

サーバ内部エラー

6503

メンテナンス中

レスポンスボディ(本文)に JSON 形式でエラーの内容を記述する。
No.

プロパティ名

内容

1

code

HTTP レスポンスコード

2

message

エラーの詳細な内容

レスポンス例{"code": 400,"message": "検索範囲が日本国内を超えています"}6

API 一覧
データ登録 API の処理フロー
施設データの登録処理における、処理フローを以下に示す。
API 提供者側

API 利用者側
施設データ登録 API
処理 ID を返す

登録処理開始処理状況監視 API 処理 ID を指定
処理状況を返す(未完了)
完了するまで繰り返し処理状況監視 API 処理 ID を指定
処理状況を返す(完了)

登録処理が完了するまで待ってから付属ファイルをアップロード（ファイルの数の分、繰り返し）

付属ファイル登録 API
処理 ID を返す• 処理 ID
登録処理中の状況を監視するために、一時的に発行される ID。
システムが発行するユニークな値とする。

7

登録処理完了データ登録 API 一覧
データ登録 API の一覧を以下に示す。尚、各 API にて指定する具体的なパラメータは 3.6 に示す。
No.

メソッド

1

施設データの/{施設種類 ID}s/import

施設データの 登

登録 API例) /bridges/import

録処理実行

処理状況監視/{施設種類 ID}s/import/status/{処理 ID}

登録処理中のAPI

例) /bridges/import/status/9999

登録状況の監

2

記述規則

内容視
3

付属ファイル登/{施設種類 ID}s/upload/{施設 ID}/{年度}

施設データの 付録 API例) /bridges/upload/35.2134,139.112/2020

属ファイルをアップロードして登録

8各 API において指定するパラメータ(1) 施設データ登録 API
指定した施設データファイル（*.json）をアップロードし、取込処理を開始する。
取込処理開始後は、処理完了を待たずにレスポンスとして処理 ID を返す。
パス: {施設種類 ID}s/import
メソッド: POST
No.

パラメータ

内容

省略時

1File

施設データファイル（*.json）

省略不可

2

Type

処理タイプ(1:追加更新 2:削除)

省略不可

データの送信には RFC7578 に則って「multipart/form-data」形式を利用する。
レスポンスとして以下のパラメータが返される。
No.

パラメータ

内容

例

1status

処理状況(0: 未実行 1:実行中 2:完了 3:エラー)

2

2

message

メッセージ“登録が完了しました”3

processid

処理 ID654321

使用例(ドメインは仮称)
施設データの登録
POST https://www.example.go.jp/xROAD/api/v1/bridges/import
HTTP ヘッダ
Content-Type: multipart/form-data; boundary=----BoundaryO5quBRiT4G7Vm3R7
リクエストボディ------BoundaryO5quBRiT4G7Vm3R7
Content-Disposition: form-data; name="type"1------BoundaryO5quBRiT4G7Vm3R7
Content-Disposition: form-data; name="file"; filename="ファイル名"Content-Type: text/plain（ファイルの内容）------BoundaryO5quBRiT4G7Vm3R7--9

(2) 処理状況監視 API
指定処理 ID の施設データファイルの取込処理状況を取得する。
パス: {施設種類 ID}s/import/status/{処理 ID}
メソッド: GET
レスポンスとして以下のパラメータが返される。
No.

パラメータ

内容例

1

status

処理状況(0: 未実行 1:実行中 2:完了 3:エラー)

2

2

message

メッセージ“登録が完了しました”使用例(ドメインは仮称)処理 ID「9999」の処理状況を取得する
GET https://www.example.go.jp/xROAD/api/v1/bridges/import/status/9999
施設データの取込処理の完了待ちに使用する。

10

(3) 付属ファイルの登録 API
指定した施設 ID・点検年度の施設データに、付属ファイルをアップロードする。
パス: {施設種類 ID}s/upload/{施設 ID}/{年度}
メソッド: POST
No.

パラメータ

内容

省略時

1

file

アップロード対象ファイル省略不可

2

total

送信するファイルの総数

1

3

count

何番目のファイルかを表す、1 から始まる数字

1

4

processid

最初の施設データ送信時に発行された処理 ID

新規処理として処理 IDを新たに発行するデータの送信には RFC7578 に則った「multipart/form-data」形式を利用する。
レスポンスとして以下のパラメータが返される。
No.

パラメータ

内容

例

1

message

メッセージ“ファイル送信が完了しました”2

processid

リクエスト時に受け取った処理 ID をそのまま返す。ただ654321

し、リクエスト時に処理 ID が指定されていなかった場合は、新規に処理 ID を発行されて返す
使用例(ドメインは仮称)
施設 ID「35.2134,139.112」、年度「2020」の施設データに付属ファイルの登録
POST
https://www.example.go.jp/xROAD/api/v1/bridges/upload/35.2134,139.112/2020
HTTP ヘッダ
Content-Type: multipart/form-data; boundary=----BoundaryO5quBRiT4G7Vm3R7
リクエストボディ------ BoundaryO5quBRiT4G7Vm3R7
Content-Disposition: form-data; name="total"
10------ BoundaryO5quBRiT4G7Vm3R7
Content-Disposition: form-data; name="count"7------ BoundaryO5quBRiT4G7Vm3R7
Content-Disposition: form-data; name="processid"

117654321------ BoundaryO5quBRiT4G7Vm3R7
Content-Disposition: form-data; name="file"; filename="ファイル名"Content-Type: text/plain（ファイルの内容）------BoundaryO5quBRiT4G7Vm3R7--

12パラメータの定義における留意事項
点検項目の定義をもとにして、API のパラメータを設定するにあたり、できるだけ表記のゆれをなくして使いやすくするために、以下の基準でパラメータの定義を行うものとする。
パラメータ構造・項目のグループごとにまとめて入れ子にし、ツリー状の構造とする・JSON で表現できるデータ構造とする・パラメータ名を表記する場合は、入れ子の親から子へ順に「.」(ドット)で繋いで表記とする。
パラメータ名・半角英数字で表記し、単語の接続はスネークケースとする・項目名をローマ字で表記する。ただし元がカタカナの場合は英語表記とする
例) 定義ファイル → teigi_file
・項目名が冗長になる場合は、項目名として使える適度な長さに短縮する
選択肢・複数の中から一つを選択する項目は、選択肢の内容を直接書き込むのではなく、コード表を作成してコードを入力する。
例) 高速自動車国道・都道府県道・一般国道↓
1:高速自動車国道・2:都道府県道・3:一般国道
・「◯△□」などの記号や「有り・無し」などで表現されていた部分もコード表記に統一する。
例) 有り・無し → 1・0
複数年データ・2018,2019...といった年度毎に 1 列割り当てられているデータは、配列として表現する。
日付表記の統一・年データは西暦とする。フォーマットは YYYY例) 2021
・年月フォーマットは YYYYMM
例) 202109
・年月日フォーマットは YYYYMMDD
例) 20210901

13利用制限本 API を利用する場合は、それぞれの利用が承認された利用者にのみ利用を許諾する。
利用申請
本 API を利用するにあたり、規定の利用申請により、API の利用手続きを行うものとする。
認証機能
API キー方式による認証機能を具備した API の実装とする。
API キー方式
API を利用するアプリごとに API キーを発行し、API アクセス時にその API キーを HTTP ヘッダに記述することによって、発行対象のアプリからのアクセスであることを認証する。
発行対象以外のアプリからのアクセスを防ぐため、発行時に登録したドメイン名や IP アドレスからのアクセス以外は拒否する。
•API キー記述ヘッダ
API-key•API キーフォーマット
半角英数字 40 文字
利用規約
別途の利用規約を参照

14

4. 用語集
用語１：N

フリガナ
イチタイタ

定義
1 対多。一つのものに対して複数のものが相対すること
サービスのデータを外部のアプリケーションやプログラムから扱うためのAPI

エーピーアイ

機能を提供するための規約・仕様。Application
Programming Interface の略
アカウント情報などはなくアプリケーションを識別する暗号化された単API キー方式

エーピーアイキーホウ

純な文字列をクライアントが Request 内に含めて送る認証方式

シキ

で、仕込み先はヘッダーやクエリー、body などサービスによって異なる
HTTP リクエストメソッドの一つで、リソースの取得・参照を行うという

GETゲットHTTP ステータスコー

エイチティーティーピー

HTTP プロトコルに従った Web サーバからのレスポンスにおいて、そドステータスコードの通信結果を表す 3 桁のコード

HTTP プロトコル

HTTP ヘッダ

HTTP リクエスト

エイチティーティーピー
プロトコル

命令

インターネット上で、Web クライアントからリクエストを送り、それを受けて Web サーバからレスポンスを返すことで、データの送受信を行う規約

エイチティーティーピー

Web コンテンツの伝送に用いられる HTTP で、メッセージの前半にヘッダある制御情報を記した領域のこと

エイチティーティーピー
リクエスト

一方から他方へ送信される、何らかの要求、あるいは、メッセージのこと。本書の場合、API を呼び出す行為とそのために必要なデータのことを表す

HTTP リクエストボデ

エイチティーティーピー

HTTP リクエストを構成する 3 つの部品のひとつで、送信内容のィ

リクエストボディ「本文」にあたる部分

HTTP リクエストメソ

エイチティーティーピー

HTTP プロトコルで定義された、リソースに対する振る舞いを定義しッド

リクエストメソッド

た命令。GET・POST など数種類が定義されている

エイチティーティーピー

リクエストを受けた対象(サーバ)が処理の結果をリクエスト元に返すレスポンスこと。あるいば返すデータを指す

HTTP レスポンス
ITEF

アイティーイーエフ

JSON

ジェイソン

multipart/form-

マルチパート/フォーム

data

データPOST

ポスト

インターネット技術特別調査委員会。インターネットに関する標準化団体
異なるプログラミング言語間でデータをやりとりするための、共通のデータ記述形式の一つ。RFC8259 で定義
リクエストで複数のフォームデータ(マルチパート)を送るための形式。
複数の異なる種類のデータを格納する方式。主にファイルアップロードで利用される。
HTTP リクエストメソッドの一つで、リソースの作成を行うという命令

15

Web システムを外部から利用するためのプログラムの呼び出し規REST API

レストエーピーアイ

約（API）の種類の一つで、「REST」（レスト）と呼ばれる設計原則に従って策定されたもの

RFC

TLS(SSL)UCSURI エンコード

アールエフシーティーエルエス/エスエ
スエル
ユーシーエスIETF による技術仕様の保存、公開形式。インターネット上の通信を始めとする技術の仕様の標準としてよく使われる
インターネット上におけるウェブブラウザとウェブサーバ間でのデータの通信を暗号化し、送受信させる仕組み。現在は SSL の後継のTLS が用いられるが、慣習として SSL と呼ばれることが多い
符号化文字集合や文字符号化方式などを定めた、文字コードの国際標準のひとつで、業界規格の Unicode と概ね互換である

ユーアールアイエンコ

文字列を URL に含める場合に、RFC3986 に定められた利用可ード

能文字以外を変換して問題ない URL にすること
文字コードの国際的な業界標準の一つで、世界中の様々な言語Unicodeユニコードの文字を収録して通し番号を割り当て、同じコード体系のもとで使用できるようにしたもの

URI

ユーアールアイ

Uniform Resource Identifier の略称。インターネット上で、リソースの場所などを表現する識別子
Unicode/UCS で定義された文字集合を表現することができる文字コード（符号化方式）の一つ。一文字を 1～6 バイトの可変UTF-8

ユーティーエフエイト

長で表現するもので、様々な言語の文字を扱える文字コードとしては世界的に最も普及している。正式名称は、ISO/IEC 10646
では “UCS Transformation Format 8”、Unicode では“Unicode Transformation Format-8” という。

エンドポイント

エンドポイント

クエリパラメータ

クエリパラメータ

ネットワークに接続された端末のアドレス。本 API におけるエンドポ
イントは、API に アクセスするための URI を指す
API 利用時にサーバへ送る URI のうち、'?'以降の検索条件を表す部分
プログラミングなどで英語の複合語やフレーズ（句）、文を一語にスネークケース

スネークケース繋げて表記する際に、単語間のスペース（空白文字）をアンダースコア（_）に置き換える方式。

スレッド

プログラムの処理の実行単位。通常、分岐やループがあっても、プロ
スレッド

グラム全体は 1 つの流れになっている。

データフォーマット

データフォーマット

複合的なデータの記述方法を定めたもの。テータ形式

バイナリ

バイナリ

パラメータ

パラメータ

プログラムの動作を決定するために指定する数値や文字列

プログラム

プログラムコンピュータに対する命令（処理）を記述したもの

プロパティ

プロパティ

コンピュータが直接的に処理するために２進数で表現されるデータ（バイナリデータ）のことを指す

ソフトウェアが取り扱う対象の持つ設定や状態、属性などの情報を指す事が多い

16データを小さく分割した単位及びそのアクセス先をページと呼ぶ。全ページネーション

ページネーション

データではなく特定のデータを要求する場合、欲しいデータ（ページ）を指定することとなる

リソース名(本 API)

リソースメイ

本 API においては、API によって取得するデータの種類を表す名前のことを指す

17