Geocoder API 開発者ガイド

を含む

リソースリクエストのパラメータ

自由形式の住所 は、searchtextパラメータの値で指定された住所の一部または全部です。 住所情報は、 1 つの連続するテキスト文字列に保持されます。 番地、番地、郵便番号、市区町村名、国名などのアイテムはマークされていないため、任意の順序で表示できます。

修飾された住所 ( または構造化住所) は、複数のパラメータで指定された住所の一部または全部で、あいまいさを削除します。 この目的で使用できるパラメータは、 countrystatecountycitydistrictpostalcode、、。 streethousenumber

表 1. リソースリクエストのパラメータ
パラメーター 説明
追加データ

リクエストへの追加の入力を提供するキーと値のペア。 一覧表の詳細については、「追加のデータパラメータ」を参照してください。 キーと値は、を使用して区切り ,ます。 複数のキーと値のペアは、次のものを使用して区切ります ;

additionaldata=<Key1>,<Value1>;<Key2>,<Value2>;...

例 :

additionaldata=PreserveUnitDesignators,true;
IncludeZipAddon,true
addressattributes

応答データに要素が含まれているコンマ区切りのリスト。

一覧表 [country, state, county, city, districtsubdistrictstreethouseNumberpostalCodeaddressLines additionalData]

省略形 : [ctr, sta, cty, cit, dis, sdi, strhnrpstalnadd、]

デフォルトの応答 : を除くすべて addressLines

注 : 値の名前では、大文字と小文字が区別されます。
app_id

xs: 文字列

クライアント アプリケーションの認証に使用される 20 バイトの Base64 URL セーフエンコード文字列。

app_id すべて app_code のリクエストに AND を含める必要があります。  詳細については、『 Identity & Access Management 開発者ガイド』を参照してください。

app_code

xs: 文字列

クライアント アプリケーションの認証に使用される 20 バイトの Base64 URL セーフエンコード文字列。

app_id すべて app_code のリクエストに AND を含める必要があります。  詳細については、『 Identity & Access Management 開発者ガイド』を参照してください。

app_id

xs:string

Geocoder API で使用可能な認証オプションのいずれかで使用される、 20 バイトの Base64 URL セーフエンコード文字列。

アプリ ID/APP コードオプションを使用する場合は、すべてのリクエストに app_idapp_code を含める必要があります。 詳細については、『 Identity & Access Management 開発者ガイド』を参照してください。

app_code

xs:string

クライアント アプリケーションの認証に使用される 20 バイトの Base64 URL セーフエンコード文字列。

アプリ ID/APP コードオプションを使用する場合は、すべてのリクエストに app_idapp_code を含める必要があります。 詳細については、『 Identity & Access Management 開発者ガイド』を参照してください。

apiKey

xs:string

A 43-byte Base64 URL-safe encoded string used for the authentication of the client application. As a logged in user, you can generate it at https://here-tech.skawa.fun/projects. API Keys never expire but you can invalidate your API Keys at any time. You cannot have more than two API Keys for one app at the same time.

apiKey すべてのリクエストにを含める必要があります。 詳細については、『 Identity & Access Management 開発者ガイド』を参照してください。

BBOX

GeoBoundingBoxType も参照してください

空間フィルタのタイプ。 空間フィルタは、リクエスト内の他の属性の検索を制限します。 バウンディング ボックスは bbox 2 つの緯度と経度のペアで指定されます。 1 つ目のペアはバウンディング ボックスの左上隅を定義し、 2 つ目のペアは右下隅を設定します。 bbox 検索は現在似て mapview いますが、拡張されていません。 関連するグローバル結果も返されます。

bbox=<TopLeft.Latitude>,<TopLeft.Longitude>;
  <BottomRight.Latitude>,<BottomRight.Longitude>
例 : bbox=41.9085286,-87.6762943;41.8682739,-87.6041965
categoryids

xs: 整数

ランドマークの結果を 1 つ以上のカテゴリに限定します。 例 :
  • ハイウェイ出口 : 116
  • 空港 : 4581
  • 観光名所 : 7999
