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"