基本設計書本文Word様式

Transcription

1 第 1.1 版 株 式 会 社 NTT ドコモ 2011 年 7 月 20 日

2 目 次 1 はじめに 本 書 の 目 的 本 書 の 定 義 範 囲 3 2 提 供 API 概 要 位 置 情 報 提 供 API 概 要 位 置 情 報 提 供 API 一 覧 本 人 位 置 情 報 取 得 API 前 バージョンとの 差 分 リクエスト 文 レスポンス 文 エラーコード 5 3 位 置 情 報 提 供 API 詳 細 本 人 位 置 情 報 取 得 API HTTPリクエスト HTTPレスポンス 処 理 結 果 コード 一 覧 処 理 シーケンス 例 リクエスト 例 レスポンス 例 31 Page 2

3 1 はじめに 1.1 本 書 の 目 的 基 地 局 を 利 用 した 位 置 情 報 提 供 は ユーザの 現 在 地 に 関 する 位 置 情 報 ( 緯 度 経 度 郵 便 番 号 住 所 など)を 日 本 国 内 にいるユーザに 対 して 提 供 する 機 能 である 位 置 情 報 利 用 サービスとしてスマートフォン 等 に 搭 載 されたアプリケーション( 以 下 位 置 情 報 利 用 サービス)が 株 式 会 社 NTT ドコモ( 以 下 ドコモ)の 提 供 する 位 置 情 報 提 供 サーバ 上 の API( 以 下 位 置 情 報 提 供 API)と 通 信 することで ユーザの 現 在 地 に 関 する 位 置 情 報 を 取 得 できる 本 書 はこの 位 置 情 報 提 供 機 能 における HTTP インタフェースに 関 する 仕 様 を 示 したものである 1.2 本 書 の 定 義 範 囲 サービスの 概 要 図 と 本 仕 様 書 で 定 義 するインタフェース 規 定 箇 所 について 以 下 に 示 す ドコモサーバ 位 置 情 報 取 得 スマートフォン ( 位 置 情 報 利 用 サービス) 位 置 情 報 提 供 サーバが 提 供 する API 本 仕 様 規 定 範 囲 サービス 概 要 と I/F 規 定 範 囲 Page 3

4 2 提 供 API 概 要 2.1 位 置 情 報 提 供 API 概 要 ユーザは 事 前 に 本 機 能 に 対 応 したサービスを 利 用 可 能 にしておく 必 要 がある スマートフォンの 場 合 には 位 置 情 報 取 得 機 能 に 対 応 したアプリのインストールが 必 要 である この 位 置 情 報 対 応 サービスより 位 置 情 報 提 供 サーバ 上 の API( 位 置 情 報 提 供 API)に 対 して HTTPS(データ 部 は XML 形 式 )による 取 得 要 求 が 行 われる 位 置 情 報 提 供 APIの 一 覧 については2.2 位 置 情 報 提 供 API 一 覧 を 参 照 2.2 位 置 情 報 提 供 API 一 覧 位 置 情 報 提 供 API の 一 覧 を 以 下 に 示 す 本 人 位 置 情 報 取 得 API 項 番 項 目 内 容 1. 機 能 概 要 利 用 者 本 人 の 現 在 位 置 情 報 を 提 供 する 2. URI 3. TCP ポート 番 号 APIバージョン* インターフェース 3.1 本 人 位 置 情 報 取 得 API 参 照 *1 API バージョンは 位 置 情 報 利 用 サービスが HTTP リクエスト 時 にリクエストボディ 部 で 設 定 する XML にて 指 定 する 表 XML 設 定 内 容 を 参 照 Page 4

5 本 人 位 置 情 報 取 得 APIのHTTPリクエスト HTTPレスポンス 例 HTTP リクエスト 例 POST /nwlocation/getlocation HTTP/1.1 Host: api.spmode.ne.jp Content-Length: Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <DDF ver="1.0"> <RequestInfo> <RequestParam> <APIKey> <APIKey1_ID> </APIKey1_ID > <APIKey2> </APIKey2> </APIKey> <OptionProperty> <AreaCode></AreaCode> <AreaName></AreaName> <Adr></Adr> <AdrCode></AdrCode> <PostCode></PostCode> </OptionProperty> </RequestParam> </RequestInfo> </DDF> HTTP レスポンス 例 HTTP/ OK Date: Thu, 21 Dec :23:47 GMT Connection: close Content-Length: Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <DDF> <ResultInfo> <TotalCount>1</TotalCount> <ResultCode>2000</ResultCode> </ResultInfo> <Feature> <Geometry> <Lat>N </Lat> <Lon>E </Lon> <Time> T12:23:45+09:00</Time> </Geometry> <OptionProperty> <AreaCode>00001</AreaCode> <AreaName> 千 代 田 区 </AreaName> <Adr> 東 京 都 千 代 田 区 千 代 田 </Adr> <AdrCode> </AdrCode> <PostCode> </PostCode> </OptionProperty> </Feature> </DDF> 2.3 前 バージョンとの 差 分 リクエスト 文 リクエスト 構 文 には 変 更 なし まったく 同 一 のままでリクエストが 可 能 レスポンス 文 正 常 時 には 変 更 なし 異 常 時 も 構 文 の 変 更 はなく エラーコードの 所 作 が 一 部 変 更 エラーコード ユーザ 許 可 設 定 の 変 更 に 伴 い いくつかエラーコードを 追 加 また エラーコード 4002 で 返 却 されるエラーの 内 容 が 変 更 詳 細 は 処 理 結 果 コード 一 覧 を 参 照 Page 5

