メインコンテンツまでスキップ

Geocoding API

追加の開発者リソース
Geocoding v6

これは、最新バージョンの Mapbox Geocoding v6 のドキュメントです。

以前のバージョンをお探しの場合は、Geocoding v5 API のドキュメントを参照してください。

Mapbox Geocoding API は次の 2 つの機能を持ちます: フォワードジオコーディング と リバースジオコーディング:

  • フォワードジオコーディングは、ロケーションテキストを地理座標に変換し、2 Lincoln Memorial Circle SW を -77.050, 38.889 にします。
  • リバースジオコーディングは、地理座標を地点名に変換し、-77.050, 38.889 を 2 Lincoln Memorial Circle SW にします。これらのロケーション名は、個々の住所から、指定された座標を含む州および国など、特定のレベルで異なる場合があります。
v6 の新機能
  • セカンダリアドレス対応 により、フォワードジオコーディングを使用してアパートメントユニットやビジネススイートを取得でき、その親アドレスとは異なる座標を持つものも含まれます。
  • 構造化入力 により、クエリを構成要素に分けてより高い精度を達成できます。
  • スマートアドレスマッチ により、address タイプの機能に対するすべての応答で match_code オブジェクトが利用可能になり、クエリと結果の対応度を示します。
  • 改良された バッチ ジオコーディング により、1 回のリクエストで最大 1000 件の異なるタイプのクエリを送信できます。API レート制限は適用され、各クエリは 1 リクエストとしてカウントされます。
  • 拡張された 日本カバレッジ により、強力な日本の住所検索機能にアクセスできます。
Geocoding v5 からの移行
  • パーマネントジオコーディングとテンポラリージオコーディングはもはや異なるエンドポイントではなく、オプションのパラメータを介して設定されます。すべてのエンドポイントのデフォルト動作はテンポラリージオコーディングです。
  • フォワードおよびリバースジオコーディングには、それぞれ専用のエンドポイントがあります。
  • バッチジオコーディングには専用のエンドポイントがあります。
  • Geocoding v6 API は POI データを提供しなくなりました (POI 検索には Search Box API を使用してください)。
  • ストリートは機能タイプとして返され、types パラメータを使用してフィルタリングできるようになりました。
Snowflake からのジオコーディング

Snowflake ユーザーは、データウェアハウスに保存されたデータに対してバッチジオコーディング操作を実行できます。Mapbox Snowflake Native アプリは Snowflake Marketplace で入手できます。

Mapbox Geocoding API の背景情報とその動作については、ジオコーディングのしくみガイド を参照してください。

また、Mapbox Geocoding API を直接使用する代わりに、アプリケーションに統合するためにいくつかの ラッパーライブラリ のいずれかを使用することもできます。

  • Mapbox Search JS SDK の場合、Geocoding コンポーネントはリリース 1.0.0-beta.20 以降で利用可能です。
PLAYGROUND
Geocoding API プレイグラウンド

フォワード, 正方向、リバース、およびバッチジオコーディングクエリを試し、その結果を地図で確認できます。

地理的機能タイプ​

さまざまなタイプの地理的機能が Mapbox のジオコーディングで利用できます。どのタイプもトップレベルの応答、トップレベルの応答のコンテキスト、または types パラメータを使用したフィルタリングオプションとして表示される場合があります。すべての機能が世界のすべての地域で利用できるわけではなく、すべての場所で関連するわけでもありません。新しいタイプは、グローバル管理階層を正確にキャプチャするために必要に応じて追加されます。

地理的機能タイプは、最大のものから最も細かいものまでリストされています:

フィーチャータイプ説明
country一般的に認識されている国、または香港のように準国家的な行政ステータスを持ち ISO 3166-1 の国コードが割り当てられている地域。
region国内のトップレベルの行政区画機能。米国の州やカナダや中国の州など。
postcode国ごとの全国アドレッシングシステムで使用される郵便番号。
districtトップレベルの行政機能より小さいが、都市より大きい場合が多い機能。中国の県など。
place通常都市、村、自治体など。これは郵便アドレッシングで使用される機能であり、現在地コンテキストが必要なエンドユーザーアプリケーション（天気表示など）での表示に適しています。
locality郵便アドレッシングで使用される追加の行政層が存在する国、または現地の話し言葉に頻繁に記載される公式な市内区画。ブラジルやチリの市区やフランスの区など。
neighborhood地元の話し言葉でしばしば言及される口語の市内区画 locality 機能とは異なり、公式なステータスがない場合や普遍的に合意された境界がない場合が多い。
street1 つ以上の住所を持つ道路機能。
block日本の住所に予約されている特別な機能タイプ。
address個々の住宅またはビジネスの住所。
secondary_address親住所内のサブユニット、スイート、またはロット。現在は米国でのみ利用可能。

ジオコーディング結果の保存​

Mapbox Geocoding API は、永久および一時という 2 種類の結果保存を提供します。

一時結果はキャッシュできませんが、永久結果は無期限にキャッシュおよび保存できます。

Geocoding API で永久ストレージを使用するには、有効なクレジットカード情報を登録するか、アクティブな企業契約が必要です。

デフォルトでは、Geocoding API は一時的なジオコーディングを使用します。永久ジオコーディングを使用するには、オプションの permanent パラメータを true に設定します。

テキスト入力での正方向ジオコーディング​

get
https://api.mapbox.com/search/geocode/v6/forward?q={search_text}

フォワードジオコーディングクエリタイプを使用すると、検索テキストの文字列を使用して場所を検索し、その標準化された住所、地理的コンテキスト、および座標が返されます。

必須パラメータタイプ説明
qstring検索対象のフィーチャー。これには住所、市名などが含まれる可能性があります。検索テキストは URL エンコードされた UTF-8 文字列として表現され、セミコロン文字（生または URL エンコードされた形）を含まない必要があります。検索テキストをデコードした場合、単語や数字がスペースや句読点で区切られた 20 語以内、および最大 256 文字で構成される必要があります。

検索クエリの住所のフォーマット方法によって、正方向ジオコーディングリクエストで返される座標の精度が影響を受ける可能性があります。住所フォーマットのベストプラクティスについては、住所ジオコーディングフォーマットガイド を参照してください。
access_tokenstringすべてのジオコーディングリクエストには アクセストークン が含まれている必要があります。

リバースジオコーディングクエリの結果をさらに絞り込むには、次のオプションパラメータを使用できます:

オプションパラメータータイプ説明
permanentbooleanクエリの結果を保存するかどうかを指定します (true) または保存しない (false, デフォルト)。
autocompletebooleanオートコンプリートの結果を返すか (true, デフォルト) どうかを指定します (false)。 オートコンプリートが有効になっている場合、要求された文字列から始まる結果が含まれます。 例えば、India のクエリは、オートコンプリートが有効な場合は India と Indiana の両方を返すことがありますが、無効の場合は India のみが返されます。

