Search Box API
Mapbox Search Box API は、コネクテッドカー、マイクロモビリティサービス、配送アプリなどにインタラクティブな場所検索を追加する最も簡単な方法です。Search Box APIは、住所、場所、そして興味のあるポイント（POI）の検索にインタラクティブな場所検索やスタンドアロン検索クエリをサポートします。
Search APIクエリを試し、地図上で結果を確認します。
日本語検索と日本の場所検索について学びます。
Mapboxの検索クライアントライブラリとSDKは、Search Box APIの力をインタラクティブ検索UIと組み合わせて提供します。Webまたはモバイルアプリケーションに強力な場所検索を追加する方法を学びます:
- Web用、React用、またはNode用のMapbox Search JS
- Android用Mapbox Search SDK
- iOS用Mapbox Search SDK
Search Box APIエンドポイント
Search Box APIは、さまざまな場所の検索ユースケースをサポートするために次のエンドポイントを提供します：
/suggestおよび/retrieveエンドポイントは、アプリのインタラクティブ検索を構築するために一緒に使用されます。/forwardエンドポイントは、検索リクエストを作成するために使用されます。/categoryエンドポイントは、カテゴリ検索を作成するために使用されます。/reverseエンドポイントは、逆引き検索を作成するために使用されます。
インタラクティブ検索
Search Box API を使用すると、開発者はユーザーが住所だけでなく、興味のあるポイント（POI）、POIのカテゴリ、通り名、近隣、地域、場所名、地区、郵便番号、地域、国を見つけやすくするオートコンプリート検索体験を作成できます。
インタラクティブ検索体験をエンドユーザーに提供するために、/suggestエンドポイントは/retrieveエンドポイントと組み合わせて使用されます。アプリケーション内で、ユーザーの検索クエリを/suggestエンドポイントに送信して、与えられた検索クエリに対する候補結果を取得します。
ユーザーがアプリケーションUIで結果を選択した場合、選択に関する詳細情報を取得するために/retrieveリクエストをトリガーする必要があります。
候補結果を取得する
このエンドポイントは、ユーザーのクエリに対する候補検索結果のリストを提供します。このエンドポイントと/retrieveエンドポイントを組み合わせることで、アプリケーションにオートコンプリート検索機能を追加できます。
| 必須のパラメータ | 型 | 説明 |
|---|---|---|
q | string | ユーザーのクエリ文字列。クエリは256文字に制限されています。 |
access_token | string | デフォルトのパーミッションを持つMapboxのアクセス トークン。 |
session_token | string | 請求目的のために一連のリクエストをグループ化する顧客提供のセッショントークン値。UUIDv4を推奨します。セッションベースの請求方法でsession_tokenがどのように使用されるかについての詳細は、このドキュメントのセッションベースの請求セクションを参照してください。 |
このエンドポイントへのクエリ結果は次のオプションパラメータでさらに絞り込むことができます：
| オプションパラメータ | 型 | 説明 |
|---|---|---|
language | string | 返される言語のISO言語コード。指定されない場合、デフォルトは英語です。 |
limit | integer | 戻り値の結果数（最大10）。 |
proximity | string | 特定の場所に近い結果を重視するようにレスポンスをバイアスします。ユーザーのIP位置に最も近い結果を取得するためにipを提供するか、経度,緯度の順に2つのカンマ区切りの座標を提供します。指定されていない場合、デフォルトはIP近接です。proximityおよびoriginの両方が提供されている場合、originはルートのターゲットとして解釈され、proximityは現在のユーザー位置を示します。 |
origin | string | 2つのカンマ区切りの座標（経度,緯度の順）として提供される、距離の計算元となる場所。proximityおよびoriginの両方が提供されている場合、originはルートのターゲットとして解釈され、proximityは現在のユーザー位置を示します。このパラメータはターゲットまでの距離の推定に必要ですが、追加の遅延が発生する可能性があります。 |
bbox | string | 提供されたバウンディングボックス内に制限される結果のみ。バウンディングボックスは4つの数字をカンマで区切って提供する必要があります（最小経度、最小緯度、最大経度、最大緯度の順）。バウンディングボックスは180度子午線を越えることはできません。 |
navigation_profile | string | 使用するナビゲーションルーティングプロファイル。利用可能なプロファイルは：driving、walking、cycling。 |
route | string | 検索に使用するルートを記述するポリラインエンコードされたラインストリング。このパラメータはルートに沿った検索を有効にします。polyline5およびpolyline6の精度が受け入れられますが、route_geometryパラメータを使用して指定する必要があります。 |
route_geometry | string | その精度を記述するルートポリラインと同時に渡されます。オプションはpolylineまたはpolyline6です。このパラメータがrouteと一緒に提供されていない場合、デフォルトはpolylineです。提供されたrouteに対して正しいroute_geometryを含めることで正確な結果が得られます。 |
sar_type | string | ユーザーがよりコストの高いルートに沿った検索リクエストを行うことを意図していることを示します。routeが含まれている場合に含める必要があり、値はisochroneになります。 |
time_deviation | number | ルートからの最大迂回時間（推定分）。 |
eta_type | string | originまたはproximityで指定された場所からの到着時間（ETA）を推定するために使用されます。このパラメータの唯一の許可される値はnavigationです。このパラメータ、およびnavigation_profileおよびorigin/proximityと共に、ETA計算に必要です。ETA計算は追加の遅延を引き起こします。 |
country | string | ISO 3166 alpha 2 の国コードのカンマ区切りリスト。 |
types | string | 特定のタイプの機能に結果を限定し、カンマ区切りリストとして提供します。タイプ名の一つ以上をカンマ区切りのリストとして渡します。タイプが指定されない場合、すべての可能なタイプが返される可能性があります。利用可能なタイプは: country、region、postcode、district、place、city、locality、neighborhood、street、address、poi、およびcategory。これらのタイプについての詳細は行政単位の種類セクションを参照してください。 |
poi_category | string | カンマ区切りリストとして提供された1つ以上のカテゴリに属する結果に制限します。 |
poi_category_exclusions | string | カンマ区切りリストとして提供されたカテゴリに属していないPOI結果に限定するカテゴリ名のカンマ区切りリスト。 |
例: 候補結果を取得するリクエスト
# limit=1でミシガンスタジアムを検索
$curl "https://api.mapbox.com/search/searchbox/v1/suggest?q=Michigan%20Stadium&language=en&limit=1&session_token=[GENERATED-UUID]&proximity=-83.748708,42.265837&country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
レスポンス: 候補結果を取得する
/suggest エンドポイントへのリクエストのレスポンスは、JSON 提案オブジェクトの配列です。提案には、結果の名前、住所情報、地理的コンテキスト、および使用可能な場合は追加のメタデータ（例えば、近接点への距離）が含まれます。地理的座標は含まれていません。座標を取得するには、/suggest結果に提供されたmapbox_idを使って/retrieveエンドポイントへのコールを行ってください。
limit パラメータを使用して、最大 10 件の結果数を増やすことができます。ページ分割は利用できませんが、この機能は後のリリースで追加される可能性があります。検索結果の順序をカスタマイズするオプションはありません。
各結果オブジェクトには次のプロパティが含まれています：
| プロパティ | タイプ | 説明 |
|---|---|---|
suggestions | array of objects | 返された提案オブジェクト。 各提案オブジェクトに含まれるプロパティに関する詳細は以下の表を参照してください。 |
attribution | string | 結果の帰属データ。 |
各提案オブジェクトには次のプロパティが含まれています：
| プロパティ | タイプ | 説明 |
|---|---|---|
name | string | [required] この機能の名前。 |
name_preferred | string | [optional] name とは異なる場合の、機能の優先名。 |
mapbox_id | string | [required] フルフィーチャの詳細を取得するために /retrieve で使用する ID。 |
feature_type | string | [required] 結果のタイプ。 POI（ポイントオブインタレスト）の場合、これは poi になります。カテゴリの結果の場合、これは category になります。住所タイプの結果の場合、グローバルコンテキスト階層が使用されます（country、region、postcode、district、place、locality、neighborhood、address）。これらのタイプに関する詳細については行政単位の種類セクションを参照してください。 |
address | string | [optional] 住所および通り番号を含む結果の住所。 |
full_address | string | [optional] address および place_formatted を連結した結果のフル住所。 |
place_formatted | string | [required] 場所、地域、国、郵便番号から成る結果コンテキストのフォーマット済み文字列。 |
context | object | [required] 機能のコンテキスト。 このコンテキストには、以下の行政単位の種類に従うレイヤがあります。 |
context.country | object | [optional] 結果の国。このレイヤには、プロパティ id、name、country_code（ISO_3166_1 alpha 2 コード）、country_code_alpha_3（ISO_3166_1 alpha 3 コード）が含まれます。 |
context.region | object | [optional] 結果の地域。このレイヤには、プロパティ id、name、region_code、および region_code_full（ISO_3166_2 コード）が含まれます。 |
context.postcode | object | [optional] 結果の郵便番号。このレイヤには、プロパティ id および name が含まれます。 |
context.district | object | [optional] 結果の地区。このレイヤには、プロパティ id および name が含まれます。 |
context.place | object | [optional] 結果の場所。このレイヤには、プロパティ id および name が含まれます。 |
context.locality | object | [optional] 結果の地域。このレイヤには、プロパティ id および name が含まれます。 |
context.neighborhood | object | [optional] 結果の近隣。このレイヤには、プロパティ id および name が含まれます。 |
context.address | object | [optional] 通り番号および街路名を含む結果の住所。このレイヤには、プロパティ id、name、address_number、および street_name が含まれます。 |
context.street | object | [optional] 結果の通り。このレイヤには、プロパティ id および name が含まれます。 |
language | string | [required] 結果の言語を示す IETF 言語タグ。 |
maki | string | [optional] この結果に使用する関連するMakiアイコン を表す文字列。 |
poi_category | array | [optional] 結果がPOIなら、その結果が属するPOIカテゴリを含む配列。 |
poi_category_ids | array | [optional] 結果がPOIなら、その結果が属する標準的なPOIカテゴリIDを含む配列。 |
brand | array | [optional] 結果がPOIであり、適用可能な場合に関連する商業ブランド名を含む配列。 |
brand_id | array | [optional] 結果がPOIであり、適用可能な場合の商業ブランドの標準IDを含む配列。 |
external_ids | object | [optional] 外部データベースで見つけた機能のIDを含むオブジェクト。キーがデータソース名で、値がIDです。 |
metadata | object | [optional] 機能に適用可能な場合、追加のメタデータを含むオブジェクト。 |
distance | number | [optional] origin ロケーションからの概算距離（メートル単位）。origin が提供されていない場合、proximity ロケーションへの概算距離（メートル単位）。 |
eta | number | [optional] origin ポイントからフィーチャへの推定到着時刻（ETA）。origin が提供されていない場合、proximity ポイントからフィーチャへの推定到着時刻（ETA）。このパラメータがeta_type、navigation_profile、およびorigin/proximityと共に使用されている場合にのみ提供。住所が道路網上になければ、ETAは提供されません。 |
added_distance | number | [optional] 指定された提案を含む入力ルートに追加される距離（メートル単位）。 |
added_time | number | [optional] 指定された提案を含む入力ルートに追加される推定時間（分単位）。 |
例: 候補結果を取得するレスポンス
{
"suggestions": [
{
"name": "Michigan Stadium",
"mapbox_id": "例のID",
"feature_type": "poi",
"address": "1201 S Main St",
"full_address": "1201 S Main St, Ann Arbor, Michigan 48104, United States of America",
"place_formatted": "Ann Arbor, Michigan 48104, United States of America",
"context": {
"country": {
"name": "United States of America",
"country_code": "US",
"country_code_alpha_3": "USA"
},
"region": {
"name": "Michigan",
"region_code": "MI",
"region_code_full": "US-MI"
},
"postcode": { "name": "48104" },
"place": { "name": "Ann Arbor" },
"neighborhood": { "name": "South Main" },
"street": { "name": "s main st" }
},
"language": "en",
"maki": "marker",
"poi_category": ["track", "sports"],
"poi_category_ids": ["track", "sports"],
"external_ids": {
"safegraph": "例のID",
"foursquare": "例のID"
},
"metadata": {}
}
],
"attribution": "© 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/)"
}
提案されたフィーチャの取得
/retrieve エンドポイントは、フィーチャについての地理座標を含む詳細情報を提供します。検索セッションでは、ユーザーが /suggest エンドポイントから提供された候補結果からアイテムを選択する際に、このエンドポイントが呼び出されます。詳細については、このドキュメントの提案されたフィーチャの取得セクションを参照してください。
/suggest エンドポイントへの成功したコールの後、提案の mapbox_id プロパティに含まれる ID を使用してフィーチャの詳細情報を取得します。
| 必須のパラメータ | 型 | 説明 |
|---|---|---|
access_token | string | デフォルトのパーミッションを持つMapboxのアクセス トークン。 |
session_token | string | 請求目的のために一連のリクエストをグループ化する顧客提供のセッショントークン値。UUIDv4を推奨します。セッションベースの請求方法でsession_tokenがどのように使用されるかについての詳細は、このドキュメントのセッションベースの請求セクションを参照してください。 |
| オプションパラメータ | 型 | 説明 |
|---|---|---|
language | string | 返される言語のISO言語コード。指定されない場合、デフォルトは英語です。 |
attribute_sets | string | メタデータのレベルを説明する属性セットのカンマ区切りリスト。 有効なオプションは basic、photos、venue、visit です。 |
例: 提案されたフィーチャを取得するリクエスト
# 提案されたフィーチャを取得する
$curl "https://api.mapbox.com/search/searchbox/v1/retrieve/{id}?session_token=[GENERATED-UUID]&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
レスポンス: 提案されたフィーチャを取得する
/retrieve エンドポイントは GeoJSON FeatureCollection を返します。
| プロパティ | タイプ | 説明 |
|---|---|---|
type | string | 常に "FeatureCollection" となります。 |
features | array of objects | 返されたフィーチャオブジェクト。各フィーチャオブジェクトに含まれるプロパティの詳細については以下の表を参照してください。 |
attribution | string | 結果の帰属データ。 |
各フィーチャ内のプロパティは次の通りです：
| プロパティ | タイプ | 説明 |
|---|---|---|
type | string | [required] 常に "Feature" となります。 |
geometry | object | [required] 返されたフィーチャの空間ジオメトリを説明するオブジェクト。 |
geometry.coordinates | array | [required] フィーチャの座標、[経度,緯度] のフォーマットで提供。 |
geometry.type | string | [required] 常に "Point" となります。 |
properties | object | [required] 返されたフィーチャに関連する特定のプロパティ。 |
properties.name | string | [required] フィーチャの名前。 |
properties.name_preferred | string | [optional] properties.name とは異なる場合のフィーチャの優先名。 |
properties.mapbox_id | string | [required] フィーチャに関連するID。 |
properties.feature_type | string | [required] 結果のタイプ。POIの場合、これは poi になります。住所タイプの結果の場合、グローバルコンテキスト階層が使用されます（country、region、postcode、district、place、locality、neighborhood、address）。これらのタイプについての詳細は行政単位の種類セクションを参照してください。 |
properties.address | string | [optional] 通り番号および街路名を含む結果の住所。 |
properties.full_address | string | [optional] properties.address および properties.place_formatted を連結した結果のフル住所。 |
properties.place_formatted | string | [optional] 場所、地域、国、郵便番号から成る結果コンテキストのフォーマット済み文字列。 address の後に結果が続く部分を示します。 |
properties.context | object | [required] フィーチャのコンテキスト。 |
properties.context.country | object | [optional] 結果の国。このレイヤには、プロパティ id、name、country_code（ISO_3166_1 alpha 2 コード）、country_code_alpha_3（ISO_3166_1 alpha 3 コード）が含まれます。 |
properties.context.region | object | [optional] 結果の地域。このレイヤには、プロパティ id、name、region_code、および region_code_full（ISO_3166_2 コード）が含まれます。 |
properties.context.postcode | object | [optional] 結果の郵便番号。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.district | object | [optional] 結果の地区。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.place | object | [optional] 結果の場所。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.locality | object | [optional] 結果の地域。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.neighborhood | object | [optional] 結果の近隣。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.address | object | [optional] 通り番号および街路名を含む結果の住所。このレイヤには、プロパティ id、name、address_number、および street_name が含まれます。 |
properties.context.street | object | [optional] 結果の通り。このレイヤには、プロパティ id および name が含まれます。 |
properties.coordinates | object | [required] 結果の地理座標。 |
properties.coordinates.longitude | number | [required] 結果の経度座標。 |
properties.coordinates.latitude | number | [required] 結果の緯度座標。 |
properties.coordinates.accuracy | string | [optional] 結果の地理座標の精度。これは住所タイプの結果のみ利用可能で、オプションは rooftop、parcel、point、interpolated、intersection、approximate、および street です。 |
properties.coordinates.routable_points | array | [optional] フィーチャのルート可能なポイントに関する情報を含むオブジェクトの配列。ルート可能なポイントオブジェクトには、プロパティ name、latitude、longitude およびオプションの note が含まれます。 |
properties.bbox | array | [optional] バウンディングボックス。形式は 最小経度,最小緯度,最大経度,最大緯度。 |
properties.language | string | [optional] 結果の言語を示すIETF言語タグ。 |
properties.maki | string | [optional] 結果に使用する関連するMakiアイコンを表す文字列。 |
properties.poi_category | array | [optional] 結果がPOIなら、その結果が属するPOIカテゴリを含む配列。 |
properties.poi_category_ids | array | [optional] 結果がPOIなら、その結果が属する標準的なPOIカテゴリIDを含む配列。 |
properties.brand | array | [optional] 結果がPOIであり、適用可能な場合に関連する商業ブランド名を含む配列。 |
properties.brand_id | array | [optional] 結果がPOIであり、適用可能な場合の商業ブランドの標準IDを含む配列。 |
properties.external_ids | object | [optional] 外部データベースで見つけた機能のIDを含むオブジェクト。キーがデータソース名で、値がIDです。 |
properties.metadata | object | [optional] 機能に適用可能な場合、追加のメタデータを含むオブジェクト。 |
例: 提案されたフィーチャを取得するレスポンス
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": { "coordinates": [-83.748708, 42.265837], "type": "Point" },
"properties": {
"name": "Michigan Stadium",
"mapbox_id": "例のID",
"feature_type": "poi",
"address": "1201 S Main St",
"full_address": "1201 S Main St, Ann Arbor, Michigan 48104, United States of America",
"place_formatted": "Ann Arbor, Michigan 48104, United States of America",
"context": {
"country": {
"name": "United States of America",
"country_code": "US",
"country_code_alpha_3": "USA"
},
"region": {
"name": "Michigan",
"region_code": "MI",
"region_code_full": "US-MI"
},
"postcode": { "name": "48104" },
"place": { "name": "Ann Arbor" },
"neighborhood": { "name": "South Main" },
"street": { "name": "s main st" }
},
"coordinates": {
"latitude": 42.265837,
"longitude": -83.748708,
"routable_points": [
{
"name": "default",
"latitude": 42.265837,
"longitude": -83.748708
}
]
},
"maki": "marker",
"poi_category": ["track", "sports"],
"poi_category_ids": ["track", "sports"],
"external_ids": {
"safegraph": "例のID",
"foursquare": "例のID"
},
"metadata": {}
}
}
],
"attribution": "© 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/)"
}
検索リクエスト
Search Box API を使用すると、開発者は検索リクエストを送信して関連する結果を取得できます。開発者は /forward エンドポイントを使用して検索リクエストを作成し、座標とメタデータを含む検索結果のリストを取得できます。インタラクティブ検索とは対照的に、/forward エンドポイントはタイプアヘッドの候補を提供せず、関連する検索結果のみを提供します。
検索結果を取得する
| 必須のパラメータ | 型 | 説明 |
|---|---|---|
q | string | ユーザーのクエリ文字列。 クエリ文字列は 256 文字に制限されています。 |
access_token | string | デフォルトのパーミッションを持つMapboxのアクセス トークン。 |
このエンドポイントへのクエリ結果は次のオプションパラメータでさらに絞り込むことができます：
| オプションパラメータ | 型 | 説明 |
|---|---|---|
language | string | 返される言語のISO言語コード。指定されない場合、デフォルトは英語です。 |
limit | integer | 戻り値の結果数（最大10）。 |
proximity | string | 特定の場所に近い結果を重視するようにレスポンスをバイアスします。ユーザーのIP位置に最も近い結果を取得するためにipを提供するか、経度,緯度の順に2つのカンマ区切りの座標を提供します。指定されていない場合、デフォルトはIP近接です。proximityおよびoriginの両方が提供されている場合、originはルートのターゲットとして解釈され、proximityは現在のユーザー位置を示します。 |
bbox | string | 提供されたバウンディングボックス内に制限される結果のみ。バウンディングボックスは4つの数字をカンマで区切って提供する必要があります（最小経度、最小緯度、最大経度、最大緯度の順）。バウンディングボックスは180度子午線を越えることはできません。 |
route | string | 検索に使用するルートを記述するポリラインエンコードされたラインストリング。このパラメータはルートに沿った検索を有効にします。polyline5およびpolyline6の精度が受け入れられますが、route_geometryパラメータを使用して指定する必要があります。 |
route_geometry | string | その精度を記述するルートポリラインと同時に渡されます。オプションはpolylineまたはpolyline6です。このパラメータがrouteと一緒に提供されていない場合、デフォルトはpolylineです。提供されたrouteに対して正しいroute_geometryを含めることで正確な結果が得られます。 |
sar_type | string | ユーザーがよりコストの高いルートに沿った検索リクエストを行うことを意図していることを示します。routeが含まれている場合に含める必要があり、値はisochroneになります。 |
time_deviation | number | ルートからの最大迂回時間（推定分）。 |
eta_type | string | originまたはproximityで指定された場所からの到着時間（ETA）を推定するために使用されます。このパラメータの唯一の許可される値はnavigationです。このパラメータ、およびnavigation_profileおよびorigin/proximityと共に、ETA計算に必要です。ETA計算は追加の遅延を引き起こします。 |
country | string | ISO 3166 alpha 2 の国コードのカンマ区切りリスト。 |
types | string | 特定のタイプの機能に結果を限定し、カンマ区切りリストとして提供します。タイプ名の一つ以上をカンマ区切りのリストとして渡します。タイプが指定されない場合、すべての可能なタイプが返される可能性があります。利用可能なタイプは: country、region、postcode、district、place、city、locality、neighborhood、street、address、poi、およびcategory。これらのタイプについての詳細は行政単位の種類セクションを参照してください。 |
poi_category | string | カンマ区切りリストとして提供された1つ以上のカテゴリに属する結果に制限します。 |
poi_category_exclusions | string | カンマ区切りリストとして提供されたカテゴリに属していないPOI結果に限定するカテゴリ名のカンマ区切りリスト。 |
例: 検索リクエスト
$curl "https://api.mapbox.com/search/searchbox/v1/forward?q=34170%20Gannon%20Terrace&language=en&limit=1&proximity=-121.90662,37.42827&country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
$curl "https://api.mapbox.com/search/searchbox/v1/forward?q=新橋一丁目十番一号,東京都港区新橋1丁目10番1号&language=ja&limit=1&proximity=13.38333,52.51667&country=JP&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
レスポンス: 検索リクエスト
/forwardエンドポイントへのリクエストのレスポンスはGeoJSON FeatureCollection です。
limitパラメータを使用して、最大10件の結果数を増やすことができます。ページ分割は利用できませんが、この機能は後のリリースで追加される可能性があります。検索結果の順序をカスタマイズするオプションはありません。
| プロパティ | タイプ | 説明 |
|---|---|---|
type | string | 常に "FeatureCollection" となります。 |
features | array of objects | 返されたフィーチャオブジェクト。各フィーチャオブジェクトに含まれるプロパティの詳細については以下の表を参照してください。 |
attribution | string | 結果の帰属データ。 |
各フィーチャ内のプロパティは次の通りです：
| プロパティ | タイプ | 説明 |
|---|---|---|
type | string | [required] 常に "Feature" となります。 |
geometry | object | [required] 返されたフィーチャの空間ジオメトリを説明するオブジェクト。 |
geometry.coordinates | array | [required] フィーチャの座標、[経度,緯度] のフォーマットで提供。 |
geometry.type | string | [required] 常に "Point" となります。 |
properties | object | [required] 返されたフィーチャに関連する特定のプロパティ。 |
properties.name | string | [required] フィーチャの名前。 |
properties.name_preferred | string | [optional] properties.name とは異なる場合のフィーチャの優先名。 |
properties.mapbox_id | string | [required] フィーチャに関連するID。 |
properties.feature_type | string | [required] 結果のタイプ。POIの場合、これは poi になります。住所タイプの結果の場合、グローバルコンテキスト階層が使用されます（country、region、postcode、district、place、locality、neighborhood、address）。これらのタイプについての詳細は行政単位の種類セクションを参照してください。 |
properties.address | string | [optional] 通り番号および街路名を含む結果の住所。 |
properties.full_address | string | [optional] properties.address および properties.place_formatted を連結した結果のフル住所。 |
properties.place_formatted | string | [optional] 場所、地域、国、郵便番号から成る結果コンテキストのフォーマット済み文字列。 address の後に結果が続く部分を示します。 |
properties.context | object | [required] フィーチャのコンテキスト。 |
properties.context.country | object | [optional] 結果の国。このレイヤには、プロパティ id、name、country_code（ISO_3166_1 alpha 2 コード）、country_code_alpha_3（ISO_3166_1 alpha 3 コード）が含まれます。 |
properties.context.region | object | [optional] 結果の地域。このレイヤには、プロパティ id、name、region_code、および region_code_full（ISO_3166_2 コード）が含まれます。 |
properties.context.postcode | object | [optional] 結果の郵便番号。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.district | object | [optional] 結果の地区。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.place | object | [optional] 結果の場所。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.locality | object | [optional] 結果の地域。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.neighborhood | object | [optional] 結果の近隣。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.address | object | [optional] 通り番号および街路名を含む結果の住所。このレイヤには、プロパティ id 、name、address_number 、および street_nameが含まれます。 |
properties.context.street | object | [optional] 結果の通り。このレイヤには、プロパティ id および name が含まれます。 |
properties.coordinates | object | [required] 結果の地理座標。 |
properties.coordinates.longitude | number | [required] 経度座標。 |
properties.coordinates.latitude | number | [required] 緯度座標。 |
properties.coordinates.accuracy | string | [optional] 座標の精度。住所タイプの結果のみで利用可能であり、オプションは rooftop、parcel 、point 、interpolated、 intersection 、approximate、および street です。 |
properties.coordinates.routable_points | array | [optional] フィーチャのルート可能なポイントに関する情報を含むオブジェクトの配列。ルート可能なポイントオブジェクトには、プロパティ name 、latitude、 longitudeおよびオプションの noteが含まれます。 |
properties.bbox | array | [optional] バウンディングボックス。形式は 最小経度、最小緯度、最大経度、最大緯度。 |
properties.language | string | [optional] 結果の言語を示すIETF言語タグ。 |
properties.maki | string | [optional] 関連するMakiアイコンを表す文字列。 |
properties.poi_category | array | [optional] 結果がPOIなら、その結果が属するPOIカテゴリを含む配列。 |
properties.poi_category_ids | array | [optional] 結果がPOIなら、その結果が属する標準的なPOIカテゴリIDを含む配列。 |
properties.brand | array | [optional] 結果がPOIであり、適用可能な場合に関連する商業ブランド名を含む配列。 |
properties.brand_id | array | [optional] 結果がPOIであり、適用可能な場合の商業ブランドの標準IDを含む配列。 |
properties.external_ids | object | [optional] 外部データベースで見つけた機能のIDを含むオブジェクト。キーがデータソース名で、値がIDです。 |
properties.metadata | object | [optional] 機能に適用可能な場合、追加のメタデータを含むオブジェクト。 |
例: 検索リクエストのレスポンス
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [-122.059632, 37.561526],
"type": "Point"
},
"properties": {
"name": "34170 Gannon Terrace",
"mapbox_id": "dXJuOm1ieGFkcjpiNjg2YTY2MS0xZTU4LTRiYmEtYTJhNC1mODdkNTRhNjczZWI",
"feature_type": "address",
"address": "34170 Gannon Terrace",
"full_address": "34170 Gannon Terrace, Fremont, California 94555, United States",
"place_formatted": "Fremont, California 94555, United States",
"context": {
"country": {
"id": "dXJuOm1ieHBsYzpJdXc",
"name": "United States",
"country_code": "US",
"country_code_alpha_3": "USA"
},
"region": {
"id": "dXJuOm1ieHBsYzpCbVRz",
"name": "California",
"region_code": "CA",
"region_code_full": "US-CA"
},
"postcode": {
"id": "dXJuOm1ieHBsYzpFclN1N0E",
"name": "94555"
},
"district": {
"id": "dXJuOm1ieHBsYzpBMGJz",
"name": "Alameda County"
},
"place": {
"id": "dXJuOm1ieHBsYzpCdzdvN0E",
"name": "Fremont"
},
"neighborhood": {
"id": "dXJuOm1ieHBsYzo2dXpz",
"name": "Ardenwood"
},
"address": {
"id": "dXJuOm1ieGFkcjpiNjg2YTY2MS0xZTU4LTRiYmEtYTJhNC1mODdkNTRhNjczZWI",
"name": "34170 Gannon Terrace",
```json
"address_number": "34170",
"street_name": "gannon terrace"
},
"street": {
"id": "dXJuOm1ieGFkcjpiNjg2YTY2MS0xZTU4LTRiYmEtYTJhNC1mODdkNTRhNjczZWI",
"name": "gannon terrace"
}
},
"coordinates": {
"latitude": 37.561526,
"longitude": -122.059632,
"accuracy": "rooftop",
"routable_points": [
{
"name": "default",
"latitude": 37.561366,
"longitude": -122.05968
}
]
},
"language": "en",
"maki": "marker",
"external_ids": {},
"metadata": {}
}
}
],
"attribution": "© 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/)"
}
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [139.7596694, 35.6674972],
"type": "Point"
},
"properties": {
"name": "〒105-0004 東京都港区新橋1丁目10番1号",
"feature_type": "address",
"address": "〒105-0004 東京都港区新橋1丁目10番1号",
"full_address": "〒105-0004 東京都港区新橋1丁目10番1号, 〒105-0004 東京都港区新橋1丁目10番1号",
"place_formatted": "〒105-0004 東京都港区新橋1丁目10番1号",
"context": {
"postcode": {
"name": "105-0004"
},
"block": {
"name": "10"
},
"address": {
"id": "address",
"name": "〒105-0004 東京都港区新橋1丁目10番1号",
"address_number": "10番1号",
"street_name": "新橋1丁目"
},
"street": {
"name": "新橋1丁目"
}
},
"coordinates": {
"latitude": 35.6674972,
"longitude": 139.7596694,
"accuracy": "rooftop"
},
"language": "ja",
"maki": "marker",
"external_ids": {},
"metadata": {
"reading": {
"ja_kana": "トウキョウトミナトクシンバシ",
"ja_latin": "toukyouto minatoku shinbashi"
}
}
}
}
],
"attribution": "© 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/)"
}
カテゴリ検索
カテゴリ検索を使用すると、特定の場所またはルートに沿ったコーヒーショップ、ホテル、本屋などのカテゴリ全体をブラウズできます。
/category エンドポイントは、指定された場所の POI (興味のあるポイント) のリストを提供します。検索ユースケースでは、このエンドポイントを使用して、たとえば、近くのすべてのコーヒーショップを表示するコーヒーボタンのような特定のカテゴリの検索を実行するためのホットボタンを作成します。
カテゴリでPOIを取得する
カテゴリでフィルタリングされたPOI（興味のあるポイント）を取得する場合などにカテゴリ検索エンドポイントを使用します。このエンドポイントは指定されたカテゴリのPOIのみを返します。
/category エンドポイントの使用例：
- あなたの周りの食べ物を見つける (
food_and_drink) - インド料理レストランを見つける (
indian_restaurant) - ルートに沿ったガソリンスタンドを見つける (
gas_station)
| 必須のパラメータ | 型 | 説明 |
|---|---|---|
access_token | string | デフォルトのパーミッションを持つMapboxのアクセス トークン。 |
このエンドポイントへのクエリ結果は次のオプションパラメータでさらに絞り込むことができます：
| オプションパラメータ | 型 | 説明 |
|---|---|---|
language | string | 返される言語のISO言語コード。指定されない場合、デフォルトは英語です。 |
limit | integer | 戻り値の結果数（最大25）。 |
proximity | string | 特定の場所に近い結果を重視するようにレスポンスをバイアスします。ユーザーのIP位置に最も近い結果を取得するためにipを提供するか、経度,緯度の順に2つのカンマ区切りの座標を提供します。指定されていない場合、デフォルトはIP近接です。proximityおよびoriginの両方が提供されている場合、originはルートのターゲットとして解釈され、proximityは現在のユーザー位置を示します。 |
origin | string | 2つのカンマ区切りの座標（経度,緯度の順）として提供される、距離の計算元となる場所。proximityおよびoriginの両方が提供されている場合、originはルートのターゲットとして解釈され、proximityは現在のユーザー位置を示します。このパラメータはターゲットまでの距離の推定に必要ですが、追加の遅延が発生する可能性があります。 |
bbox | string | 提供されたバウンディングボックス内に制限される結果のみを返します。バウンディングボックスは4つの数字をカンマで区切って提供する必要があります（最小経度、最小緯度、最大経度、最大緯度の順）。バウンディングボックスは180度子午線を越えることはできません。 |
navigation_profile | string | 使用するナビゲーションルーティングプロファイル。利用可能なプロファイルは：driving、walking、cycling。 |
route | string | 検索に使用するルートを記述するポリラインエンコードされたラインストリング。このパラメータはルートに沿った検索を有効にします。polyline5およびpolyline6の精度が受け入れられますが、route_geometryパラメータを使用して指定する必要があります。 |
route_geometry | string | その精度を記述するルートポリラインと同時に渡されます。オプションはpolylineまたはpolyline6です。このパラメータがrouteと一緒に提供されていない場合、デフォルトはpolylineです。提供されたrouteに対して正しいroute_geometryを含めることで正確な結果が得られます。 |
sar_type | string | ユーザーがよりコストの高いルートに沿った検索リクエストを行うことを意図していることを示します。routeが含まれている場合に含める必要があり、値はisochroneになります。 |
time_deviation | number | ルートからの最大迂回時間（推定分）。 |
eta_type | string | originまたはproximityで指定された場所からの到着時間（ETA）を推定するために使用されます。このパラメータの唯一の許可される値はnavigationです。このパラメータ、およびnavigation_profileおよびorigin/proximityと共に、ETA計算に必要です。ETA計算は追加の遅延を引き起こします。 |
country | string | ISO 3166 alpha 2 の国コードのカンマ区切りリスト。 |
types | string | 特定のタイプの機能に結果を限定し、カンマ区切りリストとして提供します。タイプ名の一つ以上をカンマ区切りのリストとして渡します。タイプが指定されない場合、すべての可能なタイプが返される可能性があります。利用可能なタイプは: country、region、postcode、district、place、city、locality、neighborhood、street、address、poi、およびcategory。これらのタイプについての詳細は行政単位の種類セクションを参照してください。 |
poi_category_exclusions | string | カンマ区切りリストとして提供されたカテゴリに属していないPOI結果に限定するカテゴリ名のカンマ区切りリスト。 |
例: カテゴリでPOIを検索
# `coffee` カテゴリ内のPOIを検索
$curl -X GET "https://api.mapbox.com/search/searchbox/v1/category/coffee?access_token=YOUR_MAPBOX_ACCESS_TOKEN&language=en&limit=5&proximity=-122.41%2C39&bbox=-124.35526789303981%2C38.41262975705166%2C-120.52250410696067%2C39.54169087094499"
レスポンス: カテゴリでPOIを検索
/category エンドポイントのレスポンスは GeoJSON FeatureCollection です。
| プロパティ | タイプ | 説明 |
|---|---|---|
type | string | 常に "FeatureCollection" となります。 |
features | array of objects | 返されたフィーチャオブジェクト。各フィーチャオブジェクトに含まれるプロパティの詳細については以下の表を参照してください。 |
attribution | string | 結果の帰属データ。 |
各フィーチャ内のプロパティは次の通りです：
| プロパティ | タイプ | 説明 |
|---|---|---|
type | string | [required] 常に "Feature" となります。 |
geometry | object | [required] 返されたフィーチャの空間ジオメトリを説明するオブジェクト。 |
geometry.coordinates | array | [required] フィーチャの座標、[経度,緯度] のフォーマットで提供。 |
geometry.type | string | [required] 常に "Point" となります。 |
properties | object | [required] 返されたフィーチャに関連する特定のプロパティ。 |
properties.name | string | [required] フィーチャの名前。 |
properties.name_preferred | string | [optional] properties.name とは異なる場合のフィーチャの優先名。 |
properties.mapbox_id | string | [required] フィーチャに関連するID。 |
properties.feature_type | string | [required] 結果のタイプ。POIの場合、これは poi になります。カテゴリータイプの結果の場合、グローバルコンテキスト階層が使用されます（country、region、postcode、district、place、locality、neighborhood、address）。これらのタイプについての詳細は行政単位の種類セクションを参照してください。 |
properties.address | string | [optional] 通り番号および街路名を含む結果の住所。 |
properties.full_address | string | [optional] properties.address および properties.place_formatted を連結した結果のフル住所。 |
properties.place_formatted | string | [optional] 場所、地域、国、郵便番号から成る結果コンテキストのフォーマット済み文字列。 address の後に結果が続く部分を示します。 |
properties.context | object | [required] フィーチャのコンテキスト。 |
properties.context.country | object | [optional] 結果の国。このレイヤには、プロパティ id、name、country_code（ISO_3166_1 alpha 2 コード）、country_code_alpha_3（ISO_3166_1 alpha 3 コード）が含まれます。 |
properties.context.region | object | [optional] 結果の地域。このレイヤには、プロパティ id、name、region_code、および region_code_full（ISO_3166_2 コード）が含まれます。 |
properties.context.postcode | object | [optional] 結果の郵便番号。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.district | object | [optional] 結果の地区。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.place | object | [optional] 結果の場所。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.locality | object | [optional] 結果の地域。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.neighborhood | object | [optional] 結果の近隣。このレイヤには、プロパティ id および name が含まれます。 |
properties.context.address | object | [optional] 通り番号および街路名を含む結果の住所。このレイヤには、プロパティ id 、name、address_number 、および street_nameが含まれます。 |
properties.context.street | object | [optional] 結果の通り。このレイヤには、プロパティ id および name が含まれます。 |
properties.coordinates | object | [required] 結果の地理座標。 |
properties.coordinates.longitude | number | [required] 経度座標。 |
properties.coordinates.latitude | number | [required] 緯度座標。 |
properties.coordinates.accuracy | string | [optional] 座標の精度。住所タイプの結果のみで利用可能であり、 |
properties.coordinates.routable_points | array | [optional] フィーチャのルート可能なポイントに関する情報を含むオブジェクトの配列。ルート可能なポイントオブジェクトには、プロパティ name 、latitude、 longitudeおよびオプションの noteが含まれます。 |
properties.bbox | array | [optional] バウンディングボックス。形式は 最小経度、最小緯度、最大経度、最大緯度。 |
properties.language | string | [optional] 結果の言語を示すIETF言語タグ。 |
properties.maki | string | [optional] 関連するMakiアイコンを表す文字列。 |
properties.poi_category | array | [optional] 結果がPOIなら、その結果が属するPOIカテゴリを含む配列。 |
properties.poi_category_ids | array | [optional] 結果がPOIなら、その結果が属する標準的なPOIカテゴリIDを含む配列。 |
properties.brand | array | [optional] 結果がPOIであり、適用可能な場合に関連する商業ブランド名を含む配列。 |
properties.brand_id | array | [optional] 結果がPOIであり、適用可能な場合の商業ブランドの標準IDを含む配列。 |
properties.external_ids | object | [optional] 外部データベースで見つけた機能のIDを含むオブジェクト。キーがデータソース名で、値がIDです。 |
properties.metadata | object | [optional] 機能に適用可能な場合、追加のメタデータを含むオブジェクト。 |
例: カテゴリでPOIを検索したレスポンス
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": { "coordinates": [-122.582748, 39.029528], "type": "Point" },
"properties": {
"name": "Stonehouse Cellars",
"mapbox_id": "CkIKQDRlNTdiODcxY2QyZjI0OGMwODNjZjE2Yzc1NTIyZDEyMjAyYzkzMmYzYTIwN2YwOTQ4ZDYxYjk1MTU5MmQ4ZjY=",
"feature_type": "poi",
"address": "500 Old Long Valley Rd",
"full_address": "500 Old Long Valley Rd, Clearlake Oaks, California 95423, United States of America",
"place_formatted": "Clearlake Oaks, California 95423, United States of America",
"context": {
"country": {
"name": "United States of America",
"country_code": "US",
"country_code_alpha_3": "USA"
},
"region": {
"name": "California",
"region_code": "CA",
"region_code_full": "US-CA"
},
"postcode": { "name": "95423" },
"place": { "name": "Clearlake Oaks" },
"street": { "name": "old long valley rd" }
},
"coordinates": {
"latitude": 39.029528,
"longitude": -122.582748,
"routable_points": [
{
"name": "default",
"latitude": 39.029528,
"longitude": -122.582748
}
]
},
"maki": "restaurant",
"poi_category": [
"restaurant",
"food",
"food and drink",
"winery",
"bar",
"nightlife"
],
"poi_category_ids": [
"restaurant",
"food",
"food_and_drink",
"winery",
"bar",
"nightlife"
],
"external_ids": { "foursquare": "55208bfe498e78a725b4030d" },
"metadata": { "primary_photo": [] }
}
}
],
"attribution": "© 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/)"
}
カテゴリ一覧の表示
/list/category エンドポイントへのリクエストで、指定した言語でのすべての利用可能なカテゴリのリストが返されます。このエンドポイントは親子関係を説明しておらず、カテゴリ間の関係を推測することはできません。
カテゴリ一覧を取得する
<FormatEndpoint verb='get' path={`/search/searchbox/v1/list/category`} />
| 必須のパラメータ | 型 | 説明 |
|---|---|---|
access_token | string | デフォルトのパーミッションを持つMapboxのアクセス トークン。 |
| オプションパラメータ | 型 | 説明 |
|---|---|---|
language | string | 返される言語のISO言語コード。指定されない場合、デフォルトは英語（en）で使用されます。 |
例: カテゴリ一覧を取得するリクエスト
# カテゴリ一覧を取得
$curl -X GET "https://api.mapbox.com/search/searchbox/v1/list/category?access_token=YOUR_MAPBOX_ACCESS_TOKEN&language=en"
レスポンス: カテゴリ一覧を取得する
レスポンスはカテゴリリストアイテムのコレクションです。
| プロパティ | 型 | 説明 |
|---|---|---|
list_items | array of objects | カテゴリオブジェクトの配列 |
attribution | string | 結果の帰属データ。 |
version | string | サービスバージョン情報。問題をMapboxに報告する場合はこの情報を含めてください。 |
list_items 内の各項目には次のプロパティがあります：
| プロパティ | 型 | 説明 |
|---|---|---|
canonical_id | string | [required] カテゴリの「Hot Button」の検索に使用する標準カテゴリID |
icon | string | [required] カテゴリに使用するMakiアイコン |
name | string | [required] 要求された言語でのカテゴリ名 |
例: カテゴリ一覧を取得するレスポンス
{
"listItems": [
{
"canonical_id": "services",
"icon": "marker",
"name": "Services",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "71fed985-aa4b-4e50-83f1-97e5a0a0751e"
},
{
"canonical_id": "shopping",
"icon": "marker",
"name": "Shopping",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "9d383df0-2f35-4932-9368-8cf0f488e701"
},
{
"canonical_id": "food_and_drink",
"icon": "marker",
"name": "Food and Drink",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "20dbf11b-a90d-4571-8996-a1ccbfbd8680"
},
{
"canonical_id": "food",
"icon": "restaurant",
"name": "Food",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "af0d6328-1e96-43d7-8925-decb4ed04a06"
},
{
"canonical_id": "restaurant",
"icon": "restaurant",
"name": "Restaurant",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "1a9e12e7-2e8d-47ee-9c3d-1aaa7ced55b6"
},
{
"canonical_id": "health_services",
"icon": "marker",
"name": "Health Services",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "f111ad81-9b4f-4346-b1dd-d7190a202276"
},
{
"canonical_id": "office",
"icon": "marker",
"name": "Office",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "8388a638-fdae-42f0-b3e7-ee1c1f786601"
},
{
"canonical_id": "education",
"icon": "marker",
"name": "Education",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "c530d2d8-ee87-4481-9289-088b97b796fa"
},
{
"canonical_id": "nightlife",
"icon": "marker",
"name": "Nightlife",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "ecd6c887-9952-45a1-848d-ee50177cb61d"
},
{
"canonical_id": "lodging",
"icon": "lodging",
"name": "Lodging",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629",
"uuid": "8de7b125-ac68-488f-b122-5c8b2706ff15"
}
],
"attribution": "© 2021 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/)",
"version": "25:6bd9b589a98b57a214d92076ecf35061eed6a629"
}
逆引き検索
逆引き検索を使用すると、特定の座標周辺の住所やPOI（興味のあるポイント）のリストを取得できます。例えば、33.9416° N、118.4085° W 周辺の場所を調べることができます。
/reverse エンドポイントを使用すると、単一の座標ペアを検索し、その場所に存在する地理的フィーチャーを返すことができます。
逆引き検索を実行する
| 必須のパラメータ | 型 | 説明 |
|---|---|---|
access_token | string | デフォルトのパーミッションを持つMapboxのアクセス トークン。 |
longitude | number | 逆引きクエリの経度座標。 |
latitude | number | 逆引きクエリの緯度座標。 |
このエンドポイントへのクエリ結果は次のオプションパラメータでさらに絞り込むことができます：
| オプションパラメータ | 型 | 説明 |
|---|---|---|
language | string | 返される言語のISO言語コード。指定されない場合、デフォルトは英語です。 |
limit | integer | 戻り値の結果数（最大10）。 |
country | string | ISO 3166 alpha 2 の国コードのカンマ区切りリスト。 |
types | string | 特定のタイプの機能に結果を限定し、カンマ区切りリストとして提供します。タイプ名の一つ以上をカンマ区切りのリストとして渡します。タイプが指定されない場合、すべての可能なタイプが返される可能性があります。利用可能なタイプは: country、region、prefecture、postcode、district、place、city、locality、oaza、block、street、およびaddress。これらのタイプについての詳細は行政単位の種類セクションを参照してください。 |
例: 逆引き検索を実行するリクエスト
$curl "https://api.mapbox.com/search/searchbox/v1/reverse?longitude=-118.471383&latitude=34.023653&language=de&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
レスポンス: 逆引き検索を実行する
逆引きクエリのレスポンスはGeoJSON FeatureCollectionです。
| プロパティ | 型 | 説明 |
|---|---|---|
type | string | 常に "FeatureCollection" となります。 |
features | array of objects | 返されたフィーチャオブジェクト。各フィーチャオブジェクトに含まれるプロパティの詳細については以下の表を参照してください。 |
attribution | string | 結果の帰属データ。 |
各フィーチャ内のプロパティは次の通りです：
| プロパティ | タイプ | 説明 |
| ---------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | -------- | ----------------------------------------------------------------------------------- |
| type | string | [required] 常に "Feature" となります。 |
| geometry | object | [required] 返されたフィーチャの空間ジオメトリを説明するオブジェクト。 |
| geometry.coordinates | array | [required] フィーチャの座標、[経度,緯度] のフォーマットで提供。 |
| geometry.type | string | [required] 常に "Point" となります。 |
| properties | object | [required] 返されたフィーチャに関連する特定のプロパティ。 |
| properties.name | string | [required] フィーチャの名前。 |
| properties.name_preferred | string | [optional] properties.name とは異なる場合のフィーチャの優先名。 |
| properties.mapbox_id | string | [required] フィーチャに関連するID。 |
| properties.feature_type | string | [required] 結果のタイプ。POIの場合、これは poi になります。住所タイプの結果の場合、グローバルコンテキスト階層が使用されます（country、region、postcode、district、place、locality、neighborhood、address）。これらのタイプについての詳細は行政単位の種類セクションを参照してください。 |
| properties.address | string | [optional] 通り番号および街路名を含む結果の住所。 |
| properties.full_address | string | [optional] properties.address および properties.place_formatted を連結した結果のフル住所。 |
| properties.place_formatted | string | [optional] 場所、地域、国、郵便番号から成る結果コンテキストのフォーマット済み文字列。 address の後に結果が続く部分を示します。 |
| properties.context | object | [required] フィーチャのコンテキスト。 |
| properties.context.country | object | [optional] 結果の国。このレイヤには、プロパティ id、name、country_code（ISO_3166_1 alpha 2 コード）、country_code_alpha_3（ISO 3166-1 alpha 3コード）が含まれます。 |
| properties.context.region | object | [optional] 結果の地域。このレイヤには、プロパティ id、name、region_code、および region_code_full（ISO 3166-2コード）が含まれます。 |
| properties.context.postcode | object | [optional] 結果の郵便番号。このレイヤには、プロパティ id および name が含まれます。 | properties.context.district | object | [optional] 結果の地区。このレイヤには、プロパティ id および name が含まれます。 |
| properties.context.place | object | [optional] 結果の場所。このレイヤには、プロパティ id および name が含まれます。 |
| properties.context.locality | object | [optional] 結果の地域。このレイヤには、プロパティ id および name が含まれます。 |
| properties.context.neighborhood | object | [optional] 結果の近隣。このレイヤには、プロパティ id および name が含まれます。 |
| properties.context.address | object | [optional] 通り番号および街路名を含む結果の住所。このレイヤには、プロパティ id、name、address_number、及び street_name が含まれます。 |
| properties.context.street | object | [optional] 結果の通り。このレイヤには、プロパティ id および name が含まれます。 |
| properties.coordinates | object | [required] フィーチャの地理座標。 |
| properties.coordinates.longitude | number | [required] 経度座標。 |
| properties.coordinates.latitude | number | [required] 緯度座標。 |
| properties.coordinates.accuracy | string | [optional] 座標の精度。このプロパティは住所タイプの結果にのみ利用可能で、オプションは、rooftop、parcel、point、interpolated、intersection、approximate、および street です。 |
| properties.coordinates.routable_points | array | [optional] フィーチャのルートポイントに関する情報を含むオブジェクトの配列。ルートポイントオブジェクトには、プロパティ name、latitude、longitude 及びオプションの note が含まれます。 |
| properties.bbox | array | [optional] バウンディングボックス。形式は次の通りです： 最小経度,最小緯度,最大経度,最大緯度。 |
| properties.language | string | [optional] 結果の言語を示す IETF 言語タグ。 |
| properties.maki | string | [optional] 関連する Maki アイコン を示す文字列。 |
| properties.poi_category | array | [optional] 結果が POI なら、その結果が属する POI カテゴリを含む配列。 |
| properties.poi_category_ids | array | [optional] 結果が POI なら、その結果が属する標準的な POI カテゴリ ID を含む配列。 |
| properties.brand | array | [optional] 結果が POI であり、適用可能な場合に関連する商業ブランド名を含む配列。 |
| properties.brand_id | array | [optional] 結果が POI であり、適用可能な場合の商業ブランドの標準 ID を含む配列。 |
| properties.external_ids | object | [optional] 外部データベースで見つけたフィーチャの ID を含むオブジェクト。キーがデータソース名、値が ID です。 |
| properties.metadata | object | [optional] 機能に適用可能な場合、追加のメタデータを含むオブジェクト。 |
例: 逆引き検索を実行するレスポンス
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": { "coordinates": [13.3295589, 52.5125463], "type": "Point" },
"properties": {
"name": "Straße Des 17. Juni 115",
"mapbox_id": "dXJuOm1ieGFkcjo2YjU1MDMxMy1iNzM0LTQxNjYtYjk0MC0zZTU1MTE4MmQwOGY",
"feature_type": "address",
"address": "Straße Des 17. Juni 115",
"full_address": "Straße Des 17. Juni 115, 10623 Berlin, Germany",
"place_formatted": "10623 Berlin, Germany",
"context": {
"country": {
"id": "dXJuOm1ieHBsYzpJam8",
"name": "Germany",
"country_code": "DE",
"country_code_alpha_3": "DEU"
},
"postcode": { "id": "dXJuOm1ieHBsYzpVYTQ2", "name": "10623" },
"place": { "id": "dXJuOm1ieHBsYzpBY1E2", "name": "Berlin" },
"locality": {
"id": "dXJuOm1ieHBsYzpBd1pxT2c",
"name": "Charlottenburg"
},
"address": {
"id": "dXJuOm1ieGFkcjo2YjU1MDMxMy1iNzM0LTQxNjYtYjk0MC0zZTU1MTE4MmQwOGY",
"name": "Straße Des 17. Juni 115",
"address_number": "Straße",
"street_name": "Des 17. Juni 115"
},
"street": { "name": "Des 17. Juni 115" }
},
"coordinates": {
"latitude": 52.5125463,
"longitude": 13.3295589,
"accuracy": "rooftop",
"routable_points": [
{
"name": "default",
"latitude": 52.51264818693428,
"longitude": 13.32955240836938
}
]
},
"language": "en",
"maki": "marker",
"external_ids": {},
"metadata": {}
}
}
],
"attribution": "© 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/)"
}
Mapbox Geocoding API から Search Box API へのアップグレード
既存の Mapbox Geocoding API のお客様は、Search Box API にアップグレードすると、最新の POI（興味のあるポイント）データにアクセスでき、標準住所ジオコーディングを超えた機能を提供できます。
アップグレードを計画する際に考慮する手順は以下のとおりです：
アプリケーションの Geocoding API エンドポイントを更新する
Search Box API に移行するには、アプリケーションの API エンドポイントを更新してください。以下の比較に従って、両製品のエンドポイントの対応を確認できます。
- Search Box API の Forward Geocoding エンドポイントの相当：
/suggestと/retrieve、および/forward - Search Box API の Reverse Geocoding エンドポイントの相当：
/reverse
Search Box API は検索セッションまたは検索リクエストで実装できます。
検索セッションの使用
あなたのアプリがユーザーのためのインタラクティブ検索機能を含む場合、Search Box API の /suggest および /retrieve エンドポイントを使用します。
ユーザーがクエリを入力する際に、各キー入力は /suggest エンドポイントをトリガーし、検索結果を選択すると /retrieve エンドポイントがトリガーされます。
このユースケースは、各キー入力が /forward ジオコーディングAPIのリクエストをトリガーする Geocoding API の動作とは異なります。
/suggest および /retrieve エンドポイントを組み合わせて使用すると、請求セッションが作成され、リクエストはセッションベースの価格設定に基づいて請求されます。
検索リクエストの使用
/forward エンドポイントの Search Box API へのワンオフ検索リクエストを送信することもできます。
これは Geocoding API の /forward エンドポイントの使用と似ています。このエンドポイントはリクエストごとに請求されます。
新しいレスポンススキーマに合わせてアプリを更新する
Geocoding API および Search Box API の両方が検索レスポンスとして GeoJSON オブジェクトを返しますが、属性の命名と範囲にわずかな違いがあります。 アップグレードする際には、アプリケーションのデータスキーマを更新する必要があります。Mapbox Search SDK を使用している場合、Search Box API 用に提供されているクラスを利用するのが良いでしょう。
レスポンスを制御する
Search Box API は、特定の要件に応じて検索結果をカスタマイズする力を開発者に提供します。これには、レスポンスに表示される特定の POI（Point of Interest）のカテゴリを含めるまたは除外する能力が含まれます。 パラメータを設定することで、検索結果に表示されるフィーチャの種類（たとえば、地域、住所、興味のある場所など）を決定できます。
両方のAPIの請求システムを理解する
Geocoding API はリクエストごとに請求するモデルで動作し、API への各コールは別々に課金されます。 これに対し、Search Box API は、使用するエンドポイントに応じて、セッション単位およびリクエスト単位の両方の柔軟な料金オプションを提供しています。
Geocoding API のリクエスト単位のモデルから Search Box API のセッションベースのモデルに移行する際に、合計 Geocoding API リクエスト数を検索完了に必要な平均相互作用数で除算して、推定 Search Box API セッション数を計算できます。 たとえば、モバイルアプリケーションのユーザーが通常7回のキー入力で検索を完了する場合、以前は Geocoding API で8つの個別リクエストが行われたものが、Search Box API では1つのセッションに対応します。
詳細については、Mapbox 検索価格をご覧ください。
行政単位の種類
Search Box API では、さまざまなタイプの行政単位が利用可能です。任意のタイプは、トップレベルレスポンスとして、トップレベルレスポンスのコンテキストとして、またはオプションの types パラメータを使用してフィルタリングオプションとして表示される場合があります。 利用可能な行政単位タイプについては以下の表を参照してください。
| 行政単位の種類 | 説明 |
|---|---|
country | 一般に認識されている国、または一部のケース（例：香港）では、ISO 3166-1 の下で国コードを持つ準国行政ステータスの地域。 |
region | 州、カナダや中国の県、米国の州など、トップレベルの行政区分機能。 |
postcode | 国内のアドレッシングシステムで使用される郵便番号。 |
district | トップレベルの行政機能よりも小さいが、通常は都市よりも大きいフィーチャ。例えば、中国の県など。郵便アドレッシングで追加のレイヤが使われる国に存在します。 |
place | 一般的には都市、村、自治体など。郵便アドレッシングで使用されるフィーチャで、現在の位置コンテキストが必要なエンドユーザー用アプリケーション（例：天気表示）に適している。 |
locality | 公式の都市内サブフィーチャ。郵便アドレッシングで追加の行政レイヤが使用される国、または地元の言葉でよく参照される。例：ブラジルとチリの都市区、フランスの区など。 |
neighborhood | 地域の言葉でよく参照される非公式のサブフィーチャ。locality フィーチャとは異なり、これらは公式のステータスを持たず、普遍的に合意された境界を持たない場合がある。逆引き検索リクエストには利用不可。 |
street | 通り名、番地なしの住所。 |
address | 通り番号の住所。 |
言語と地理のサポート
サポートされている言語
Search Box API は以下の言語のテキストクエリをサポートしています； チェコ語、クロアチア語、デンマーク語、オランダ語、英語、エストニア語、フィンランド語、フランス語、ドイツ語、ギリシャ語、ハンガリー語、イタリア語、日本語、リトアニア語、ラトビア語、ポーランド語、ポルトガル語、ルーマニア語、ロシア語、スロバキア語、スロベニア語、スペイン語、スウェーデン語、トルコ語、ウクライナ語。
APIパラメータの言語に対応するISOの言語コードを設定することで、言語を設定できます。また、カンマ区切りリストで複数の言語コードを指定できます。この場合、リスト内で最初にサポートされる言語が要求の処理に使用されます。
サポートされている地域
Search Box API はアメリカ合衆国、カナダおよびヨーロッパに対応しています。
Search Box APIエラー
レスポンスボディ message | HTTPエラーコード | 説明 |
|---|---|---|
Not authorized | 401 | クエリに使用したアクセス トークンを確認してください。 |
Bad request | 400 | エンドポイント、パスパラメータ、およびクエリパラメータに構文エラーがないか確認してください。 |
Forbidden | 403 | アカウントに問題がある可能性があります。アカウントページで詳細を確認してください。 一部のケースでは、URL制限付きのアクセス トークンを使用することも 403 エラーを引き起こす可能性があります。詳細は、トークン管理ガイドを参照してください。 |
Search Box API制限
- Mapbox の利用規約により、Search Box API エンドポイントから返されるすべてのデータは一時的な使用のみ許可されています。位置データの保存が必要なユースケースについては、Mapbox 営業部門にお問い合わせください。
- Mapbox Search Box API のデフォルトのレート制限は 1 秒間に 10 リクエストです。より高いレート制限が必要な場合は、Mapbox 営業部門にお問い合わせください。
- Search Box API の
/suggestおよび/retrieveエンドポイントへのコールには、session_tokenパラメータを含める必要があります。1 つの検索セッション内の各 API コールは、レート制限に対して個別にカウントされます。たとえば、同じsession_tokenを使用して/suggestに連続して 10 回コールし、1 回/retrieveにコールする場合、レート制限に対して 11 リクエストとしてカウントされますが、請求上は 1 つのセッションとしてカウントされます。Search Box API がどのように請求されるかについての詳細は、このドキュメントの Session Billing セクションを参照してください。
Search Box API の料金
Mapbox Search Box API は、使用する API エンドポイントに基づいて料金が適用されます。/suggest や /retrieve エンドポイントを使用する場合、使用は検索セッションごとに請求されます。/category や /reverse エンドポイントを使用する場合、使用はリクエストごとに請求されます。
詳細については、Mapbox 検索価格をご覧ください。
セッション請求
検索セッションは、請求目的でバンドルされた一連の Search API コールです。Search Box API の /suggest および /retrieve エンドポイントには、session_token パラメータを含める必要があります。session_token パラメータは、一連のリクエストを 1 つのセッションにグループ化するために使用されます。
セッションは以下のアクションの後に終了します：
- 共通の
session_tokenで/suggestにコールし、その後/retrieveにコールする。 - 共通の
session_tokenで/suggestに 50 回連続してコールし、その後/retrieveにコールしない。 /suggestにコールし、その後 60 分間/retrieveにコールしない。
Mapbox Search API（以前のリリース）のドキュメントは https://docs.mapbox.com/search/search/ で利用できます。