6 3 位 置 情 報 提 供 API 詳 細 3.1 本 人 位 置 情 報 取 得 API HTTPリクエスト HTTP リクエストの 構 造 とリクエスト 例 を 以 下 に 示 す リクエストライン リクエストヘッダ 部 リクエストヘッダ 部 の 終 了 メソッド <SP> リクエスト URI <SP> HTTP バージョン <CRLF> ヘッダ 名 : <SP> ヘッダ 設 定 値 <CRLF> ヘッダ 名 : <SP> ヘッダ 設 定 値 <CRLF> : ヘッダ 名 : <SP> ヘッダ 設 定 値 <CRLF> <CRLF> リクエストボディ 部 位 置 情 報 クエリパラメータ(XML 形 式 ) 図 HTTP リクエスト 構 造 文 字 コード 改 行 コードについて HTTPリクエストで 許 容 する 文 字 コード 改 行 コードを 表 に 示 す 表 許 容 する 文 字 コード 改 行 コード(HTTP リクエスト) 項 番 箇 所 文 字 コード 改 行 コード 備 考 1. リクエストボディ 部 以 外 US-ASCII CR+LF - 2. リクエストボディ 部 (XML 形 式 ) UTF-8 CR+LF XML は BOM(Byte Order Mark)なしとする Page 6

7 リクエストライン リクエストラインのメッセージフォーマットを 表 に 示 す 表 リクエストラインのメッセージフォーマット 項 番 要 素 設 定 内 容 種 別 必 須 設 定 例 1. メソッド POST 固 定 - 2. リクエストURI 1 リクエスト 先 のリソース 可 変 nwlocation/getlocation 3. HTTP バージョン HTTP/1.1 固 定 - 凡 例 必 須 : 全 ての 要 求 で 付 与 : 要 求 により 付 与 種 別 固 定 : 固 定 値 のみ 可 変 : 可 変 な 値 1 リクエスト URI は FQDN を 含 む URI もしくはディレクトリパスによる URI のいずれかの 形 式 で 指 定 する /nwlocation/getlocation リクエストヘッダ 部 リクエストヘッダのメッセージフォーマットを 表 を 示 す 表 リスエストヘッダのメッセージフォーマット 項 番 要 素 設 定 内 容 種 別 必 須 設 定 例 1. Host ( 基 地 局 位 置 情 報 提 供 サーバのホスト 名 ) 固 定 api.spmode.ne.jp URI 中 のホスト 名 2. Content-Length (ボディ 部 のサイズ) 可 変 4096 Byte 指 定 指 定 範 囲 :0~ Content-Type application/xml; charset=utf-8 固 定 - 凡 例 必 須 : 全 ての 要 求 で 付 与 : 要 求 により 付 与 種 別 固 定 : 固 定 値 のみ 可 変 : 可 変 な 値 Page 7

8 リクエストボディ 部 リクエストボディはXML 形 式 で 記 述 する XMLのメッセージフォーマットについては 表 XML 設 定 内 容 を 参 照 すること リクエストボディのメッセージフォーマット 位 置 情 報 利 用 サービスからの 要 求 でリクエストボディ 部 に 設 定 する XML の 記 述 規 則 を 以 下 に 示 す リクエストボディ 部 の1 行 目 は XML 宣 言 とする 記 載 内 容 は 以 下 の 通 りとする <?xml version="1.0" encoding="utf-8"?> 各 要 素 タグは < 要 素 タグ> 値 ( 設 定 内 容 )</ 要 素 タグ> の 形 式 とする 要 素 タグの 設 定 内 容 が 空 要 素 の 場 合 { < 要 素 タグ></ 要 素 タグ>, < 要 素 タグ/> }の 記 述 形 式 を 許 容 する ルート 要 素 タグ(DDF 要 素 )にXMLスキーマのバージョン 番 号 属 性 (ver 属 性 )を 定 義 する XMLスキーマ のバージョン 番 号 属 性 (ver 属 性 ) 以 外 が 定 義 された 場 合 XML 構 文 エラーとなりHTTPステータスコード =200/レスポンスコード=5000を 返 却 する またルート 要 素 タグ(DDF 要 素 ) 以 外 の 要 素 タグの 属 性 は 処 理 対 象 とせずに 処 理 を 継 続 する XML はインデントされていなくても 解 釈 可 能 とする またインデントで 使 用 可 能 な 文 字 は 半 角 スペース Tab 改 行 のみとする XMLのコメント <!--コメント 内 容 --> を 許 容 しない XMLのコメントが 存 在 した 場 合 にはHTTPステータスコード=200/レスポンスコード=5000 を 返 却 する CDATAセクション <![CDATA[ 文 字 列 ]]> を 許 容 しない CDATA セクションが 存 在 した 場 合 には HTTP ステータスコード=200/レスポンスコード=5000 を 返 却 する リクエストボディ 部 の 要 素 タグに 表 に 記 されている 要 素 タグ 以 外 が 設 定 されている 場 合 には HTTPステータスコード=200/レスポンスコード=5000を 返 却 する リクエストボディ 部 に BOM(Byte Order Mark)が 付 与 されてきた 場 合 には 無 視 する 要 素 値 の 左 右 の 半 角 スペース Tab 改 行 は 除 去 する その 他 記 述 規 則 は 位 置 情 報 クエリパラメタのXMLスキーマにて 規 定 する XML の 各 要 素 への 設 定 内 容 は 以 下 の 通 り 表 XML 設 定 内 容 項 タグ 名 設 定 内 容 必 須 文 字 種 別 文 字 列 長 設 定 例 番 要 素 1. DDF 要 素 ルート 要 素 以 下 の 子 要 素 から 構 成 される RequestInfo 要 素 以 下 の 属 性 を 持 つ ver 属 性 2. ver 属 性 API のバージョン 番 号 半 角 数 字 記 号 最 大 8Byte 1.0 及 び. 小 数 点 3. RequestInfo 要 素 検 索 要 求 の 情 報 以 下 の 子 要 素 から 構 成 される RequestParam 要 素 4. RequestParam 要 素 要 求 パラメータのデータ 群 以 下 の 子 要 素 から 構 成 される APIkey 要 素 OptionProperty 要 素 Page 8