オートコンプリートが有効な場合、各ユーザーのキーストロークが1回のジオコーディングAPIリクエストとしてカウントされます。 例えば、「Cali」の検索は4つのジオコーディングAPIリクエストとして反映されます。 送信するリクエストを減らすために、特定の文字数が入力されてからジオコーディングAPIを呼び出すようにアプリケーションを設定できます。
bboxnumber指定された境界ボックス内に含まれる結果のみに制限します。 境界ボックスはカンマで区切られた4つの数字として提供され、minLon,minLat,maxLon,maxLat の順序で指定します。 境界ボックスは180度の子午線を超えることはできません。
Location Helper を使用して、このAPIで使用するための境界ボックスを見つけることができます。
countrystring結果を1つ以上の国に限定します。 許可される値はカンマで区切られた ISO 3166 alpha 2 国コードです。
formatstring結果の希望するレスポンス形式を指定します (geojson, デフォルト) または互換性のための (v5)。
languagestringレスポンスで提供されるテキストの言語を設定します。 また、結果のスコアリングに影響を与え、要求された言語でユーザーのクエリに一致する結果が他の言語に一致する結果よりも優先されます。 例えば、Frank で始まるオートコンプリートクエリでは、英語 (en) 言語パラメータを指定すると Frankfurt が最初の結果として返されるかもしれませんが、 ドイツ語 (de) 言語パラメータでは Frankreich (“フランス”) が返されます。

オプションは、IETF 言語タグ であり、必須の ISO 639-1 言語コード と、必要に応じて1つ以上の IETF サブタグを含みます。

複数の値も指定でき、カンマで区切られます。 リストの最初の言語が主要言語と見なされ、それに対してレスポンスが生成されます。 他の言語に対しては翻訳が提供されます。翻訳セクション を参照してください。

サポートされている特定の言語については、言語カバレッジセクション を参照してください。
limitinteger返される結果の最大数を指定します。デフォルトは 5 で、サポートされる最大値は 10 です。
proximitystringこの場所に近い結果を優先するようにレスポンスをバイアスします。longitude,latitude の順序でカンマ区切りの2つの座標、または逆IP検索に基づいてバイアスするための ip という文字列として提供します。
typesstring利用可能なフィーチャータイプのサブセット (1つまたは複数) のみに結果をフィルタリングします。 オプションは country, region, postcode, district, place, locality, neighborhood, street, address です。 複数のオプションはカンマで区切られます。

利用可能なタイプについての詳細は、地理的フィーチャータイプセクション を参照してください。
worldviewstring様々な地域的、文化的、政治的グループによって異なる定義のフィーチャーを返します。 利用可能なワールドビューは: ar,cn,in,jp,ma,rs,ru,tr,us です。worldview が設定されていない場合、デフォルトで us ワールドビューの境界が返されます。

worldview パラメータの使用についての詳細は、ワールドビューセクション を参照してください。

フォワードジオコーディングの例リクエスト (テキスト入力)​

# 基本的なフォワードジオコーディングリクエスト
# ロサンゼルスを検索

$curl "https://api.mapbox.com/search/geocode/v6/forward?q=Los%20Angeles&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# 特定の地域にある「チェスター」という町を検索
# 近接パラメータをローカルの座標で追加
# ニュージャージー州チェスターの町が結果に含まれる

$curl "https://api.mapbox.com/search/geocode/v6/forward?q=chester&proximity=-74.70850,40.78375&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# types=country を指定して国だけを検索
# 結果はジョージア州ではなく、ジョージアの国に限定される

$curl "https://api.mapbox.com/search/geocode/v6/forward?q=georgia&types=country&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# 結果を 2 件に制限する limit オプションを使用
# 「ワシントン」の多くの可能性のある一致の中から、このクエリは 2 件のみを返す。

$curl "https://api.mapbox.com/search/geocode/v6/forward?q=Washington&limit=2&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# イレミトライアングルにある「Kaaleng」という場所を検索。cn worldview を指定すると、国の値として南スーダンが返される。worldview パラメータを指定しない場合はデフォルトで us worldview が適用され、国の値としてケニアが返される。

$curl "https://api.mapbox.com/search/geocode/v6/forward?q=Kaaleng&worldview=cn&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

テキスト入力のフォワードジオコーディングの応答​

ジオコーディング応答オブジェクトのセクション を参照してください。

セカンダリアドレスのクエリ
  • types パラメータが設定されていない場合、または「secondary_address」タイプがフィルタの types に含まれている場合は、セカンダリアドレスの検索が有効になります。
  • セカンダリアドレスクエリは、「デジグネータ」トークン（例:「Apt」、「Suite」、「Unit」、「#」）の後に識別子トークン（例:「12B」、「A」、「103」）が続く場合に検出されます。
  • 親住所にセカンダリアドレスが関連付けられている場合、最初にデータ内の指定された識別子と一致する既知のユニットが返されます。データ内で識別子がわかっていない場合、そのユニットは「外挿」され、親住所と同じ座標として入力されます。

構造化入力を使用したフォワードジオコーディング​

New in v6
get
https://api.mapbox.com/search/geocode/v6/forward?address_number={address_number}&street={street}&...

構造化入力は、検索クエリの各要素の機能タイプを定義することで、結果の精度を向上させるフォワードジオコーディング検索タイプです。構造化入力を使用する場合、q パラメータは、各機能タイプの別のパラメータに置き換えられます。

最良の結果を得るためには、クエリの各要素に機能タイプを割り当て、autocomplete を false に設定します。

必須パラメータタイプ説明
access_tokenstringすべてのジオコーディングリクエストには アクセストークン が含まれている必要があります。

構造化入力クエリで定義できる機能タイプは次のとおりです:

オプションパラメータタイプ説明
address_line1stringaddress_number と street を含む文字列。以下に挙げる address_number と street の別々のパラメータとして提供できます。
address_numberstring家に関連付けられた番号。
streetstring住所の中の通りの名前。
blockstring日本のように、住所の構成要素としてブロックが含まれる国。
placestring通常は都市、村、自治体など。これは郵便アドレッシングで使用される機能であり、現在地コンテキストが必要なエンドユーザーアプリケーション（天気表示など）での表示に適しています。
regionstring米国の州やカナダや中国の州など、国内のトップレベルの行政区画機能。
postcodestring国ごとの全国のアドレッシングシステムで使用される郵便番号。
localitystring郵便アドレッシングで使用される追加の行政層が存在する国、または現地の話し言葉に頻繁に記載される公式な市内区画。ブラジルやチリの市区やフランスの区など。
neighborhoodstring地元の話し言葉でしばしば言及される口語の市内区画 locality 機能とは異なり、公式なステータスがない場合や普遍的に合意された境界がない場合が多い。リバースジオコーディングクエリには利用できません。
countrystring一般的に認識されている国、または香港のように準国家的な行政ステータスを持ち ISO 3166-1 の国コードが割り当てられている地域。

構造化入力クエリの結果をさらに絞り込むには、次のオプションパラメータを使用できます:

オプションパラメータータイプ説明
permanentbooleanクエリの結果を保存するかどうかを指定します (true) または保存しない (false, デフォルト)。
autocompletebooleanオートコンプリートの結果を返すか (true, デフォルト) どうかを指定します (false)。 オートコンプリートが有効になっている場合、要求された文字列から始まる結果が含まれます。 例えば、India のクエリは、オートコンプリートが有効な場合は India と Indiana の両方を返すことがありますが、無効の場合は India のみが返されます。