city

xs: 文字列

国ごとのマッピングが必要です。 例 :
  • アメリカ : 市区町村
  • ドイツ : ジェミニンデ

xs: 文字列、完全一致

国コード( 3 バイト、 ISO 3166-1-alpha-3 )または国名を使用して国または国のリストを指定します。 これは厳密なフィルタです。 結果は指定された国に限定されます。
注 : あいまいさを避けるために、国名のスペルではなく、 3 文字の ISO コードを使用して国を指定することをお勧めします。 名前を使用すると、スペルミスのリスクが高くなります。また、すべての国のすべての言語翻訳がサポートされているわけではありません。
国別配分

xs: 文字列、完全一致、単一の ISO 3166-1-alpha-3 国コード

指定した国の結果が優先されます。 これはソフトフィルタです。 スペルが記入された国名は、国別の表記ではサポートされていません。
  • ハードカントリーフィルタとソフトカントリーフォーカスパラメータの両方がリクエストに設定されている場合、国フィルタがフォーカスよりも優先されます。 つまり、結果は国のフィルタで指定された国に限定されます。
  • bbox mapview または、競合がある場合は、国の重点項目よりもフィルタが優先されます。

xs: 文字列

国の 2 番目の下位区分レベル。 国の管理者階層によっては、このレベルは適用されない場合があります。 例 :
  • アメリカ : 国
  • ドイツ : Kreis
地区

xs: 文字列

街の下位階に位置しています。 国の管理者階層によっては、このレベルは適用されない場合があります。 例 :
  • アメリカ : 該当なし
  • ドイツ : Ortsteil
世代

xs: 整数