9 項 タグ 名 設 定 内 容 必 須 文 字 種 別 文 字 列 長 設 定 例 番 要 素 5. APIKey 要 素 位 置 情 報 利 用 サービスの API キー (ID) API キー2 以 下 の 子 要 素 から 構 成 される APIKey1_ID 要 素 APIKey2 要 素 6. APIKey1_ID 要 素 API キー1(ID) 非 公 開 非 公 開 非 公 開 7. APIKey2 要 素 API キー2 非 公 開 非 公 開 非 公 開 8. OptionProperty 要 位 置 情 報 のその 他 付 加 情 報 素 以 下 のオプション 要 素 から 構 成 される AreaName 要 素 AreaCode 要 素 Adr 要 素 AdrCode 要 素 PostCode 要 素 取 得 要 求 は 本 要 素 の 有 無 又 は 子 要 素 の 有 無 によって 判 定 本 要 素 無 : 全 情 報 の 取 得 要 求 無 し 本 要 素 有 : 子 要 素 の 有 無 により 取 得 要 求 を 判 定 9. AreaName 要 素 取 得 位 置 に 対 するエリア 名 本 要 素 有 : 取 得 要 求 有 り 1 要 素 の 内 容 は 空 要 素 の 内 容 は 空 要 素 の 内 容 は 空 本 要 素 無 : 取 得 要 求 無 し 10. AreaCode 要 素 取 得 位 置 に 対 するエリアコード 本 要 素 有 : 取 得 要 求 有 り 1 要 素 の 内 容 は 空 要 素 の 内 容 は 空 要 素 の 内 容 は 空 本 要 素 無 : 取 得 要 求 無 し 11. Adr 要 素 取 得 位 置 に 対 する 住 所 本 要 素 有 : 取 得 要 求 有 り 1 要 素 の 内 容 は 空 要 素 の 内 容 は 空 要 素 の 内 容 は 空 本 要 素 無 : 取 得 要 求 無 し 12. AdrCode 要 素 取 得 位 置 に 対 する 住 所 コード 本 要 素 有 : 取 得 要 求 有 り 1 要 素 の 内 容 は 空 要 素 の 内 容 は 空 要 素 の 内 容 は 空 本 要 素 無 : 取 得 要 求 無 し 13. PostCode 要 素 取 得 位 置 に 対 する 郵 便 番 号 本 要 素 有 : 取 得 要 求 有 り 本 要 素 無 : 取 得 要 求 無 し 1 要 素 の 内 容 は 空 要 素 の 内 容 は 空 要 素 の 内 容 は 空 凡 例 必 須 : 全 ての 要 求 で 付 与 : 要 求 により 付 与 1: 要 素 の 内 容 は 空 とし 該 当 要 素 の 存 在 有 無 によりパラメータ 有 無 の 判 定 を 行 う 要 素 の 内 容 が 存 在 しても 無 視 する 例 ) <AreaName></AreaName>(<AreaName/>の 記 述 も 許 容 ) Page 9

10 ( 参 考 ) 位 置 情 報 クエリパラメタのXMLスキーマ HTTP リクエストにおいて リクエストボディ 部 に 用 いる XML のスキーマは 以 下 の 通 り <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" elementformdefault="qualified"> <xs:element name="ddf"> <xs:complextype> <xs:all> <xs:element ref="requestinfo" /> </xs:all> <xs:attribute name="ver" type="xs:token" use="required" /> </xs:complextype> </xs:element> <xs:element name="requestinfo"> <xs:complextype> <xs:all> <xs:element ref="requestparam" /> </xs:all> </xs:complextype> </xs:element> <xs:element name="requestparam" > <xs:complextype> <xs:all> <xs:element ref="apikey" /> <xs:element ref="optionproperty" /> </xs:all> </xs:complextype> </xs:element> <xs:element name="apikey"> <xs:complextype> <xs:all> <xs:element name="apikey1_id" type="xs:token" minoccurs="1" maxoccurs="1" /> <xs:element name="apikey2" type="xs:token" minoccurs="1" maxoccurs="1" /> </xs:all> </xs:complextype> </xs:element> <xs:element name="optionproperty"> <xs:complextype> <xs:all> <xs:element name="areacode" type="xs:token" minoccurs="0" maxoccurs="1" /> <xs:element name="areaname" type="xs:token" minoccurs="0" maxoccurs="1" /> <xs:element name="adr" type="xs:token" minoccurs="0" maxoccurs="1" /> <xs:element name="adrcode" type="xs:token" minoccurs="0" maxoccurs="1" /> <xs:element name="postcode" type="xs:token" minoccurs="0" maxoccurs="1" /> </xs:all> </xs:complextype> </xs:element> </xs:schema> 図 XML スキーマ Page 10

11 リクエストライン リクエストヘッダ リクエストボディに 関 する 入 力 チェック 仕 様 本 人 位 置 情 報 取 得 APIにおけるHTTPリクエストのチェックの 前 提 条 件 を 表 に 記 す 表 本 人 位 置 情 報 取 得 API での HTTP リクエストチェックの 前 提 条 件 項 番 チェック 内 容 条 件 1. 空 白 文 字 <SP> は 1Byte のスペース 以 外 に 2Byte 以 上 の 連 続 したスペース およびタブも 許 容 し 混 在 も 可 能 とする 2. 改 行 <CRLF> は CR+LF 以 外 に LF のみも 許 容 する 3. リクエスト URI については 英 字 大 / 小 文 字 を 区 別 する 4. ヘッダ 名 は 大 文 字 小 文 字 を 区 別 しない 5. ヘッダの 値 については 英 字 大 / 小 文 字 を 区 別 する 6. 想 定 外 ヘッダがあった 場 合 はチェックを 行 わず 無 視 する Page 11

12 3.1.2 HTTPレスポンス HTTP レスポンスの 構 造 とレスポンス 例 を 以 下 に 示 す ステータスライン レスポンスヘッダ 部 レスポンスヘッダ 部 の 終 了 レスポンスボディ 部 HTTP バージョン <SP> ステータスコード <SP> リーズンフレーズ<CRLF> ヘッダ 名 : <SP> ヘッダ 設 定 値 <CRLF> ヘッダ 名 : <SP> ヘッダ 設 定 値 <CRLF> : ヘッダ 名 : <SP> ヘッダ 設 定 値 <CRLF> <CRLF> 位 置 情 報 (XML 形 式 ) 図 HTTP レスポンス 構 造 文 字 コード 改 行 コードについて HTTPレスポンスで 許 容 する 文 字 コードを 表 に 示 す 表 許 容 する 文 字 コード 改 行 コード(HTTP レスポンス) 項 番 箇 所 文 字 コード 改 行 コード 備 考 1. レスポンスボディ 部 以 外 US-ASCII CR+LF - 2. レスポンスボディ 部 (XML 形 式 ) UTF-8 CR+LF XML は BOM(Byte Order Mark)なしとする ステータスライン ステータスラインのメッセージフォーマットを 表 に 示 す 表 ステータスラインのメッセージフォーマット 項 番 要 素 設 定 内 容 種 別 必 須 設 定 例 1. HTTP バージョン HTTP/1.1 固 定 - 2. ステータスコード ( 結 果 コード) 可 変 処 理 結 果 コード を 参 照 3. リーズンフレーズ ( 結 果 の 説 明 句 ) 可 変 OK Page 12