オートコンプリートが有効な場合、各ユーザーのキーストロークが1回のジオコーディングAPIリクエストとしてカウントされます。 例えば、「Cali」の検索は4つのジオコーディングAPIリクエストとして反映されます。 送信するリクエストを減らすために、特定の文字数が入力されてからジオコーディングAPIを呼び出すようにアプリケーションを設定できます。
bboxnumber指定された境界ボックス内に含まれる結果のみに制限します。 境界ボックスはカンマで区切られた4つの数字として提供され、minLon,minLat,maxLon,maxLat の順序で指定します。 境界ボックスは180度の子午線を超えることはできません。
Location Helper を使用して、このAPIで使用するための境界ボックスを見つけることができます。
countrystring結果を1つ以上の国に限定します。 許可される値はカンマで区切られた ISO 3166 alpha 2 国コードです。
formatstring結果の希望するレスポンス形式を指定します (geojson, デフォルト) または互換性のための (v5)。
languagestringレスポンスで提供されるテキストの言語を設定します。 また、結果のスコアリングに影響を与え、要求された言語でユーザーのクエリに一致する結果が他の言語に一致する結果よりも優先されます。 例えば、Frank で始まるオートコンプリートクエリでは、英語 (en) 言語パラメータを指定すると Frankfurt が最初の結果として返されるかもしれませんが、 ドイツ語 (de) 言語パラメータでは Frankreich (“フランス”) が返されます。

オプションは、IETF 言語タグ であり、必須の ISO 639-1 言語コード と、必要に応じて1つ以上の IETF サブタグを含みます。

複数の値も指定でき、カンマで区切られます。 リストの最初の言語が主要言語と見なされ、それに対してレスポンスが生成されます。 他の言語に対しては翻訳が提供されます。翻訳セクション を参照してください。

サポートされている特定の言語については、言語カバレッジセクション を参照してください。
limitinteger返される結果の最大数を指定します。デフォルトは 5 で、サポートされる最大値は 10 です。
proximitystringこの場所に近い結果を優先するようにレスポンスをバイアスします。longitude,latitude の順序でカンマ区切りの2つの座標、または逆IP検索に基づいてバイアスするための ip という文字列として提供します。
typesstring利用可能なフィーチャータイプのサブセット (1つまたは複数) のみに結果をフィルタリングします。 オプションは country, region, postcode, district, place, locality, neighborhood, street, address です。 複数のオプションはカンマで区切られます。

利用可能なタイプについての詳細は、地理的フィーチャータイプセクション を参照してください。
worldviewstring様々な地域的、文化的、政治的グループによって異なる定義のフィーチャーを返します。 利用可能なワールドビューは: ar,cn,in,jp,ma,rs,ru,tr,us です。worldview が設定されていない場合、デフォルトで us ワールドビューの境界が返されます。

worldview パラメータの使用についての詳細は、ワールドビューセクション を参照してください。

構造化入力を使用したフォワードジオコーディングの例リクエスト​

$curl --location --request GET "https://api.mapbox.com/search/geocode/v6/forward?country=us&address_number=1600&street=pennsylvania%20ave%20nw&postcode=20500&place=Washington%20dc&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

構造化入力を使用したフォワードジオコーディングの応答​

ジオコーディング応答オブジェクトのセクション を参照してください。

リバースジオコーディング​

get
https://api.mapbox.com/search/geocode/v6/reverse?longitude={longitude}&latitude={latitude}

リバースジオコーディングクエリタイプは、座標のペアを検索し、その場所の標準化された住所や地理的コンテキストを含む地理的機能が返されます。

必須パラメータタイプ説明
longitudenumberクエリ対象場所の経度の十進法値。
latitudenumberクエリ対象場所の緯度の十進法値。
access_tokenstringすべてのジオコーディングリクエストには アクセストークン が含まれている必要があります。

フォワードジオコーディングクエリの結果をさらに絞り込むには、次のオプションパラメータを使用できます:

オプションパラメータタイプ説明
permanentboolean結果を保存する意図があるかどうかを指定します (true または false, デフォルト)。
countrystring結果を特定の国に限定します。許可される値はコンマで区切られた ISO 3166-1 alpha-2 の国コードです。
languagestringユーザーの言語を指定します。このパラメータにより、応答で提供されるテキストの言語が制御されます。

オプションは IETF 言語タグ で、必須の ISO 639-1 言語コード と、オプションで国またはスクリプトの IETF サブタグの 1 つまたは複数で構成されます。

指定できる値は 1 つのみです。

サポートされる特定の言語についての詳細は、言語カバレッジセクション を参照してください。
limitinteger返される結果の最大数を指定します。デフォルト値は 1 で、サポートされる最大数は 5 です。

逆方向ジオコーディングのデフォルト動作は、複数レベルの行政階層の各レベルで最大 1 つのフィーチャーを返すことです（例えば、1 つの住所、1 つの地域、1 つの国）。限度を増やすと、同じタイプの複数のフィーチャーが返されますが、これは 1 つのタイプのみのため（例えば、複数の address 結果）。したがって、limit をデフォルト値よりも高く設定するには、正確に 1 つの types パラメータを指定する必要があります。
typesstring結果を利用可能なフィーチャータイプのサブセット（1 つまたは複数）に絞り込みます。オプションは country, region, postcode, district, place, locality, neighborhood, street, および address。複数のオプションをコンマで区切ることができます。

利用可能なタイプの詳細については、地理的フィーチャータイプセクション を参照してください。
worldviewstring地域、文化、または政治的なグループに属するさまざまな視聴者によって異なって定義される特徴を返します。利用可能な視点は、ar,cn,in,jp,ma,ru,tr,usです。視点が指定されていない場合、デフォルトでは us の視点の境界が返されます。

worldview パラメータの使用についての詳細は、視点セクション を参照してください。

リバースジオコーディングの例リクエスト​

# 基本的な逆方向ジオコーディングリクエスト

# 特定の場所近くの場所を検索

$curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=-73.989&latitude=40.733&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# 結果を住所のみに絞る

$curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=-73.989&latitude=40.733&types=address&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# イレミトライアングル内のクエリで、USワールドビューの特徴を返す

$curl "https://api.mapbox.com/search/geocode/v6/reverse?longitude=35.4628&latitude=4.8975&worldview=us&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

リバースジオコーディングの応答​

リバースジオコーディングクエリのAPI応答は、GeoJSON フィーチャーコレクションを Mapbox Geocoding Response フォーマットで返します。Geocoding API からの応答のフォーマットの詳細については、ジオコーディング応答オブジェクトセクション を参照してください。

バッチジオコーディング​

v6 で改良
Snowflake からのジオコーディング

Snowflake ユーザーは、データウェアハウスに保存されたデータに対してバッチジオコーディング操作を実行できます。Mapbox Snowflake Native アプリは Snowflake Marketplace で入手できます。

post
https://api.mapbox.com/search/geocode/v6/batch

バッチジオコーディングクエリタイプを使用すると、1 回のリクエストで最大 1000 件の正方向または逆方向ジオコーディングクエリを送信できます。

バッチジオコーディングリクエストは、複数の検索クエリを連続して配置した JSON オブジェクトとして BODY に渡される形式です。URL 文字列のクエリパラメータとして定義されたフィールドは JSON オブジェクトのフィールドになります。複数の値を指定するフィールド（例: types, country, bbox, proximity）は、コンマ区切りの文字列としてまたは JSON-フォーマットの配列として渡すことができます（、例: types フィルタ値は "address,street,place" または ["address", "street", "place"] と表現できます）。

1 回のバッチジオコーディングリクエスト内で、異なるタイプのクエリを束ねることができます。正方向クエリ、構造化入力クエリ、および逆方向クエリです。各クエリには個別のパラメータが定義される場合があります。例えば、1 つのクエリに対して IP 近接性がオンに設定され、残りにはオフに設定されるなど。

