Reverse Geocode POST リクエスト

POSTリクエストでは、単一の入力座標または座標リストをバッチ処理用に送信することができます。国コード、座標参照系、マッチングの優先設定を、オプションで指定できます。候補のリストを、関連する住所データとマッチング情報とともに含むレスポンスが返されます。POSTリクエストの優先設定オプションは、使用可能なオプションの完全集合です。

ベース URI

http://<server>:<port>/rest/GlobalGeocode/reverseGeocode.[content type]

説明:

.[content type] は、指定されたコンテンツ タイプがデフォルトで使用されることを示します。これはオプションです。
json
JSONコンテンツ ネゴシエーションによって置き換えられない限り、デフォルトのコンテンツ タイプは HTTP です
xml
XMLコンテンツ ネゴシエーションによって置き換えられない限り、デフォルトのコンテンツ タイプは HTTP です

リクエスト パラメータ

POSTリクエストは、次の入力パラメータで構成されます。
  • points — リバース ジオコーディングを行う (複数の) 入力座標。必須
  • preferences — マッチング オプション。これはオプションです。
これらのオブジェクトとその要素の定義は、以下の表のとおりです。
名前 タイプ 説明
points ジオメトリ オブジェクトと国コード文字列の両方が含まれている配列オブジェクト。
country String リバース ジオコード結果を検索する国。3 文字の ISO 国コードで指定します。これはオプションです。国コードについては、国参照一覧と ISO 3166-1 国コードを参照してください。
Geometry オブジェクト。次の要素で構成されます。
coordinates Double 入力 x, y 座標。x は経度、y は緯度。例: [ -105.25175, 40.024494 ]
type String 入力座標が表す地理的エンティティのタイプ。
point
入力座標はポイント ロケーションを表します。
crs String 入力座標で使用されている座標参照系。形式は、European Petroleum Survey Group (EPSG) コードまたは SRID コードである必要があります。デフォルトはEPSG:4326です。codespace:code という形式で、座標参照系を指定します。
Preferences オブジェクト。次の要素で構成されます。
注: preferences オブジェクト内の次の要素のみが Reverse Geocode サービスに適用可能です。
注: 特定の国の preferences 要素のデフォルト値をオーバーライドするには、customPreferences オブジェクトにキー/値のペアを、ISO-3166 の 3 文字の国コード、ピリオド、キー定数の形式で指定します。例: DEU.streetOffset。
distance Double Reverse Geocode サービスにおいて、入力座標に一致するものを検索する半径を設定します。単位は、distanceUnits によって指定されます。デフォルトは 150 メートルです。最大値は 5280 フィート (1 マイル)、1609 メートルです。
distanceUnits String 検索距離の単位を指定します。次のいずれかです。
  • フィート
  • メートル - デフォルト
clientLocale String このフィールドは、複数の言語が存在する国で言語の候補の優先順位を決定するために使用されます。ロケールは、"cc_CC" という形式で指定する必要があります。ここで、cc" は言語、"CC" は ISO 3166-1 Alpha-2 コードであり、ロケールは en-US、fr_CA、fr_FR のようになります。

例えば、エジプトでは英語とアラビア語の両方がサポートされています。clientLocale フィールドは、英語優先 (en-EN) またはアラビア語優先 (ar-EG) のどちらかに設定できます。

注: ISO Alpha-2 国コードの一覧については、国参照一覧と ISO 3166-1 国コードを参照してください。
clientCoordSysName String ジオメトリの変換先の座標系を指定します。形式は、European Petroleum Survey Group (EPSG) コードまたは SRID コードである必要があります。デフォルトは EPSG:4326です。

codespace:codeという形式で、座標参照系を指定します。
streetOffset Double ストリートレベルのジオコーディングに使うストリートセグメントからのオフセット距離を指定します。距離の指定は streetOffsetUnits オプションで指定した単位で行います。デフォルト値は 7 メートルです。

オフセット距離は、ジオコードがストリートの中央に位置付けられるのを防ぐために、ストリートレベルのジオコーディングで使われます。ストリートレベルのジオコーディングを行うと、住所が位置するストリートの中心点の緯度/経度が返されますが、これを補正するのがオフセットです。住所が指し示す建物はストリートの真上に建っているわけではないので、路上のポイントに相当する住所のジオコードが返されるのは不都合です。ジオコードは、ストリートに面して建つ建物の場所を表している必要があります。例えば、50 フィートのオフセットは、ジオコードがストリートの中心から 50 フィート離れた場所を表すことを意味します。距離は、住所のストリートセグメントから垂直方向に計算されます。また、オフセットは、ストリートをはさんで向かい合う住所が同じポイントになるのを防ぐ目的にも使われます。以下に、オフセット ポイントと元のポイントとの比較図を示します。
streetOffsetUnits String ストリート オフセットの距離単位を指定します。次のいずれかです。
  • フィート
  • メートル - デフォルト