13 レスポンスヘッダ 部 レスポンスヘッダのメッセージフォーマットを 表 に 示 す 表 レスポンスヘッダのメッセージフォーマット 項 要 素 設 定 内 容 種 別 必 須 設 定 例 番 1. Connection close 固 定 1-2. Date HTTP レスポンスの 生 成 日 付 可 変 Thu, 21 Dec :23:47 GMT GMT 形 式 で 設 定 2 3. Content-Length Byte 指 定 可 変 1234 指 定 範 囲 :0~ Content-Type application/xml; 固 定 - charset=utf-8 3 凡 例 必 須 : 全 ての 応 答 で 付 与 : 応 答 により 付 与 種 別 固 定 : 固 定 値 のみ 可 変 : 可 変 な 値 1 本 人 位 置 情 報 取 得 API は1リクエスト レスポンスを 想 定 しており HTTP レスポンスに 必 ず Connection: close を 付 与 して 返 し 位 置 情 報 提 供 サーバからコネクションを 切 断 するものとする 2 フォーマット 例 ) Date:_Thu,_21_Dec_2010_12:23:47_GMT ( _ は 空 白 ) 3 HTTP エラーステータスを 返 却 した 場 合 には 本 要 素 は 返 却 されない Page 13

14 レスポンスボディ 部 レスポンスボディはXML 形 式 で 記 述 する XMLのメッセージフォーマットについては 表 を 参 照 すること レスポンスボディのメッセージフォーマット 基 地 局 位 置 情 報 利 用 サービスからのレスポンスにおける XML の 各 要 素 への 設 定 内 容 は 以 下 の 通 り レスポンスボディ 部 の1 行 目 は XML 宣 言 とする 各 要 素 タグは < 要 素 タグ> 値 ( 設 定 内 容 )</ 要 素 タグ> の 形 式 とする 要 素 タグの 設 定 内 容 が 空 要 素 の 場 合 には 要 素 自 体 を 記 述 しない レスポンス XML の 要 素 値 はすべてサニタイジング 処 理 をされて 返 却 される サニタイジングの 内 容 は 以 下 のとおり 表 サニタイジング 処 理 対 象 文 字 サニタイジング 前 文 字 列 サニタイジング 後 文 字 列 & & < < > > " " ' &#39; 表 XML 設 定 内 容 項 タグ 名 設 定 内 容 必 須 文 字 種 別 文 字 列 長 設 定 例 番 要 素 1. ResultInfo 要 素 検 索 結 果 の 情 報 以 下 の 要 素 から 構 成 される TotalCount 要 素 ResultCode 要 素 Error 要 素 2. TotalCount 要 素 検 索 結 果 (Feature 要 素 )の 全 件 数 半 角 数 字 最 大 3Byte 1 値 0: 位 置 情 報 無 し 値 1 以 上 : 1 件 以 上 の 位 置 情 報 有 り (0~255) 3. ResultCode 要 素 レスポンスコード 半 角 数 字 4Byte( 固 定 ) 処 理 結 果 コード を 参 照 4. Error 要 素 エラー 発 生 時 のみ 存 在 する 要 素 以 下 の 要 素 から 構 成 される 1 Message 要 素 5. Message 要 素 テキストメッセージ 全 半 角 文 字 最 大 600Byte 1 6. Feature 要 素 検 索 結 果 1 件 分 のデータ 群 位 置 情 報 の 検 索 に 失 敗 した 場 合 は 本 要 素 は 追 加 しない 以 下 の 要 素 から 構 成 される Geometry 要 素 OptionProperty 要 素 Page 14