バッチジオコーディングリクエストの請求

バッチジオコーディングリクエストの各検索は 1 つのリクエストとしてカウントされます。

HTTP POST リクエストを使用して、次のボディ構造を持つ バッチジオコーディングリクエスト を作成できます:

https://api.mapbox.com/search/geocode/v6/batch

リクエスト ボディ

[
    {
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    {
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]
必須パラメータタイプ説明
access_tokenstringすべてのジオコーディングリクエストには アクセストークン が含まれている必要があります。
オプションパラメータタイプ説明
permanentbooleanクエリの結果を保存する意図があるかどうか (true) か (false, デフォルト)。

バッチジオコーディングの例リクエスト​

$curl --location --request POST "https://api.mapbox.com/search/geocode/v6/batch?access_token=YOUR_MAPBOX_ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '[
    {/**** フォワードジオコーディングリクエスト ****/
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    { /**** 構造化入力を使用したフォワードジオコーディングリクエスト ****/
        "country": "us",
        "address_number": "1600",
        "street": "Pennsylvania Avenue NW",
        "postcode": "20500",
        "place": "Washington, DC"
    },
    {/**** リバースジオコーディングリクエスト ****/
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]'

バッチジオコーディングの応答​

バッチジオコーディングクエリの応答は batch プロパティを持つオブジェクトです。batch プロパティは ジオコーディング応答オブジェクト の配列です。リクエスト内のクエリの順序は、バッチ配列内の対応するオブジェクトの順序を決定します。特定のクエリに対して結果が返されない場合、そのクエリの features 配列は空です ("features": [])。

以下は、3 つのクエリのリストが含まれている例のリクエストです。最初の 2 つのリクエストはワードジオコーディング用で、最後の 1 つはリバースです。

$curl --location --request POST 'https://api.mapbox.com/search/geocode/v6/batch?access_token=YOUR_MAPBOX_ACCESS_TOKEN&permanent=true' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "types": ["address"],
        "q": "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States",
        "bbox": [-80, 35, -70, 40],
        "limit": 1
    },
    {
        "types": ["address"],
        "q": "aslkdjf",
        "bbox": [-80, 35, -70, 40]
    },
    {
        "types": ["address"],
        "longitude": -73.986136,
        "latitude": 40.748895
    }
]'

応答では、すべてのクエリの結果がクエリの順序と同じ順序で表示されることを確認してください。aslkdjf の 2 番目のクエリは結果を返しませんが、バッチ配列の 2 番目の位置に存在します。

{
  "batch": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "id": "dXJuOm1ieGFkcjo2YzdhYjM4Yi05YzM4LTQ3ZDItODFkMS1jYzZlYjg5YzliMWM",
          "geometry": {
            "type": "Point",
            "coordinates": [-77.03655, 38.89768]
          },
          "properties": {
            "mapbox_id": "dXJuOm1ieGFkcjo2YzdhYjM4Yi05YzM4LTQ3ZDItODFkMS1jYzZlYjg5YzliMWM",
            "feature_type": "address",
            "name": "1600 Pennsylvania Avenue Northwest",
            "coordinates": {
              "longitude": -77.03655,
              "latitude": 38.89768,
              "accuracy": "rooftop"
            },
            "place_formatted": "Washington, District of Columbia 20500, United States",
            "match_code": {
              "address_number": "matched",
              "street": "matched",
              "postcode": "matched",
              "place": "matched",
              "region": "matched",
              "locality": "not_applicable",
              "country": "inferred",
              "confidence": "exact"
            },
            "context": {
              "address": {
                "mapbox_id": "dXJuOm1ieGFkcjo2YzdhYjM4Yi05YzM4LTQ3ZDItODFkMS1jYzZlYjg5YzliMWM",
                "address_number": "1600",
                "street_name": "Pennsylvania Avenue Northwest",
                "name": "1600 Pennsylvania Avenue Northwest"
              },
              "street": {
                "mapbox_id": "dXJuOm1ieGFkcjo2YzdhYjM4Yi05YzM4LTQ3ZDItODFkMS1jYzZlYjg5YzliMWM",
                "name": "Pennsylvania Avenue Northwest"
              },
              "neighborhood": {
                "mapbox_id":```
                  "dXJuOm1ieHBsYzpHYUVzN0E",
                  "name": "National Mall",
                  "alternate": {
                    "mapbox_id": "dXJuOm1ieHBsYzpEY1ZNN0E",
                    "name": "Franklin Mcpherson Square"
                  }
                },
                "postcode": {
                  "mapbox_id": "dXJuOm1ieHBsYzpBOEZPN0E",
                  "name": "20500"
                },
                "place": {
                  "mapbox_id": "dXJuOm1ieHBsYzpGSmlvN0E",
                  "name": "Washington",
                  "wikidata_id": "Q61"
                },
                "region": {
                  "mapbox_id": "dXJuOm1ieHBsYzpCUVRz",
                  "name": "District of Columbia",
                  "wikidata_id": "Q3551781",
                  "region_code": "DC",
                  "region_code_full": "US-DC"
                },
                "country": {
                  "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
                  "name": "United States",
                  "wikidata_id": "Q30",
                  "country_code": "US",
                  "country_code_alpha_3": "USA"
                }
              }
            }
          }
        ],
        "attribution": "NOTICE: © 2023 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
      },
      {
        "type": "FeatureCollection",
        "features": [],
        "attribution": "NOTICE: © 2023 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
      },
      {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "id": "dXJuOm1ieGFkcjplMzVmMzZiOC1kYjRmLTQyOWItOWE4ZC0yZGQ3ZmQ1OTUzMTY",
            "geometry": {
              "type": "Point",
              "coordinates": [-73.9861365, 40.7488949]
            },
            "properties": {
              "mapbox_id": "dXJuOm1ieGFkcjplMzVmMzZiOC1kYjRmLTQyOWItOWE4ZC0yZGQ3ZmQ1OTUzMTY",
              "feature_type": "address",
              "name": "20 West 34th Street",
              "coordinates": {
                "longitude": -73.9861365,
                "latitude": 40.7488949,
                "accuracy": "rooftop"
              },
              "place_formatted": "New York, New York 10118, United States",
              "context": {
                "address": {
                  "mapbox_id": "dXJuOm1ieGFkcjplMzVmMzZiOC1kYjRmLTQyOWItOWE4ZC0yZGQ3ZmQ1OTUzMTY",
                  "address_number": "20",
                  "street_name": "West 34th Street",
                  "name": "20 West 34th Street"
                },
                "street": {
                  "mapbox_id": "dXJuOm1ieGFkcjplMzVmMzZiOC1kYjRmLTQyOWItOWE4ZC0yZGQ3ZmQ1OTUzMTY",
                  "name": "West 34th Street"
                },
                "neighborhood": {
                  "mapbox_id": "dXJuOm1ieHBsYzpGQ2VNN0E",
                  "name": "Koreatown"
                },
                "postcode": {
                  "mapbox_id": "dXJuOm1ieHBsYzpBWUFPN0E",
                  "name": "10118"
                },
                "locality": {
                  "mapbox_id": "dXJuOm1ieHBsYzpGREtLN0E",
                  "name": "Manhattan",
                  "wikidata_id": "Q11299"
                },
                "place": {
                  "mapbox_id": "dXJuOm1ieHBsYzpEZTVJN0E",
                  "name": "New York",
                  "wikidata_id": "Q60"
                },
                "district": {
                  "mapbox_id": "dXJuOm1ieHBsYzpBUU5tN0E",
                  "name": "New York County",
                  "wikidata_id": "Q500416"
                },
                "region": {
                  "mapbox_id": "dXJuOm1ieHBsYzpBYVRz",
                  "name": "New York",
                  "wikidata_id": "Q1384",
                  "region_code": "NY",
                  "region_code_full": "US-NY"
                },
                "country": {
                  "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
                  "name": "United States",
                  "wikidata_id": "Q30",
                  "country_code": "US",
                  "country_code_alpha_3": "USA"
                }
              }
            }
          }
        ],
        "attribution": "NOTICE: © 2023 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
      }
    ]
  }
}

ジオコーディング応答オブジェクト​

Geocoding API リクエストへの応答は、以下のプロパティを含むオブジェクトです。

プロパティタイプ説明
typestring"FeatureCollection", GeoJSON 仕様 の GeoJSON タイプ。
featuresarrayフィーチャーオブジェクトの配列。
前方ジオコード: 返される機能は関連性順に並んでいます。
逆ジオコード: 返される機能は、インデックス階層、最も具体的な特徴から最も一般的な特徴まで並んでいます。

Geocoding API の応答における結果の優先順位について詳しくは、「検索結果の優先順位付け」ガイドをご覧ください。
attributionstringMapbox Geocoding API の結果を Mapbox に帰属させます。

Mapbox Geocoding API をパワーアップさせるデータは、絶えず更新および改善されています。これは、応答オブジェクト内のプロパティの値が保証されず、同じ API バージョン内で変更される可能性があることを意味します。同じ API バージョン内で応答からプロパティが削除されることはありません。

features 配列内の各フィーチャーオブジェクトには、以下のプロパティが含まれている場合があります。

プロパティタイプ説明
idstringフィーチャー識別子。このプロパティは GeoJSON 仕様に準拠するために "id" と名付けられていますが、応答内の mapbox_id とも呼ばれます。
typestring"Feature", GeoJSON 仕様 の GeoJSON タイプ。
geometryobject返されたフィーチャーの空間ジオメトリーを記述するオブジェクト。
geometry.typestring"Point", GeoJSON 仕様 の GeoJSON タイプ。
geometry.coordinatesarray[longitude,latitude] 形式の配列で、指定された bbox の中央座標。
propertiesobject結果フィーチャーの詳細を含むオブジェクト。

フィーチャーオブジェクトの properties 内の各オブジェクトには、以下の属性が含まれている場合があります。

プロパティタイプ説明
mapbox_idstringフィーチャー ID。mapbox_id は Mapbox 検索データベース内の場所を一意に識別します。Mapbox ID は Geocoding API へのリクエストで前方検索として受け入れられ、対応するフィーチャーを返します。
feature_typestringフィーチャーのタイプを記述する文字列。オプションには country, region, postcode, district, place, locality, neighborhood, street, address が含まれます。
v5 では place_type。
namestringaddress_number と street を含むフォーマットされた文字列。
name_preferredstringフィーチャー名の標準的またはより一般的な別名。たとえば、「アメリカ」を検索すると "United States" が name_preferred として返されます。
place_formattedstring結果コンテキストのフォーマットされた文字列: 場所、地域、国、郵便番号。結果の name の後に続く部分。
full_addressstringname_preferred と place_formatted を組み合わせたフィーチャーの完全なフォーマットされた文字列。
contextobject地理的階層の親機能を表すオブジェクト。これは country, region, postcode, district, place, locality, neighborhood, street のサブオブジェクトを含む場合があります。
どのサブオブジェクトが含まれているかは、利用可能なデータのカバレッジによって異なります。
coordinatesobjectフィーチャーの地理的位置と精度を表すオブジェクト。
coordinates.longitudenumber結果の経度。
coordinates.latitudenumber結果の緯度。
coordinates.accuracystring返された address タイプの機能の精度メトリクス。下記の住所機能の精度ポイントを参照してください。
coordinates.routable_pointsarray各プロパティに name, longitude, latitude を含むアドレス機能のルート可能ポイントの配列。
bboxarray[minLon,minLat,maxLon,maxLat] の配列形式のフィーチャーの境界ボックス。このプロパティは country, region, postcode, district, place, locality, または neighborhood タイプのフィーチャーのみに提供されます。
match_codeobject結果構成要素がクエリにどの程度一致しているかを示すメタデータのオブジェクト。下記のスマートアドレスマッチを参照してください。

コンテキストオブジェクト​

properties 内の context オブジェクトは、指定された住所や場所の完全な地理的階層を分解します。これは、住所の各構成要素の名前付き値に確実にアクセスできる方法であり、Wikidata ID や 3 文字の国コードなどのフィーチャー固有のデータも含まれます。

各サブオブジェクトには常に mapbox_id と name が関連付けられています。ID は前方ジオコーディング検索を介して直接クエリ可能であり、異なる地理的階層に移動できます。住所機能には address サブオブジェクトも含まれ、street_name および address_number プロパティが含まれています。

secondary_address フィーチャーには、コンテキストに一致するサブオブジェクトもあります:

{
  "secondary_address": {
    "mapbox_id": "dXJuOm1ieGFkci11bml0OjdkZTE3MmUxLTJiMjktNDU1Mi1iNGQzLTkwN2JjMGZmOGQ1NDoyMDE",
    "name": "UNIT 201",
    "designator": "UNIT",
    "identifier": "201",
    "extrapolated": true // ユニット番号がデータ内で既知でないことを示しますが、親住所はセカンダリアドレスを持っていることが知られています。
  },
  ...
}

コンテキストオブジェクトの例​

以下は、住所 2595 Lucky John Drive, Park City, Utah 84060, United States に対して返されたコンテキストオブジェクトの例です:

"context": {
    "address": {
        "mapbox_id": "dXJuOm1ieGFkcjozOGY3OTg1OC1jNzY0LTQ4ZGUtYTFmMC04NjJjOTM1ZWViMjc",
        "address_number": "2595",
        "street_name": "Lucky John Drive",
        "name": "2595 Lucky John Drive"
    },
    "street": {
        "mapbox_id": "dXJuOm1ieGFkcjozOGY3OTg1OC1jNzY0LTQ4ZGUtYTFmMC04NjJjOTM1ZWViMjc",
        "name": "Lucky John Drive"
    },
    "neighborhood": {
        "mapbox_id": "dXJuOm1ieHBsYzpITktzN0E",
        "name": "Park Meadows"
    },
    "postcode": {
        "mapbox_id": "dXJuOm1ieHBsYzpFUjNPN0E",
        "name": "84060"
    },
    "place": {
        "mapbox_id": "dXJuOm1ieHBsYzpEdjlvN0E",
        "name": "Park City",
        "wikidata_id": "Q482993"
    },
    "district": {
        "mapbox_id": "dXJuOm1ieHBsYzpBVlRHN0E",
        "name": "Summit County",
        "wikidata_id": "Q484563"
    },
    "region": {
        "mapbox_id": "dXJuOm1ieHBsYzpCa1Rz",
        "name": "Utah",
        "wikidata_id": "Q829",
        "region_code": "UT",
        "region_code_full": "US-UT"
    },
    "country": {
        "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
        "name": "United States",
        "wikidata_id": "Q30",
        "country_code": "US",
        "country_code_alpha_3": "USA"
    }
}

翻訳​

country, region, district, place, neighborhood プロパティに対して 1 つ以上の言語がコンテキストオブジェクトに提供される場合、翻訳プロパティが表示されます。これは、キーが言語コードで、値が言語および名前のプロパティを持つオブジェクトであるオブジェクトです。

翻訳の例​

パラメータ language=en,es を指定した場合のコンテキストオブジェクトの例です。

{
  "context": {
    "address": {
      "mapbox_id": "dXJuOm1ieGFkcjowYzNhM2QzZi03ODIyLTQ3YzItODRlNC04YzA3ZDIxMTE2MmE",
      "address_number": "100",
      "street_name": "Jefferson Street Northwest",
      "name": "100 Jefferson Street Northwest"
    },
    "street": {
      "mapbox_id": "dXJuOm1ieGFkcjowYzNhM2QzZi03ODIyLTQ3YzItODRlNC04YzA3ZDIxMTE2MmE",
      "name": "Jefferson Street Northwest"
    },
    "neighborhood": {
      "mapbox_id": "dXJu```
Om1ieHBsYzpCQTRzN0E",
      "name": "Brightwood Park",
      "translations": {
        "en": {
          "language": "en",
          "name": "Brightwood Park"
        },
        "es": {
          "language": "es",
          "name": "Brightwood Park"
        }
      }
    },
    "postcode": {
      "mapbox_id": "dXJuOm1ieHBsYzpBNSt1N0E",
      "name": "20011"
    },
    "place": {
      "mapbox_id": "dXJuOm1ieHBsYzpGSmlvN0E",
      "name": "Washington",
      "wikidata_id": "Q61",
      "translations": {
        "en": {
          "language": "en",
          "name": "Washington"
        },
        "es": {
          "language": "es",
          "name": "Washington"
        }
      }
    },
    "region": {
      "mapbox_id": "dXJuOm1ieHBsYzpCUVRz",
      "name": "District of Columbia",
      "wikidata_id": "Q3551781",
      "region_code": "DC",
      "region_code_full": "US-DC",
      "translations": {
        "en": {
          "language": "en",
          "name": "District of Columbia"
        },
        "es": {
          "language": "es",
          "name": "Distrito de Columbia"
        }
      }
    },
    "country": {
      "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
      "name": "United States",
      "wikidata_id": "Q30",
      "country_code": "US",
      "country_code_alpha_3": "USA",
      "translations": {
        "en": {
          "language": "en",
          "name": "United States"
        },
        "es": {
          "language": "es",
          "name": "Estados Unidos"
        }
      }
    }
  }
}

住所フィーチャーの精度ポイント​

ジオコーディング応答オブジェクトの coordinates.accuracy プロパティは、返された address タイプのフィーチャーのポイント精度メトリクスです。このリストは変更される可能性があります。

精度説明
rooftop結果は既知の建物/入口に交差しています。
parcel結果は指定されたポリゴン境界内の 1 つ以上の住所に関連付けられています。
point結果は既知の住所ポイントですが、既知の屋上/区画に交差していません。
interpolated結果の位置と存在は、近くの既知の住所に基づいて推定されます。
approximate結果の位置は 9 桁の郵便番号の重心によって概算されています。
intersectionストリートタイプのフィーチャー専用。結果は 2 つのストリートの交差点です。

スマートアドレスマッチ​

New in v6

Geocoding API の match_code オブジェクトは、結果の住所フィーチャーが送信されたクエリとどのように一致するかを理解するのに役立ちます。住所タイプのフィーチャーにのみ利用可能な match_code は、結果の各要素がクエリとどのように一致するか、そしてそれがどの程度の信頼性で一致するかの詳細な説明を提供します。これにより、アプリケーションの許容度に応じて、結果を保持するかどうかの判断に役立ちます。

スマートアドレスマッチは、address タイプのフィーチャーを返すすべての前方ジオコーディングリクエストに対して利用できます。これは、構造化入力 前方クエリを使用すると最も効果的に機能し、リクエスト の要素は明示的にタイプ付けされる必要があります。

信頼性スコア説明
exact一致しないコンポーネントはなく（最大 2 つが推測される）、余分なクエリトークンもありません。
high1 つのコンポーネント（house_number または region を除く）が修正される可能性があります。さらに、house_number, street, および postcode のみが提供され、正確に一致する場合、高い信頼性が返されます。
medium2 つのコンポーネント（house_number または region を除く）が変更されることがあります。軽微な綴り誤りを許容します。house_number, street, place, postcode が一致すると、region が修正される可能性があります。
lowhouse_number, region, または 2 つ以上の他のコンポーネントが修正されている可能性があります。
マッチコード説明
matchedコンポーネントの値がユーザーの入力と一致します。
unmatchedコンポーネントの値がユーザーの入力と一致しないか、ユーザーがこのタイプのコンポーネントをクエリに含めませんでした。
not_applicableコンポーネントは、例えば locality のように、郵便住所の文字列では使用されません。
inferredクエリにこのタイプのコンポーネントが含まれていませんが、自信を持って値を推測できました。これは country コンポーネントに対してのみ返されます。
plausibleこれは address_number と secondary_address コンポーネントにのみ関連します。address_number の場合、これは住所の精度が補間されたものであることを意味します。secondary_address の場合、これは副住所が外挿された、すなわちジオコーディングサービスがデータで特定の一致する副住所を見つけなかったことを意味します。

match_code の例​

この構造化入力を使用したフォワードジオコーディングリクエストには、アメリカ合衆国ユタ州パークシティの有効な住所が含まれます。

https://api.mapbox.com/search/geocode/v6/forward?&address_number=2595&street=lucky john dr&place=park city&region=CO

region パラメータの値は CO であり、結果フィーチャーのプロパティ内の match_code で unmatched ステータスが表示されます。

{
  "name": "2595 Lucky John Drive",
  "place_formatted": "Park City, Utah 84060, United States",
  "match_code": {
    "address_number": "matched",
    "street": "matched",
    "postcode": "unmatched",
    "place": "matched",
    "region": "unmatched",
    "locality": "not_applicable",
    "country": "inferred",
    "confidence": "medium"
  }
}

フォワードジオコーディングの例応答​

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "dXJuOm1ieGFkcjo5ZDQzNzM1Mi0xZGZiLTRkNTItYWMxNC01MzllZjY5ODIwMmI",
      "geometry": {
        "type": "Point",
        "coordinates": [-111.86313, 40.725163]
      },
      "properties": {
        "mapbox_id": "dXJuOm1ieGFkcjo5ZDQzNzM1Mi0xZGZiLTRkNTItYWMxNC01MzllZjY5ODIwMmI",
        "feature_type": "address",
        "name": "974 2100 South",
        "coordinates": {
          "longitude": -111.86313,
          "latitude": 40.725163,
          "accuracy": "rooftop"
        },
        "place_formatted": "Salt Lake City, Utah 84106, United States",
        "match_code": {
          "address_number": "matched",
          "street": "matched",
          "postcode": "unmatched",
          "place": "unmatched",
          "region": "unmatched",
          "locality": "not_applicable",
          "country": "inferred",
          "confidence": "low"
        },
        "context": {
          "address": {
            "mapbox_id": "dXJuOm1ieGFkcjo5ZDQzNzM1Mi0xZGZiLTRkNTItYWMxNC01MzllZjY5ODIwMmI",
            "address_number": "974",
            "street_name": "2100 South",
            "name": "974 2100 South"
          },
          "street": {
            "mapbox_id": "dXJuOm1ieGFkcjo5ZDQzNzM1Mi0xZGZiLTRkNTItYWMxNC01MzllZjY5ODIwMmI",
            "name": "2100 South"
          },
          "neighborhood": {
            "mapbox_id": "dXJuOm1ieHBsYzpERWdNN0E",
            "name": "Fairmont",
            "alternate": {
              "mapbox_id": "dXJuOm1ieHBsYzpLMmRzN0E",
              "name": "Winfield"
            }
          },
          "postcode": {
            "mapbox_id": "dXJuOm1ieHBsYzpFU011N0E",
            "name": "84106"
          },
          "place": {
            "mapbox_id": "dXJuOm1ieHBsYzpFVmhvN0E",
            "name": "Salt Lake City",
            "wikidata_id": "Q23337",
            "alternate": {
              "mapbox_id": "dXJuOm1ieHBsYzpETE5vN0E",
              "name": "Millcreek"
            }
          },
          "district": {
            "mapbox_id": "dXJuOm1ieHBsYzpBVGdtN0E",
            "name": "Salt Lake County",
            "wikidata_id": "Q484556"
          },
          "region": {
            "mapbox_id": "dXJuOm1ieHBsYzpCa1Rz",
            "name": "Utah",
            "wikidata_id": "Q829",
            "region_code": "UT",
            "region_code_full": "US-UT"
          },
          "country": {
            "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          }
        }
      }
    },
    {
      "type": "Feature",
      "id": "dXJuOm1ieGFkcjpkNjZkM2M0Zi1hNTA0LTQ3NTQtYTZjMS1iNjYwMGU2NWY4NmI",
      "geometry": {
        "type": "Point",
        "coordinates": [-111.919654, 40.725872]
      },
      "properties": {
        "mapbox_id": "dXJuOm1ieGFkcjpkNjZkM2M0Zi1hNTA0LTQ3NTQtYTZjMS1iNjYwMGU2NWY4NmI",
        "feature_type": "address",
        "name": "974 2100 South",
        "coordinates": {
          "longitude": -111.919654,
          "latitude": 40.725872,
          "accuracy": "interpolated"
        },
        "place_formatted": "South Salt Lake, Utah 84119, United States",
        "match_code": {
          "address_number": "plausible",
          "street": "matched",
          "postcode": "unmatched",
          "place": "unmatched",
          "region": "unmatched",
          "locality": "not_applicable",
          "country": "inferred",
          "confidence": "low"
        },
        "context": {
          "address": {
            "mapbox_id": "dXJuOm1ieGFkcjpkNjZkM2M0Zi1hNTA0LTQ3NTQtYTZjMS1iNjYwMGU2NWY4NmI",
            "address_number": "974",
            "street_name": "2100 South",
            "name": "974 2100 South"
          },
          "street": {
            "mapbox_id": "dXJuOm1ieGFkcjpkNjZkM2M0Zi1hNTA0LTQ3NTQtYTZjMS1iNjYwMGU2NWY4NmI",
            "name": "2100 South"
          },
          "neighborhood": {
            "mapbox_id": "dXJuOm1ieHBsYzpCVG5NN0E",
            "name": "Cannon",
            "alternate": {
              "mapbox_id": "dXJuOm1ieHBsYzpGYU5zN0E",
              "name": "Lincoln Park"
            }
          },
          "postcode": {
            "mapbox_id": "dXJuOm1ieHBsYzpFU1RPN0E",
            "name": "84119"
          },
          "place": {
            "mapbox_id": "dXJuOm1ieHBsYzpFbStJN0E",
            "name": "South Salt Lake",
            "alternate": {
              "mapbox_id": "dXJuOm1ieHBsYzpFMHRJN0E",
              "name": "Taylorsville"
            }
          },
          "district": {
            "mapbox_id": "dXJuOm1ieHBsYzpBVGdtN0E",
            "name": "Salt Lake County",
            "wikidata_id": "Q484556"
          },
          "region": {
            "mapbox_id": "dXJuOm1ieHBsYzpCa1Rz",
            "name": "Utah",
            "wikidata_id": "Q829",
            "region_code": "UT",
            "region_code_full": "US-UT"
          },
          "country": {
            "mapbox_id": "dXJuOm1ieHBsYzpJdXc",
            "name": "United States",
            "wikidata_id": "Q30",
            "country_code": "US",
            "country_code_alpha_3": "USA"
          }
        }
      }
    }
  ],
  "attribution": "NOTICE: © 2023 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
}