gen このパラメータは、 API での下位互換性のない動作を有効または無効にします。

  • gen=0 既定の動作
  • gen=1
    • アドレスに対する逆方向のジオ コーディングリクエストで、指定した半径内に住所または番地が見つからなかった場合は、代わりにそのエリア情報が返されます。 半径 gen=010,000 メートルの結果が返されます。
    • MatchLevel 交差の一致の結果はです intersectiongen=0 では、 MatchLevel 交差の一致の対象は street です。
  • gen=2
    • gen=1 機能が含まれます。
    • 逆方向のジオコード領域の応答には DispalyPosition 、その値が領域の表示位置(領域の中心など)であることが含まれます。 gen<2 では、リクエストからポイントを DisplayPosition ミラーリングします。
    • リクエストに locationattributes=(mr, mapReference, all のいずれか ) が指定されている場合、 response 要素 MapReference にはマップバージョンが含まれます。 の gen<2MapReference は、地図のバージョンが含まれていません。
  • gen=3
    • gen=2 機能が含まれます。
    • リバースジオ コーディングアドレスの結果には、明確な表示およびナビゲーション位置が含まれます。 では gen<3、リバースジオ コーディングの結果の住所には、ナビゲーション位置と常に同じ表示位置が表示されます。 この gen=3 バグは修正されました。
    • Reverse ジオ コーディング Point Address の結果 MatchType pointAddress が表示されます。それ以外の場合 MatchType は、 interpolated です。 gen<3 アドレスを使用すると、リバースジオ コーディングの結果 MatchType interpolated が常に表示されます。
  • gen=4
    • gen=3 機能が含まれます。
    • Forward ジオ コーディングでは、郵便番号または郵便番号ごとに 1 つの番地レベルの結果が生成されます。これにより、複数の結果が互いに近接して作成されたり、地区名または郵便番号に基づいてのみ明確に区別できるように再検索されたりすることがありません。 gen<4 Forward ジオ コーディング応答では、郵便番号または郵便番号ごとに複数の結果が含まれます。
  • gen=5
    • gen=4 機能が含まれます。
    • Reverse ジオ コーディングでは、国のフィルタが適用されます。 逆の Geocoder 結果は、リクエストで指定された国に限定されます。 これはバグ修正です。 gen<5 逆の Geocoder では、国のフィルタは無視されます。 Forward Geocoder の動作は変更されません。常に国のフィルタが適用されています。
    • Reverse ジオ コーディングでは、 1 つのリンクにつき 1 つの番地一致を指定するのではなく、 1 つの番地一致へのリンクを集約しようとします。この場合、座標のみが異なります。
    • LocationType (Location の要素 ) は、結果 point だけでなく結果に固有のものです。 LocationType
      • address: の場合 MatchLevel houseNumber, street, intersection
      • area: の場合 MatchLevel country, state, county, city, district, postalCode
      • のランドマークに固有 MatchLevel landmarkです。 例 park, river, golfCourse, industrialComplex, island
      この変更は、順方向と逆方向の両方の Geocoder 結果に影響しますか。
  • gen=6
    • gen=5 機能が含まれます。
    • search エンドポイントによって検出されたランドマークは、として公開 Locationされます。 として公開される前 Place。 これにより、応答構造が簡素化され、冗長な情報がいくつか削除されます。 以下のエッフェル塔検索の応答例を参照してください。
      • placeIdlocationId 外部システムからのみ派生したものであり、外部システムへの参照ではありませんでした
      • category.categoryId locationType が、その結果に固有のに置き換えられました gen=5 ( 以前は locationType 常に "point" でした )
      • category.categorySystemId いつも「施設」だった
      • suppliers は常に空です
        表 1. 第 5 世代と第 6 世代のランドマークジオ コーディング
        search.json?
        searchtext=Eiffel+Tower
        &gen=5
        &language=en
        search.json?
        searchtext=Eiffel+Tower
        &gen=6
        &language=en
        relevance: 1,
        matchLevel: "landmark",
        matchQuality: {
           name: 1
        },
        place: {
           placeId: "801890088",
           name: "Eiffel Tower",
           category: [ {
            categoryId: "5999",
            categorySystemId: "facility"
           }],
           suppliers: [ {} ],
           locations: [ {
            locationId:
             "NT_AIzytxewh0cMjfGkhX4O.B",
            locationType:
             "historicalMonument",
            name: "Eiffel Tower",
            displayPosition: {
             latitude: 48.85824,
             longitude: 2.2945
            },
        ...
        relevance: 1,
        matchLevel: "landmark",
        matchQuality: {
           name: 1
        },
        location: {
           locationId:
            "NT_AIzytxewh0cMjfGkhX4O.B",
           locationType:
            "historicalMonument",
           name: "Eiffel Tower",
           displayPosition: {
            latitude: 48.85824,
            longitude: 2.2945
           },
        ...
      この変更は、順方向および逆方向の Geocoder 結果に影響します。
    • 管理領域を反転( Reverse Geocoder )の結果の距離は、指定した点から多角形の境界までの距離で計算されます。 したがって、指定した点が領域内にある距離は負の値になります。 これはランドマークの結果と整合しています。 で gen<6は、管理エリアの結果の距離は、指定したポイントからエリアの中心までの距離で計算されます。
  • gen=7
    • gen=6 機能が含まれます。
    • リバース Geocoder mode=retrieveAreas リクエストの半径値は無視されなくなりました。 近接値が 0 より大きい場合、半径内にある領域が応答に含まれます。 例 : ベルリン近郊の都市、ポツダムの座標に関する地域情報をリクエストします。

      mode=retrieveAreas&prox=52.39702,13.04811,10000&level=city&gen=7

      ポツダムの結果に加えて、ベルリンをはじめ、指定した場所から 10,000 メートル以内にある近隣の町についての結果も含まれています。
  • gen=8
    • gen=7 機能が含まれます。
    • 番地が遠くに一致するのではなく、参照地点に近い番地の一致 ( リンク上のポイント ) が返されます。

      これは、リバースジオ コーディングに適用 mode=retrieveAddressesされます。 番地が指定された範囲外にある場合、サービスはその番地にスナップしません。 その代わりに、番地レベルの結果が返されます。 で gen<8は、最も近いリンク位置が指定された半径内 にあり 、番地の位置がそのポイントから 150 メートル以内にない場合、サービスは番地の位置にスナップします。

  • gen=9 (recommended)
    • gen=8 機能が含まれます。
    • Location.AdminInfo.TimeZoneOffsetLocation.AdminInfo.TimeZone.Offset 他のタイムゾーン情報と一緒にに移動されました。 詳細については、タイムゾーンを参照してください。

      表 2. タイムゾーンオフセットは、第 9 世代から第 8 世代に変更されます
      &gen=8
      &locationattributes=tz
      &gen=9
      &locationattributes=tz
      Location.AdminInfo.TimeZoneOffset
      Location.AdminInfo.LocalTime
      Location.AdminInfo.Currency
      Location.AdminInfo.DrivingSide
      Location.AdminInfo.SystemOfMeasure
      Location.AdminInfo.LocalTime
      Location.AdminInfo.Currency
      Location.AdminInfo.DrivingSide
      Location.AdminInfo.SystemOfMeasure
      Location.AdminInfo.TimeZone.Id
      Location.AdminInfo.TimeZone.Offset
      Location.AdminInfo.TimeZone.RawOffset
      Location.AdminInfo.TimeZone.NameShort
      Location.AdminInfo.TimeZone.NameLong
      Location.AdminInfo.TimeZone.NameDstShort
      Location.AdminInfo.TimeZone.NameDstLong
      Location.AdminInfo.TimeZone.InDaylightTime
      Location.AdminInfo.TimeZone.DstSavings
housenumber

xs: 文字列、完全一致

番地または自宅名。

ID

xs: 整数

複数のリバースジオ コーディング結果で使用されるアイテム識別子。あるリクエストを別のリクエストと区別します。

jsonattributes

xs: 整数

1 に設定すると、各 JSON 応答属性名の最初の文字が小文字に設定されます。 デフォルト値は 0 です。

jsoncallback

xs: 文字列

JSON 応答のラップに使用するユーザー定義関数の名前を指定します。

言語

LanguageCodeType

結果の住所要素の優先言語。 Geocoder は、希望する言語を使用せずに、現地の人々が理解できるように、公式の国の言語または地域の主要言語で結果を返します。 言語コードは、 RFC 4647 標準に準拠して提供する必要があります。 パラメーター(言語)の複数形もサポートされています。 ただし、リスト内の最後に指定した言語のみが使用されます。 この時点では、上記の言語設定はすべて無視されます。

レベル

xs: 文字列

検索結果のターゲットの一致レベル。 [country, state, county, city, district, postalCode, , ] をクリックします 以上との組み合わせでのみ有効 gen=2 です。
locationattributes

応答データに要素が含まれているコンマ区切りのリスト。

一覧表 [address, mapReference, mapView, addressDetails, streetDetailsadditionalDataadminIdslinkInfoadminInfotimeZone, addressNamesBilingual related.nearByAddress]

省略形 : [ar, mr, mv, dt, sd, ad, ailiintznbrn,]

adminIds このスイッチは、順方向ジオ コーディングでのみ使用できます。

タイムゾーン情報を取得するには、次 adminInfo のようにパラメータを追加する必要があります。 locationattributes=adminInfo,timeZone

逆方向のジオ コーディングの結果では、 locationattributes=none をオフにしない限り、 adminIds は常に存在します。 locationattributes=-adminIds は、逆方向のジオ コーディングの結果には影響を与えません。

related.nearByAddress このスイッチは trackPosition 、リバースジオ コーディングモードでのみ使用できます。

リバースジオ コーディング応答のデフォルト : addressmapViewadditionalDatamapReferenceadminIds

転送ジオ コーディング応答のデフォルト : addressmapViewadditionalData

mapReference リンク PVID 、番地、管理エリアの PVID が応答データに含まれています。 で adminIdsは、管理エリアの PVID のみが存在します。

注 : 値の名前では、大文字と小文字が区別されます。
位置情報 ID

xs: 文字列、完全一致

物理的な場所を一意に識別するキー。 ジオコード応答の各レコードには、ロケーション ID が含まれています。 ID を使用して、正確に同じ場所の情報を取得します。 たとえば、「 1 Market Street, 94105 San Francisco 」のロケーション ID は NT_NVpegjQLOBK8ORYk3jV7A_xA です。

マップビュー

GeoBoundingBoxType を参照してください

アプリのビューポイントの地図座標を指定します。 は mapview 2 つの緯度と経度のペアで指定されます。最初のペアはバウンディング ボックスの左上隅を定義し、 2 番目のペアは右下隅を設定します。 設定されたマップ ビュー内の一致と拡張領域の一致が最も高いランク付けされます。 関連するグローバル結果も返されます。

mapview=<TopLeft.Latitude>,<TopLeft.Longitude>;
  <BottomRight.Latitude>,<BottomRight.Longitude>
例 : mapview=41.9085286,-87.6762943;41.8682739,-87.6041965
MaxResults

xs: 整数

応答構造内の最大アイテム数を定義し、各応答ページに含まれる結果の数を制限します。 定義されている最大数を超える結果が得られると、別々の追加ページに返されます。 各応答構造 ( ページ ) には、次のページへのハンドルが含まれています。 たとえば、 maxresults=5 は、 1 つの応答ページにつき最大 5 つの結果を生成します。 合計で 8 つの結果がある場合、最初のページには 5 つの結果が含まれ、さらに結果が表示された 2 ページ目があることを示します。

"metaInfo: {
  timestamp: 2012-05-10T15:10:06.227+0000
  nextPageInformation: 2
}"
検索結果はわずかです

xs: 整数

minResults 結果が見つかるまで、サービスが指定した半径を無視することを示します。 デフォルトは 0 です。 Reverse ジオコード mode=retrieveAreas およびでサポート mode=retrieveAddressesされています。

モード
5 つの値のいずれか :
  • retrieveAddresses - 最も近い番地を検索します
  • retrieveAreas - リクエストで指定された位置の管理エリア情報を取得します
  • retrieveLandmarks - リクエストに応じて、公園や湖などのランドマークを検索できます
  • retrieveAll - 通り、行政エリア、ランドマークを検索します。 このモードでは、 3 つの異なるモードの結果が 1 つのコールに集約されます
  • trackPosition - 位置と方位に基づいて、番地と番地の情報を取得します
名前

xs: 文字列

ランドマークの名前。 ランドマークの名前は、内で指定することもでき searchtextます。 searchtext ではなく name を使用して、住所などのあいまいさを回避します。

ハイウェイの出口もランドマーク的な存在となっていますが、ハイウェイ名と出口名で構成されています。 パラメーターには出口名のみを指定する name 必要があります。 ハイウェイ A67 の出口 4 を検索するには、以下の 2 つの方法があります。

  • search.xml?searchtext=A67&name=4
  • search.xml?searchtext=A67+4
ページ情報

xs: 文字列

応答が複数のページに分割されたときに返されるページを識別するキー。 maxresults 元のリクエストでが指定されており、リクエストの応答に次のページがあることが示されている場合にのみ関連します。例 :

"metaInfo: {
  timestamp: 2012-05-10T15:10:06.227+0000
  nextPageInformation: 2
}"
政治家の見方

xS: 文字列 (3 バイト、 ISO 3166-1-alpha-3)

政治的見解を指定します。 利用可能な地域は、この国の観点から見ることができます。 このパラメータが指定されていない場合は、中立的な国際ビューが利用可能になります。このビューでは、地域に未解決のクレームがある可能性があります。

サポートされているすべてのビューの一覧については、付録の「 Political View 」を参照してください。

Geocoder をサポートしていないすべての政治的ビューについて、はデフォルトのビューに戻ります。 たとえば、 politicalview=USA または politicalview=FRA は、どのような方法でも応答に影響を与えません。

位置

pos=lat,lon,bearing

緯度、経度、および方位を表す。 方位は、真北を起点にコンパスの時計回りにアセットが向かっている方向を度単位で表します。北は 0 度、東は 90 度、南は 180 度、西は 270 度です。

郵便番号

xs: 文字列、完全一致

国の政府によって定義された郵便番号。

Prox です

GeoProximityType 。 GeoProximityType も参照してください

prox=lat,lon,radius

SpatialFilter のタイプ。 空間フィルタは、リクエストの他の属性の検索を制限します。 近傍( Proximity )では、緯度、経度、および半径を使用して検索する円をメートル単位で指定します。 検索方法はに似 mapviewています。 セットエリア内の一致件数が高い順にランク付けされます。 関連するグローバル結果も返されます。

Prox です

GeoProximityType 。 GeoProximityType も参照してください

prox=lat,lon,radius

SpatialFilter のタイプ。 空間フィルタは、リクエストの他の属性の検索を制限します。 近傍( Proximity )では、緯度、経度、および半径を使用して検索する円をメートル単位で指定します。

リクエスト ID

xs: 文字列

リクエスト処理のトレースに使用できる任意の URL エンコード値。 requestid を指定すると、応答構造体の MetaInfo 要素内でその要素が繰り返されます。

responseattributes

応答データに要素が含まれているコンマ区切りのリスト。

列挙 [performedSearch, matchQuality, matchType, matchCode parsedRequest]

省略形 : [ps, mq, mt, mc, pr]

デフォルトの応答 : matchQuality, matchType

メモ : 値の名前では、大文字と小文字が区別されます。
テキストを検索します

xs: 文字列

searchtext 住所要素を含む自由形式のテキストが含まれています。 searchtext パラメーターは単独で指定することも、他のパラメーターを使用して指定して検索範囲を絞り込むこともできます。 たとえば、検索テキストフィールドで、自由形式のアドレスとともに state または country パラメータを指定できます。
注 : 検索テキストに住所以外の関連要素を含めないでください。これにより、結果の関連性が向上します。 検索テキストの住所以外の要素が結果の品質に影響を与える可能性があります。
sortby

xs: 文字列

距離 ( デフォルト ) 、母集団の数、またはサイズ ( 近似領域サイズ ) で結果を並べ替えます。 [distance, population size] のいずれかです。

現在、 Reverse ジオコードでのみサポート mode=retrieveAreasされています。 エンティティに人口のカウントが使用できない場合、サービスはエリアサイズで並べ替えられるようにフォールバックします。

都道府県

xs: 文字列、完全一致

国の下の最初の下位区分レベル。 state 完全表記または省略表記を使用して指定します。 たとえば、国ごとのマッピングが必要です
  • 米国 : 都道府県
  • ドイツ : ブンデューンランド
street

xs: 文字列

通りの名前には、スイート、アパート、および階数の情報を含めることができます。 道路の交差点を検索する場合、次の 2 つの形式がサポートされています。
  • 次の 2 つのパラメータ street0 street1 を使用します。例 :
    street0=McAllister+St&street1=Market+St
  • または、定義済みの区切り文字のいずれかを使用して、 2 つの道路を連結します(「 and 」、「 at 」、「 & 」、または「 @ 」)。例:
    street=McAllister+St+@+Market+St
strictlanguagemode

xs: boolean

  • True - language パラメータで指定された最初の言語で値が使用できる場合、属性値は AddressPlaceLocation 、および Category の各要素で直接設定されます。 代替言語の値が AlternativeValues 要素に返されます。
  • False - language パラメーターで指定された言語の優先度に基づいて、 AddressPlaceLocation および Category の各要素で直接使用できる最適な属性値が返されます。 代替案は返されません。
トークン

xs: 文字列

一般的に 24 バイトの URL エンコードされた Base64 文字列 ( 保証されていません ) 。 は token 、ユーザーに基づいて生成 app_id され、アプリケーションの登録プロセス後に受信されます。

パラメータ token は廃止されました app_code 。代わりにを使用してください