15 項 番 タグ 名 設 定 内 容 必 須 要 素 7. Geometry 要 素 緯 度 経 度 測 位 時 刻 の 必 須 項 目 からな る 位 置 情 報 4 以 下 の 要 素 から 構 成 される Lat 要 素 Lon 要 素 Time 要 素 8. Lat 要 素 緯 度 ( 北 緯 南 緯 含 む)( 世 界 測 地 系 :WGS84) 4 形 式 :XYYY.ZZZZZ( 度 数 表 記 ) ( 文 字 1 桁 + 整 数 部 3 桁 (0 パディング)+ 小 数 点 1 桁 + 少 数 部 5 桁 (0 パディング) 文 字 1 桁 は N( 北 緯 ) S( 南 緯 )の 何 れか 数 値 部 分 の 範 囲 : ~ 文 字 種 別 文 字 列 長 設 定 例 半 角 英 数 字 記 号 ( i 10Byte( 固 定 ) N ii) i 使 用 可 能 な 半 角 英 字 ( 大 文 字 の N S) ii 使 用 可 能 な 記 号 (. ( 小 数 点 )) 例 :N Lon 要 素 経 度 ( 東 経 西 経 含 む)( 世 界 測 地 系 半 角 英 数 字 記 号 ( i 10Byte( 固 定 ) E (WGS84)) 4 ii) i 使 用 可 能 な 半 角 英 形 式 :XYYY.ZZZZZ( 度 数 表 記 ) 字 ( 大 文 字 の E W) ( 文 字 1 桁 + 整 数 部 3 桁 (0 パディング)+ ii 使 用 可 能 な 記 号 小 数 点 1 桁 + 少 数 部 5 桁 (0 パディング) (. ( 小 数 点 )) 文 字 1 桁 は E( 東 経 ) W( 西 経 )の 何 れ か 数 値 部 分 の 範 囲 : ~ 例 :E Time 要 素 測 位 時 刻 (タイムゾーンを 含 む) 半 角 英 数 字 記 号 ( i 25Byte( 固 定 ) T12: 年 - 月 - 日 T 時 : 分 : 秒 +タイムゾーンの 形 4 ii) 23:45+09:00 式 i 使 用 可 能 な 半 角 英 T は 日 付 と 時 刻 の 区 切 りを 示 す 字 ( 大 文 字 の T) (YYYY-MM-DDThh:mm:ss±hh:mm) ii 使 用 可 能 な 記 号 ( 現 時 点 では 日 本 国 内 でのみ 取 得 する ( : + - ) ため タイムゾーンは 必 ず+09:00 となる) 例 : T23:59:59+09:00 Page 15

16 項 番 タグ 名 設 定 内 容 必 須 要 素 11. OptionProperty 要 位 置 情 報 のその 他 付 加 情 報 素 以 下 のオプション 要 素 から 構 成 される 2 AreaName 要 素 4 AreaCode 要 素 Adr 要 素 AdrCode 要 素 PostCode 要 素 12. AreaName 要 素 取 得 位 置 に 対 するエリア 名 3 i エリア 仕 様 と 同 等 AreaCode 要 素 取 得 位 置 に 対 するエリアコード 3 i エリア 仕 様 と 同 等 Adr 要 素 取 得 位 置 に 対 する 住 所 3 都 道 府 県 名 称 市 区 町 村 名 称 4 大 字 名 称 字 丁 目 名 称 を 結 合 した 文 字 列 文 字 種 別 文 字 列 長 設 定 例 全 半 角 文 字 最 大 48Byte 千 代 田 区 半 角 数 字 5Byte( 固 定 ) 全 半 角 文 字 最 大 285Byte 東 京 都 千 代 田 区 千 代 田 例 ) 東 京 都 墨 田 区 横 網 1 丁 目 15. AdrCode 要 素 取 得 位 置 に 対 する 住 所 コード 半 角 英 数 字 2Byte( 最 小 ) 国 土 地 理 協 会 が 管 理 するコード 4 5Byte 8Byte 住 所 を 一 意 に 識 別 するコード 都 道 府 11Byte( 最 大 ) 県 コード(2)+ 市 区 町 村 コード(3)+ 大 字 通 称 コード(3)+ 字 丁 目 コード(3) を 合 わせたコード 16. PostCode 要 素 取 得 位 置 に 対 する 郵 便 番 号 半 角 数 字 7Byte( 固 定 ) Page 16

17 凡 例 必 須 : 必 ず 値 を 返 却 : 条 件 により 値 を 返 却 1 ResultCode が 2001 以 上 のときに 返 却 される 2 OptionProperty の 子 要 素 がいずれか 一 つでも 存 在 する 場 合 に 返 却 される 3 OptionPropertyの 子 要 素 (オプション 要 素 )の 値 がすべて 表 オプション 要 素 の 返 却 値 の 項 番 1~3 に 該 当 する 場 合 ResultCodeは 2000 で 返 却 される OptionPropertyの 子 要 素 (オプション 要 素 )のAreaName 要 素 AreaCode 要 素 の 値 のうち いずれか1つでも 表 オプシ ョン 要 素 の 返 却 値 の 項 番 4 に 該 当 する 場 合 ResultCodeは 5001 で 返 却 される AreaName 要 素 AreaCode 要 素 の 値 は 表 オプション 要 素 の 返 却 値 の 項 番 1~3 に 該 当 するが Adr 要 素 AdrCode 要 素 PostCode 要 素 の 値 のうち いずれか1つでも 表 オプション 要 素 の 返 却 値 の 項 番 4 に 該 当 する 場 合 ResultCodeは 2001 で 返 却 される 4 ResultCode が 3000 以 上 のときに 返 却 されない また オプション 要 素 の 返 却 値 に 関 して リクエスト XML における 該 当 要 素 の 取 得 要 求 状 況 との 対 応 は 以 下 のとおり 表 オプション 要 素 の 返 却 値 項 返 却 値 リクエスト XML における 状 況 番 該 当 要 素 の 取 得 要 求 1. 正 しい 値 が 返 却 される*1 あり 結 果 が 正 しく 返 却 された 場 合 2. 要 素 タグがない なし - 3. あり 値 は 取 得 できたが 空 であった 場 合 *2 4. あり 基 地 局 位 置 情 報 提 供 サーバのエラーで 値 が 取 得 できなかった 場 合 *1 Adr 要 素 においては 返 却 値 が 丸 められている 場 合 がある ( 緯 度 経 度 に 対 応 する 住 所 が 複 数 存 在 した 場 合 この 場 合 共 通 する 部 分 のみ 返 却 される) 例 : 東 京 都 港 区 赤 坂 4- - 東 京 都 港 区 赤 坂 4- - の 場 合 東 京 都 港 区 赤 坂 4- までが 返 却 される *2 緯 度 経 度 に 対 応 する 当 該 要 素 の 値 がなかったときに 発 生 する Page 17

18 ( 参 考 ) 位 置 情 報 (XML 形 式 ) HTTP レスポンスにおいて レスポンスボディ 部 に 用 いる XML のスキーマは 以 下 の 通 り <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" elementformdefault="qualified"> <xs:element name="ddf"> <xs:complextype> <xs:sequence> <xs:element ref="resultinfo" /> <xs:element ref="feature" minoccurs="0" maxoccurs="255" /> </xs:sequence> </xs:complextype> </xs:element> <xs:element name="resultinfo"> <xs:complextype> <xs:all> <xs:element name="totalcount" type="xs:token" minoccurs="1" maxoccurs="1" /> <xs:element name="resultcode" type="xs:token" minoccurs="1" maxoccurs="1" /> <xs:element ref="error" minoccurs="0" maxoccurs="1" /> </xs:all> </xs:complextype> </xs:element> <xs:element name="error"> <xs:complextype> <xs:all> <xs:element name="message" type="xs:string" minoccurs="1" maxoccurs="1" /> </xs:all> </xs:complextype> </xs:element> <xs:element name="feature"> <xs:complextype> <xs:all> <xs:element ref="geometry" minoccurs="1" maxoccurs="1" /> <xs:element ref="optionproperty" minoccurs="0" maxoccurs="1" /> </xs:all> </xs:complextype> </xs:element> <xs:element name="geometry"> <xs:complextype> <xs:all> <xs:element name="lat" type="lattype" minoccurs="1" maxoccurs="1" /> <xs:element name="lon" type="lontype" minoccurs="1" maxoccurs="1" /> <xs:element name="time" type="xs:datetime" minoccurs="1" maxoccurs="1" /> </xs:all> </xs:complextype> </xs:element> ( 続 く) 図 XML スキーマ( 前 半 ) Page 18

19 ( 続 き) <xs:element name="optionproperty"> <xs:complextype> <xs:all> <xs:element name="areacode" type="xs:token" minoccurs="0" maxoccurs="1" /> <xs:element name="areaname" type="xs:token" minoccurs="0" maxoccurs="1" /> <xs:element name="adr" type="xs:token" minoccurs="0" maxoccurs="1" /> <xs:element name="adrcode" type="xs:token" minoccurs="0" maxoccurs="1" /> <xs:element name="postcode" type="xs:token" minoccurs="0" maxoccurs="1" /> </xs:all> </xs:complextype> </xs:element> <xs:simpletype name="lattype"> <xs:restriction base="xs:string"> <xs:pattern value="[ns]\d{3}\.\d{5}" /> </xs:restriction> </xs:simpletype> <xs:simpletype name="lontype"> <xs:restriction base="xs:string"> <xs:pattern value="[ew]\d{3}\.\d{5}" /> </xs:restriction> </xs:simpletype> </xs:schema> 図 XML スキーマ( 後 半 ) Page 19

20 3.1.3 処 理 結 果 コード 一 覧 HTTPステータスコード 一 覧 位 置 情 報 利 用 サービスに 返 却 される HTTP ステータスコード 一 覧 を 以 下 に 示 す 表 HTTP ステータスコード 一 覧 項 リーズンフレ ステータスコード 番 ーズ 内 容 OK HTTP リクエストライン HTTP リクエストヘッダが 正 常 な 場 合 に 返 却 される Bad Request HTTP リクエストラインもしくは HTTP リクエストヘッダに 異 常 がある 場 合 に 返 却 される レスポンスコード 一 覧 本 情 報 は HTTP ステータスが 200 OK 時 にレスポンスボディ 部 (XML 形 式 )の ResultCode 要 素 の 内 容 に 設 定 し 位 置 情 報 利 用 サービスに 返 却 される レスポンスコードのコード 体 系 を 以 下 に 示 す 表 レスポンスコード 体 系 項 番 区 分 エラー 分 類 レスポンスコード 範 囲 1. 正 常 系 番 台 2. 異 常 系 サービス 停 止 中 輻 輳 中 3000 番 台 3. 認 証 エラー 4000 番 台 4. システムエラー 5000 番 台 位 置 情 報 利 用 サービスに 返 却 されるレスポンスコード 一 覧 を 以 下 に 示 す レスポンスコードは 表 レスポンスコード 体 系 にもとづき 将 来 追 加 されることがある 表 レスポンスコード 一 覧 項 レスポンス 処 理 結 果 内 容 番 コード 正 常 終 了 緯 度 経 度 測 位 時 刻 オプション 要 素 の 位 置 情 報 検 索 に 成 功 オプション 要 素 を 返 さない 場 合 も 本 レスポンスコードを 返 却 する 要 素 タグ が 空 の 場 合 については 表 オプション 要 素 の 返 却 値 を 参 照 正 常 終 了 緯 度 経 度 測 位 時 刻 オプション 要 素 (エリア 名 エリアコード)の 位 置 情 報 検 索 に 成 功 しかし 本 人 位 置 情 報 取 得 API の 内 部 起 因 によりオプション 要 素 の 一 部 取 得 ( 住 所 住 所 コード 郵 便 番 号 1)に 失 敗 サービス 停 止 中 サービス 停 止 中 サーバ 輻 輳 中 位 置 情 報 提 供 サーバにて 利 用 制 限 発 生 API 利 用 停 止 中 指 定 キーに 対 する 位 置 情 報 提 供 が 停 止 されている 回 線 認 証 失 敗 該 当 利 用 者 が 不 明 又 は 利 用 者 のサービス 利 用 が 禁 止 されている アクセス 権 限 無 し(API キー1 指 定 されたキーが 登 録 内 容 と 一 致 しない (ID)/API キー2) Page 20

21 項 レスポンス 処 理 結 果 内 容 番 コード 該 当 サービスへの 位 置 情 報 提 利 用 者 が 該 当 サービスでの 位 置 情 報 利 用 を 許 可 していない 供 不 許 可 包 括 同 意 設 定 の 拒 否 状 態 該 当 ユーザが 基 地 局 位 置 情 報 自 体 の 利 用 を 拒 否 している テザリング 利 用 時 の 該 当 利 用 者 がテザリング 状 態 による 基 地 局 位 置 情 報 提 供 が 許 可 されてい 基 地 局 位 置 情 報 提 供 拒 否 状 ない 状 態 で テザリング 利 用 により 本 人 位 置 情 報 取 得 API にアクセスした 態 リクエスト 不 正 位 置 情 報 利 用 サービスから 送 信 された リクエストボディ 部 の 内 容 フォー マットが 異 常 12. 上 記 以 外 サーバ 内 部 エラー 本 人 位 置 情 報 取 得 API にて 内 部 エラーが 発 生 1 オプション 要 素 のうち 住 所 住 所 コード 郵 便 番 号 のいずれかのデータ 取 得 に 失 敗 した 場 合 は 本 人 位 置 情 報 取 得 API から 位 置 情 報 利 用 サービスに 住 所 住 所 コード 郵 便 番 号 すべての 位 置 情 報 が 返 却 されない 2 許 可 設 定 のための URL を 含 む Message が 返 却 される Page 21

22 3.1.4 処 理 シーケンス 例 (1) 位 置 情 報 取 得 正 常 [HTTPステータス=200/レスポンスコード=2000 番 台 ] 位 置 情 報 取 得 が 正 常 の 場 合 のシーケンスを 示 す 位 置 情 報 利 用 サービス (アプリ 等 ) 本 人 位 置 情 報 取 得 API 位 置 情 報 取 得 開 始 TCP コネクション 確 立 TLS セッション 確 立 位 置 情 報 取 得 要 求 /HTTP リクエスト(POST / HTTP/1.1) 位 置 情 報 検 索 位 置 情 報 取 得 応 答 /HTTP レスポンス(HTTP/ OK ) TCP コネクション 切 断 位 置 情 報 取 得 終 了 図 位 置 情 報 取 得 正 常 Page 22

23 (2) 認 証 エラー [HTTPステータス=200/レスポンスコード=4000 番 台 ] ユーザ 認 証 エラーの 場 合 本 人 位 置 情 報 取 得 API は 位 置 情 報 利 用 サービスに 業 務 処 理 エラーを 返 却 する HTTP レスポンスのリクエストボディ 部 (XML 形 式 )にエラー 要 因 に 応 じたエラー 情 報 (リザルトコード エラーメッセージ) を 付 与 する レスポンスコード 4002 番 の 場 合 リクエストボディ 部 のエラーメッセージ 部 (Message 要 素 タグ)にエラーメッセージ ではなく 遷 移 先 URI が 設 定 される その 場 合 ブラウザで 遷 移 先 URI にアクセスすること 遷 移 先 URIは 基 地 局 位 置 情 報 提 供 サーバ 側 で 変 更 することがあるため 加 工 せずそのまま 使 用 してアクセスすること 位 置 情 報 利 用 サービス (アプリ 等 ) 本 人 位 置 情 報 取 得 API 位 置 情 報 取 得 開 始 TCP コネクション 確 立 TLS セッション 確 立 位 置 情 報 取 得 要 求 /HTTP リクエスト(POST / HTTP/1.1) 認 証 エラー 検 出 位 置 情 報 取 得 応 答 /HTTP レスポンス(HTTP/ OK リザルトコード:エラー 対 応 コード) TCP コネクション 切 断 認 証 エラー 通 知 図 認 証 エラー Page 23

24 (3) ユーザ 操 作 による 位 置 情 報 取 得 中 断 [HTTPステータス= 未 返 却 /レスポンスコード= 未 返 却 ] ユーザが 位 置 情 報 取 得 処 理 中 に 電 源 断 等 の 中 断 処 理 を 行 った 場 合 位 置 情 報 利 用 サービスからコネクションの 切 断 が 行 われる 位 置 情 報 利 用 サービス (アプリ 等 ) 本 人 位 置 情 報 取 得 API 位 置 情 報 取 得 開 始 TCP コネクション 確 立 TLS セッション 確 立 位 置 情 報 取 得 要 求 /HTTP リクエスト(POST / HTTP/1.1) ユーサ 操 作 による 位 置 情 報 取 得 中 断 TCP コネクション 切 断 位 置 情 報 検 索 スマートフォン 間 の TCP コネクション 切 断 検 出 図 ユーザ 操 作 による 位 置 情 報 取 得 中 断 Page 24

25 (4) 基 地 局 位 置 情 報 提 供 サーバがサービス 停 止 中 輻 輳 中 [HTTPステータス=200/レスポンスコード=3000 番 台 ] 基 地 局 位 置 情 報 提 供 サーバがサービスを 停 止 輻 輳 中 などの 場 合 業 務 処 理 エラー 返 却 後 に 本 人 位 置 情 報 取 得 API からコネクションを 切 断 する 位 置 情 報 利 用 サービス (アプリ 等 ) 本 人 位 置 情 報 取 得 API 位 置 情 報 取 得 開 始 TCP コネクション 確 立 TLS セッション 確 立 位 置 情 報 取 得 要 求 /HTTP リクエスト(POST / HTTP/1.1) 位 置 情 報 取 得 応 答 /HTTP レスポンス(HTTP/ OK リザルトコード:エラー 対 応 コード) TCP コネクション 切 断 NW 位 置 情 報 提 供 サーバ が 停 止 中 輻 輳 中 などを 検 出 エラー 通 知 図 基 地 局 位 置 情 報 提 供 サーバがサービス 停 止 中 輻 輳 中 Page 25

26 (5) 本 人 位 置 情 報 取 得 APIエラー 検 出 [HTTPステータス=200/レスポンスコード=5000 番 台 ] HTTP リクエストボディ 部 の 入 力 チェックエラーや 構 文 エラー またサーバ 内 部 エラー 等 を 本 人 位 置 情 報 取 得 API が 検 出 した 場 合 システムエラー 返 却 後 に 本 人 位 置 情 報 取 得 API からコネクションを 切 断 する 位 置 情 報 利 用 サービス (アプリ 等 ) 本 人 位 置 情 報 取 得 API 位 置 情 報 取 得 開 始 TCP コネクション 確 立 TLS セッション 確 立 位 置 情 報 取 得 要 求 /HTTP リクエスト(POST / HTTP/1.1) 構 文 エラーや 内 部 エラー 等 の 検 出 位 置 情 報 取 得 応 答 /HTTP レスポンス(HTTP/ OK リザルトコード:エラー 対 応 コード) TCP コネクション 切 断 エラー 通 知 図 本 人 位 置 情 報 取 得 API エラー 検 出 Page 26

27 (6) 位 置 情 報 利 用 サービスからのHTTPリクエスト 不 正 [HTTPステータス=400/レスポンスコード= 未 返 却 ] HTTPリクエストのHTTPヘッダチェックでエラーを 検 出 した 場 合 HTTPエラーレスポンス 送 信 完 了 後 に 本 人 位 置 情 報 取 得 APIからコネクションを 切 断 する 位 置 情 報 利 用 サービス (アプリ 等 ) 本 人 位 置 情 報 取 得 API 位 置 情 報 取 得 開 始 TCP コネクション 確 立 TLS セッション 確 立 位 置 情 報 取 得 要 求 /HTTP リクエスト(POST / HTTP/1.1) HTTP ヘッダチェックで エラーを 検 出 位 置 情 報 取 得 応 答 /HTTP レスポンス(HTTP/ Bad Request ) TCP コネクション 切 断 エラー 通 知 図 位 置 情 報 利 用 サービスからの HTTP リクエスト 不 正 Page 27

28 (7) 本 人 位 置 情 報 取 得 APIエラー 検 出 (タイムアウト) [HTTPステータス= 未 返 却 /レスポンスコード= 未 返 却 ] 位 置 情 報 利 用 サービスからの HTTP リクエスト 待 ちでタイムアウトを 検 出 した 場 合 HTTP レスポンスを 応 答 せずに コネクションを 切 断 する 位 置 情 報 利 用 サービス (アプリ 等 ) 本 人 位 置 情 報 取 得 API 位 置 情 報 取 得 開 始 TCP コネクション 確 立 TLS セッション 確 立 リクエスト 待 ちのタイムアウト TCP コネクション 切 断 図 本 人 位 置 情 報 取 得 API エラー 検 出 (タイムアウト) Page 28

29 (8) 位 置 情 報 利 用 サービスからの 連 続 HTTPリクエストのリクエスト 破 棄 ( 同 一 コネクション 上 ) [HTTPステータス= 未 返 却 /レスポンスコード= 未 返 却 ] 本 人 位 置 情 報 取 得 API は 同 一 コネクションにおいて 位 置 情 報 利 用 サービスからの 要 求 処 理 中 に 次 の 要 求 を 受 けた 場 合 は 該 当 の 要 求 を 破 棄 する 位 置 情 報 利 用 サービス (アプリ 等 ) 本 人 位 置 情 報 取 得 API 位 置 情 報 取 得 開 始 TCP コネクション 確 立 TLS セッション 確 立 位 置 情 報 取 得 要 求 /HTTP リクエスト(POST / HTTP/1.1) 位 置 情 報 取 得 要 求 /HTTP リクエスト(POST / HTTP/1.1) リクエスト 破 棄 位 置 情 報 検 索 位 置 情 報 取 得 応 答 /HTTP レスポンス(HTTP/ OK ) TCP コネクション 切 断 位 置 情 報 取 得 終 了 図 位 置 情 報 利 用 サービスからの 連 続 HTTP リクエストのリクエスト 破 棄 ( 同 一 コネクション 上 ) Page 29

30 3.1.5 リクエスト 例 POST /nwlocation/getlocation HTTP/1.1 Host: api.spmode.ne.jp Content-Length: Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <DDF ver="1.0"> <RequestInfo> <RequestParam> <APIKey> <APIKey1_ID> </APIKey1_ID > <APIKey2> </APIKey2> </APIKey> <OptionProperty> <AreaCode></AreaCode> <AreaName></AreaName> <Adr></Adr> <AdrCode></AdrCode> <PostCode></PostCode> </OptionProperty> </RequestParam> </RequestInfo> </DDF> 図 リクエスト 例 Page 30

31 3.1.6 レスポンス 例 (1) 位 置 情 報 取 得 正 常 [HTTPステータス=200/レスポンスコード=2000 番 ] HTTP/ OK Date: Thu, 21 Dec :23:47 GMT Connection: close Content-Length: Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <DDF> <ResultInfo> <TotalCount>1</TotalCount> <ResultCode>2000</ResultCode> </ResultInfo> <Feature> <Geometry> <Lat>N </Lat> <Lon>E </Lon> <Time> T12:23:45+09:00</Time> </Geometry> <OptionProperty> <AreaCode>00001</AreaCode> <AreaName> 千 代 田 区 </AreaName> <Adr> 東 京 都 千 代 田 区 千 代 田 </Adr> <AdrCode> </AdrCode> <PostCode> </PostCode> </OptionProperty> </Feature> </DDF> 図 位 置 情 報 取 得 正 常 のレスポンス 例 Page 31

32 (2) 位 置 情 報 取 得 正 常 ( 位 置 情 報 の 一 部 情 報 取 得 ) [HTTPステータス=200/レスポンスコード=2001 番 ] HTTP/ OK Date: Thu, 21 Dec :23:47 GMT Connection: close Content-Length: Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <DDF> <ResultInfo> <TotalCount>1</TotalCount> <ResultCode>2001</ResultCode> <Error> <Message> 位 置 情 報 の 一 部 取 得 ( 住 所 住 所 コード 郵 便 番 号 )に 失 敗 しました </ Message> </ Error> </ResultInfo> <Feature> <Geometry> <Lat>N </Lat> <Lon>E </Lon> <Time> T12:23:45+09:00</Time> </Geometry> <OptionProperty> <AreaCode>00001</AreaCode> <AreaName> 千 代 田 区 </AreaName> </OptionProperty> </Feature> </DDF> 図 位 置 情 報 取 得 正 常 ( 位 置 情 報 の 一 部 情 報 取 得 )のレスポンス 例 Adr 要 素 が 取 得 できなかった 場 合 Page 32

33 (3) 認 証 エラー HTTPリクエスト 解 析 エラー(リクエストボディ 部 ) サービス 停 止 / 輻 輳 中 内 部 サーバエラーなど [HTTPステータス=200/レスポンスコード=3000~5999 番 ] HTTP/ OK Date: Thu, 21 Dec :23:47 GMT Connection: close Content-Length: Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <DDF> <ResultInfo> <TotalCount>0</TotalCount> <ResultCode>4000</ResultCode> <Error> <Message>このユーザでは 利 用 できません </ Message> </ Error> </ResultInfo> </DDF> 図 認 証 エラー HTTP リクエスト 解 析 エラー(リクエストボディ 部 ) サービス 停 止 / 輻 輳 中 内 部 サーバエラーなどのレスポンス 例 Page 33

34 (4) 位 置 情 報 利 用 サービスからのHTTPリクエスト 不 正 [HTTPステータス=400/レスポンスコード= 未 返 却 ] HTTP/ Bad Request Date: Thu, 21 Dec :23:47 GMT Connection: close 図 位 置 情 報 利 用 サービスからの HTTP リクエスト 不 正 の 場 合 のレスポンス 例 Page 34