cornerOffset Double ストリートレベルでのマッチングに使うストリートの終端からのオフセットを指定します。距離の指定は cornerOffsetUnits オプションで指定した単位で行います。この値は、通りの角の住所に交差点と同じジオコードが与えられるのを防ぐために使われます。角に対するジオコード ポイントのオフセット位置を定義します。デフォルト値は 7 メートルです。

以下に、ストリートの終点とオフセット終点の比較図を示します。
cornerOffsetUnits String コーナーオフセットの距離単位を指定します。次のいずれかです。
  • フィート
  • メートル - デフォルト
customPreferences Map<String key, String value> 国固有の入力優先設定を指定します。このオブジェクトを使用して、以下の項目を指定できます。
  • preferences または returnFieldsDescriptor オブジェクト内の (複数の) 要素のデフォルト値に対する、国固有のオーバーライド。
  • 国に対するカスタム入力オプション。
特定の国のデフォルト値をオーバーライドするには、キー定数の前に ISO-3 の国コードとピリオドを付け、値を指定します。例えば、XML リクエストでは、国のデフォルト値をオーバーライドするための入力は次のようになります。
<customPreferences>
   <entry>
      <key>CAN.distance</key>
      <value>300</value>
   </entry>
</customPreferences>
国のカスタム入力オプションは、以下の国に対して提供されています。 また、カスタム ユーザ辞書と標準ジオコーディング データセットの両方をサポートしている国については、キー KEY_CUSTOM_DICTIONARY_USAGE によってカスタム優先設定を設定できます。このキーは、カスタム辞書と標準辞書の両方がジオコーディング エンジンで使用可能な場合の検索とマッチングの優先設定を定義します。このオプションは、フォワード ジオコーディングにのみ使用可能です。詳細については、標準およびカスタム辞書使用時の検索とマッチングの優先設定を参照してください。各国がカスタム ユーザ辞書をサポートしているかどうかという情報については、その国の「サポートされているジオコーディング データセット」セクションを参照してください。
ReturnsFieldsDescriptorタイプの returnFieldsDescriptor オブジェクト。候補に対して返される追加データを制御します。デフォルトでは、拡張候補情報は返されませんが、追加の情報が使用可能な場合は、以下の方法で制御できます。
注: 特定の国の returnFieldsDescriptor 要素のデフォルト値をオーバーライドするには、customPreferences オブジェクトにキー/値のペアを、ISO-3166 の 3 文字の国コード、ピリオド、キー定数の形式で指定します。例: AUS.returnAllCustomFields。
returnAllCustomFields Boolean
True
候補に対するすべてのカスタム フィールドを返します。
False
候補に対するフィールドの標準セットのみを返します。こちらがデフォルトです。
returnedCustomFieldKeys List<String> 候補の customFields 出力で返されるカスタム フィールドを表すキーのリストを指定します。例えば、“CTYST_KEY” や “DATATYPE” です。デフォルトは空です。
注: 国に対して複数のキー/値のペアを指定するには、返すカスタム フィールドの名前をスペースで区切ります。例:"USA.returnedCustomFieldKeys" : "LAT LON SHORT_CITY"。この情報を持つ候補の customFields 出力には、これらのキーを含む 3 つのカスタム フィールドがあります。
注: カスタム フィールドは国によって異なります。各国の情報については、詳細情報が記載された付録の「国固有の情報」で該当するセクションを参照してください。
returnMatchDescriptor Boolean
True
候補のどの部分が入力住所と一致したかを表す、マッチ記述子オブジェクトを返します。
False
マッチ記述子オブジェクトを返しません。こちらがデフォルトです。
returnStreetAddressFields Boolean
True
formattedStreetAddress フィールドを構成する、以下に示す個々のストリート フィールドをすべて個別に返します。
  • MAIN_ADDRESS — ストリート名の基本部分。例: “13 River Ave” の “River”
  • THOROUGHFARE_TYPE — ストリート名の前または後に付くことがある、Ave、Via、St、Rd などの大ストリートタイプ。
  • ADDRESS_ID — ソース データ内の住所に対する一意の識別子。
  • PRE_ADDRESS — 主ストリート名の前に付く冠詞などを値に含めることができます。例: “Calle de la mesa” の “de la”
  • POST_ADDRESS — 主ストリート名の後に付く語句を値に含めることができます。例: “Calle Ramon Perez de la tiedra” の "de la tiedra"
  • PRE_DIRECTIONAL — 主ストリート名の前に付く方位記号を値に含めることができます。例: “123 South Main St” の “South”
  • POST_DIRECTIONAL — 主ストリート名の後に付く方位記号を値に含めることができます。例: “123 River St SW” の “SW”
False
個々のストリート フィールドを個別に返しません。これらの値を formattedStreetAddress フィールドに入れて返します。こちらがデフォルトです。
returnUnitInformation Boolean
True
可能な場合には、単位のタイプと単位の値の情報を個別に unitType および unitValue フィールドで、また formattedStreetAddress フィールドでも返します。
False
可能な場合には、単位のタイプと単位の値の情報を formattedStreetAddress フィールドでのみ返します。こちらがデフォルトです。