視点​

worldview パラメータを使用して、さまざまな地域、文化、または政治的グループに属する視聴者によって異なる特徴を識別します。Geocoding API は country と region データタイプの視点のみをサポートしますが、将来的には他のデータタイプにも拡張される可能性があります。

利用可能な視点​

Geocoding API は以下の worldview パラメータ値をサポートします:

値説明
arアルゼンチンの視聴者向けの特徴
cn中国本土の視聴者向けの特徴
inインドの視聴者向けの特徴
jp日本の視聴者向けの特徴
maモロッコの視聴者向けの特徴
ruロシアの視聴者向けの特徴
trトルコの視聴者向けの特徴
usアメリカの視聴者向けの特徴

返された特徴は、上記の国のそれぞれの政府によって公式に承認されているわけではありません。

各クエリは最大 1 つの worldview をサポートします。1 つの検索で複数の worldview をクエリしようとするとエラーメッセージが表示されます。視点が選択されていない場合、Geocoding API は us 視点の特徴を返します。

worldview パラメータの使用​

Mapbox サービスでは、worldview データフィールドは、さまざまな地域、文化、または政治的グループに属する視聴者によって異なって定義される地理的特徴を識別するために使用されます。worldview を設定することで、所有権や定義が一致しない地域にある住所の返される値に影響を与えます。

例えば、南スーダンの東エクアトリア州とケニアのトゥルカナ郡の間にあるイレミトライアングルの住所を考えてみてください。選択された worldview によって、この場所の住所が異なる国コンテキストで返されます。

  • worldview=cn の場合、カーレング（東エクアトリアまたは南スーダン）が返されます。
  • worldview=us の場合、カーレング（トゥルカナまたはケニア）が返されます。

したがって、worldview=cn を使用してケニア (ke) 国フィルタと組み合わせる場合、この地域の住所検索は成功しません。代わりに、worldview=cn と南スーダン (ss) 国フィルタを組み合わせる必要があります。

worldview と country パラメータを組み合わせる際には注意が必要です。これらのインデックスは緩やかに結びついています。

worldview 値を変更することで地図の境界がどのように影響を受けるかの視覚的な例については、関連する Maps 境界サービス を参照してください。

言語カバレッジ​

言語の翻訳可能性は地域や言語によっても異なります。以下の言語サポート層を提供しています。

グローバルカバレッジ​

これらの言語は通常、country、region および主要な place フィーチャーで常に存在します。

言語
de ドイツ語en 英語es スペイン語
fr フランス語it イタリア語nl オランダ語
pl ポーランド語

ローカルカバレッジ​

これらの言語はグローバルカバレッジには欠ける場合がありますが、その国で広く使用されている場合は country、regionおよび主要なplace フィーチャーで常に存在します。

言語
az アゼルバイジャン語bn ベンガル語ca カタルーニャ語
cs チェコ語da デンマーク語el 現代ギリシャ語
et エストニア語fa ペルシア語fi フィンランド語
ga アイルランド語hu ハンガリー語id インドネシア語
is アイスランド語ja 日本語ka グルジア語
km 中部クメール語ko 韓国語lt リトアニア語
lv ラトビア語mk マケドニア語mn モンゴル語
ms マレー語nb ノルウェー語 (ブークモール)pt ポルトガル語
ro ルーマニア語sk スロバキア語sl スロベニア語
sq アルバニア語th タイ語tl タガログ語
uk ウクライナ語vi ベトナム語zh 中国語
zh_Hans 簡体中国語zh_Hant 繁体中国語zh_TW 台湾華語

リミテッドカバレッジ​

これらの言語は時々存在しますが、カバレッジは一貫性がないか地理的に制約されていることがあります。

言語
ar アラビア語bs ボスニア語heヘブライ語
hi ヒンディー語kk カザフ語lo ラオス語
my ビルマ語ru ロシア語sr セルビア語
sv スウェーデン語te テルグ語tk トルクメン語
tr トルコ語

Geocoding API 応答のフォーマットやプロパティの詳細については、ジオコーディング応答オブジェクトセクション を参照してください。

Geocoding API のエラー​

応答本文 messageHTTP エラーコード説明
Not Authorized - No Token401クエリにトークンが使用されていません。
Not Authorized - Invalid Token401クエリで使用されたアクセストークンを確認してください。
Forbidden403アカウントに問題がある可能性があります。アカウントページ を確認してください。

一部のケースでは、URL 制限付きのアクセストークンの使用も 403 エラーを引き起こすことがあります。詳細については、トークン管理ガイドの URL 制限 をご覧ください。
Not Found404クエリで使用されたエンドポイントを確認してください。
Not Found404クエリに検索テキストまたは構造化入力パラメータが提供されていません。
BBox is not valid. Must be an array of format [minX, minY, maxX, maxY]422bbox のフォーマットを確認してください。最初の座標ペアはボックスの南西隅を示し、2 番目のペアは北東隅を示している必要があります。
BBox {minX/maxX} value must be a number between -180 and 180422bbox の minX および maxX のフォーマットを確認してください。
BBox {minY/maxY} value must be a number between -90 and 90422bbox の minY および maxY のフォーマットを確認してください。
BBox {minX/minY} value cannot be greater than {maxX/maxY} value422bbox に使用される座標ペアの値を確認してください。
Type "{input}" is not a known type. Must be one of: country, region, place, district, postcode, locality, neighborhood, and address422クエリに使用されたtype を確認してください。
Stack "{input}" is not a known stack. Must be one of: …422country パラメータは有効な ISO 3166 alpha-2 国コードである必要があります。
Batch queries must include 50 queries or less422バッチジオコードリクエストには 50 件以下のクエリしか含めることができません。
Query too long {query length}/256 characters422クエリには 256 文字を超えることはできません。
Query too long - {query tokens length}/20 tokens422クエリには 20 単語境界で区切られた文字列 (トークン) を超えることはできません。
Proximity must be an array in the form [lon, lat]422proximity パラメータは 2 つのコンマで区切られた値を含む必要があります。
Proximity lon value must be a number between -180 and 180422proximity パラメータの経度値を確認してください。
Proximity lat value must be a number between -90 and 90422proximity パラメータの緯度値を確認してください。
"{input}" is not a valid language code422language パラメータは、有効な IETF 言語タグ で、必須の ISO 639-1 言語コード と、オプションで国またはスクリプトの IETF サブタグの 1 つまたは複数で構成されます。
options.language should be a list of no more than 20 languages422クエリの language パラメータには 20 の言語コードを含めることはできません。
options.language should be a list of unique language codes422language のコンマ区切りの値は一意である必要があります。
limit must be combined with a single type parameter when reverse geocoding422limit パラメータを含む リバースジオコーディングリクエスト の場合、type パラメータも使用する必要があります。
Rate limit exceeded429設定されたレート制限を超えました。詳細については、アカウントページ を確認してください。

ジオコーディングの制限とレート制限​

Geocoding API を保護し、サービスの安定性を最大化するために、Mapbox はGeocoding API リクエストのレート制限を行います。

  • デフォルトのGeocoding API レート制限は 1 分あたり 1000 リクエストですが、アカウントごとに調整可能です。Mapbox は、高トラフィックのアプリケーションを収容するため、または不正行為を防止するために、自動的に顧客のレート制限を調整する場合があります。
  • レート制限が達成された場合、HTTP エラーコード 429 が返されます。
  • もし、レート制限をの数を高くしたい場合は、お問い合わせください。.

Geocoding API の価格設定​

  • リクエスト ごとに請求されます
  • 料金ページの Search セクションで、Geocoding API リクエスト ごとの料金と割引をご確認ください。

Geocoding API の使用は API リクエスト 単位で計測されます。無料枠に含まれるリクエスト数や、それを超えた場合のリクエストごとの費用については、価格ページ に詳細があります。Geocoding API からの応答を使用する場合、Mapbox 地図と組み合わせて使用する必要があります。

オートコンプリートと価格設定​

Geocoding API の autocomplete パラメータはデフォルトで有効になっています。オートコンプリートを有効にして API を使用する場合、キー入力ごとに 1 つの API リクエストが蓄積される可能性があります。例えば、オートコンプリートを有効にして、ユーザーが検索バーにサーチ文字を入力するたびにGeocoding API リクエストを行うように設定した場合、ユーザーが「Cali」と入力して「California」を探すと、4 件のGeocoding API リクエスト が行われます。1 つのリクエストが各入力文字に対して発生します。

オートコンプリートが有効な場合にリクエスト数を減らすためには、特定の文字数が入力されるまで API リクエストを開始しないようにする方法があります。Geocoding API にはリクエスト制限を絞り込むためのパラメータはありませんが、Mapbox Search JS SDK を使用して検索構成を設定するか、アプリケーションに直接書き込むことができます。

バッチジオコーディングと価格設定​

バッチジオコーディング を使用することで、1 回のリクエストで複数のジオコーディングクエリを送信できます。バッチジオコーディングリクエストの各個別の検索は 1 つのリクエストとしてカウントされます。例えば、3 つの検索を含むリクエストは 3 件のリクエストとしてカウントされ、そのように請求されます。これらの 3 件のリクエストは、統計グラフ と請求に反映されます。

日本のジオコーディング​

Geocoding API には強力な日本の住所および場所検索が含まれています。新しい、高精度かつ高カバレッジの日本検索にアクセスするには、language および country パラメータの両方を設定する必要があります。

  • language=ja
  • country=jp

日本のジオコーディング応答は、他の国と同様に、住所構造の構成要素を定義するために同じ 地理的フィーチャータイプセクション を使用します (必要に応じて block コンポーネントが追加されます)。これらのフィーチャータイプは、日本の住所構造の以下の等価物を表しています。

地理的フィーチャータイプ日本の住所等価物
blockブロック
neighborhood丁目
locality大字
place市
region県

日本のジオコーディング応答には、日本語の読みを示すユニークな feature.properties.reading オブジェクトも含まれています。それぞれのスクリプトタイプに対して以下の例があります。

{
  "ja-Kana": "ヤマグチケンシモノセキシシンアカダニシマチ",
  "ja-Latn": "yamaguchiken shimonosekishi shinakadanishimachi"
}
追加の開発者リソース
このpageは役に立ちましたか？