Search

Public beta for the Search API

Mapbox Search APIはパブリックベータ版です。パブリックベータ版のMapbox Search APIでは、日本国内の場所に対する日本語のクエリのみご利用頂けます。他の言語のクエリで、海外を含めた検索結果をご確認いただくには、Mapbox Geocoding APIをご利用ください。

パブリックベータ期間中に此方のフィードバックまで送信頂いたご意見やご感想は、Search APIの改善に利用させて頂きます。

Mapbox Search APIはエンドユーザーにインタラクティブな検索体験の提供や、個別のフォワード又はリバースのジオコーディングクエリをサポートします。

Search APIエンドポイント

Search APIには5つのエンドポイントがあります: /suggest, /retrieve, /forward, /permanent/forward, /reverse.

サジェスト

/suggestエンドポイントを/retrieveエンドポイントと組み合わせて使用すると、サジェスト検索機能をエンドユーザーに提供できます。先ずはアプリケーション内でユーザーの検索クエリを/suggestエンドポイントに送信します。 その後UI上でユーザーが選択する検索サジェスト結果が/retrieveエンドポイントに送信されます。詳しくは、本ドキュメントのサジェストの取得セクションをご参照ください。

取得

ユーザーが/suggestエンドポイントで選択した結果は/retrieveエンドポイントに送られ、地理座標を含むフィーチャが提供されます。/retrieveアクションが実行されると、Search APIが選択されたフィーチャの座標を含むGeoJSONを返します。詳しくは、本ドキュメントのフィーチャに関する情報の取得セクションをご参照ください。

フォワードジオコーディング

/forwardエンドポイントは、場所を名前で検索し、地理座標を返すことができます。詳しくは、本ドキュメントのフォワードジオコーディングのセクションをご参照ください。

パーマネントフォワードジオコーディング

/permanent/forwardエンドポイントは、位置データを保存するユースケースで使用します。 /forwardエンドポイントは、場所を名前で検索し、地理座標を返すことができます。詳しくは、本ドキュメントのパーマネントフォワードジオコーディングのセクションをご参照ください。

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

/reverseエンドポイントは、一組の座標を検索し、該当する場所の地理的特徴やフィーチャを返すことができます。詳しくは、本ドキュメントのリバースジオコーディングセクションをご参照ください。

行政区画タイプ

Search APIでは様々な行政区画タイプがご利用頂けます。データ型はトップレベルのレスポンスとして表示されます。表示の際は、トップレベルのレスポンスのコンテキスト、またはtypesオプションパラメータを使用したフィルターオプションとして表示されます。 利用可能な行政区画タイプは次の表の通りです。

行政区画タイプ概要
country国家として認められている行政区画を指します。または、香港のように、ISO 3166-1が指定する国名コードを付与されている準国家としての行政区画も指します。
region米国の州(state)、カナダの州や中国の省(province)など、最高位の地方自治体の行政区画を指します。
prefecture日本では「県」(都道府県)と称される行政区画で、regionに相当します。
postcode各国の住所システムで使用されている郵便番号です。
district最高位の行政区画より小規模のフィーチャになりますが、市よりも大きい地域を指します。国によっては、郵便物の宛先にこのようなレイヤーを加えて使用します。(例:中国の県)
place一般的に、市区町村・自治体などを指します。通常、郵便物の宛先に使用されるフィーチャになります。このフィーチャは、現在地情報を反映させるようなアプリケーション(例:天気情報)に適しています。
city日本では「市町村」にあたる行政区画で、placeに相当します。
locality郵便物の宛先に使用されるような、国家に正式に認可されている行政区画を指します。placecityよりも細かい区画のフィーチャになります。ブラジルやチリの市区町村、フランスの「arrondissement(行政区)」などのような行政レイヤーを指します。
oaza日本では大字(訳註:または町域/町字とも呼ばれる。)と称される行政区画で、localityに相当します。
neighborhood現地で口語的に使用される区画の呼称です。placecityよりも細かい区画のフィーチャですが、localityとは異なり、通常この行政区画は公式な行政区域ではないので、境界線が曖昧な場合があります。
chome日本では「丁目」と称される行政区画で、neighborhoodに相当します。
block区画番号です。
street住居番号のない通りです。
address個人住宅や会社の住所を、住居番地付きの通りとして返します。日本では、「何番地、何号」の番号に相当します。chome(丁目)以下の部分はすべてaddressとして指定されます。

サジェストの取得

GET /search/v1/suggest/{search_text}

サジェストを取得します。このエンドポイントは、ユーザークエリのオートコンプリート機能に基づいて、エンドユーザーが何を検索しているのかを予測します。retrieve endpointと同時に使用すると、地理検索機能を有するアプリケーションに、オートコンプリート機能を追加できます。

POI search not available

Search APIのパブリックベータ版ではPOI(関心地点)検索はご利用いただけません。建物名、地元の店舗、公園などのPOIを検索する機能は今後実装する予定です。

必須パラメータデータ型概要
access_token文字列Mapboxアクセストークン(デフォルトのパーミッション設定)です。
session_token文字列お客様が提供するセッション・トークンの値です。一連のリクエストをグループ化し、課金用に使用します。UUIDv4を推奨します。Search APIのコールを1つのセッションにまとめるsession_tokenについては、本ドキュメントにあるセッション毎の料金のセクションをご参照ください。
search_text文字列ユーザーのクエリ文字列です。クエリ文字列の上限は120文字までです。
language文字列返されるISO言語コードです。正確な結果を出すためには、このパラメータの値をjaに設定してください.
country文字列「ISO 3166 alpha 2」の国名コードです。正確な結果を出すためには、このパラメータの値をJPに設定してください。

以下のオプションを使い、このエンドポイントに対するクエリの結果をより使いやすくできます:

オプション・パラメータデータ型概要
bbox数値指定されたバウンディングボックス内に含まれるものだけに結果を限定します。バウンディングボックスを指定するには、次の4つの数値、minimum longitude, minimum latitude, maximum longitude, maximum latitudeの順にカンマ区切りで指定します。バウンディングボックスは、180度の子午線を越えることはできません。
limit整数返される結果の数を設定します(最大100件)。デフォルトでは、5つの結果を返すよう設定されています。
navigation_profile文字列使用するナビゲーション・ルーティング・プロファイルです。利用可能なプロファイルは、driving,walking,cyclingです。navigation_profileoriginは距離の計算に必要になります。
origin数値距離を計算する起点を、longitude,latitudeの順にカンマ区切りにした2つの座標で指定します。proximityoriginの両方が提供された場合、originはルートのターゲットとして解釈され、proximityはユーザーの現在地を示します。 このパラメータは、ターゲット間の距離を推定するため必要になりますが、遅延が発生する場合があります。
proximity数値指定地点に近い結果が優先されるように、レスポンスを調整します(バイアスをかける)。結果は、longitude,latitudeの順に、カンマ区切りの2つの座標として提供されます。proximityoriginの両方が提供された場合、originはルートのターゲットとして解釈され、proximityはユーザーの現在地を示します。
eta_type文字列originで指定された場所からの到着時間を推定するために使用します。このパラメータで使用できる値は、navigationのみです。このパラメータは、originおよびnavigation_profileとともに、ETA(推定到着時刻)の計算に必要になります。ETA(推定到着時刻)の計算には遅延が発生します。
types文字列結果を1つまたは複数のデータ型のフィーチャに限定して、カンマ区切りのリストを提供します。1つまたは複数のデータ型名をカンマ区切りのリストとして渡します。指定されたデータ型がない場合は、利用可能なすべてのデータ型を返します。以下のデータ型がご利用いただけます:country, region, prefecture, postcode, district, place, city, locality, oaza, neighborhood, chome, block, street, address。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。

リクエスト例: サジェストの取得

# Search for 東京 with only prefectures and no proximity point

$ curl "https://api.mapbox.com/search/v1/suggest/東京?language=ja&country=jp&types=prefecture&access_token=YOUR_MAPBOX_ACCESS_TOKEN&session_token=[GENERATED-UUID]"

レスポンス: サジェストの取得

/suggestエンドポイントに対してリクエストを実行した際、返されるレスポンスは、JSONサジェストオブジェクトの配列になります。サジェストには、結果の名前、概要、利用可能な場合は追加のメタデータ(近接ポイントまでの距離など)が含まれます。地理座標は含まれていません。座標を取得するためには、「/retrieve」エンドポイント/retrieve endpointをコールします。この際、/suggest結果の"action"ブロックで提供された情報を使用します。"action"ブロックは不透明型(OPAQUE)なので、アプリケーションで確認を行わなくてもそのまま使用することができます。

デフォルトでは、検索1回に対し最大5件の結果を返します。limitパラメータを使用すると、検索結果の最大数を100件まで増やせます。現段階ではページネーションのご利用はできませんが、将来のリリースで追加される可能性があります。また、検索結果の順序をカスタマイズするオプションはありません。

各結果オブジェクトには、以下のプロパティが含まれます:

プロパティデータ型概要
attribution文字列結果の帰属データです。
version文字列サービスのバージョン情報です。Mapboxに問題を報告する際は、バージョン情報を明記の上、ご連絡ください。
response_uuid文字列サービスのバージョン情報です。Mapboxに問題を報告する際は、response_uuidを明記の上、ご連絡ください。
suggestionsオブジェクトの配列返されたサジェストオブジェクトです。各サジェストオブジェクトに含まれるプロパティについては、以下の表をご参照ください。

各サジェストオブジェクトは、以下のプロパティを含みます:

プロパティデータ型概要
feature_name文字列フィーチャの名前です。
matching_name文字列検索アルゴリズムでマッチしたフィーチャー名です。
description文字列都市名や州名を住所名として使用する場合などの追加情報です。
actionオブジェクトこのアクションブロックは、サジェストを継続するために必要な次のステップを示します。
action.endpoint文字列次のリクエストを指定するエンドポイントです。現在のオプションはsuggestretrieveです。/suggestコールは、APIが、次の最良の選択肢は別のラウンドのサジェストである、と判断したときに使用されます。/retrieveコールは、ユーザーの探している機能をAPIが理解し、ユーザーが結果の地理的座標を入手する準備ができたと判断したときに使用されます。
action.method文字列次のリクエストで許可されるHTTPメソッドの種類です。選択肢はPOST、または、あまり一般的ではありませんがGETも使用できます。
action.bodyオブジェクトGeoJSONを取得する際に、HTTP POST /retrieveに渡すデータの内容になります。
action.multi_retrievableブーリアン型一括でデータの取得(バッチ・リトリーブ)を行う際に、特定のフィーチャを取得できるかどうかを示します。パブリックベータ版ではご利用いただけません。
result_type配列グローバルコンテキスト階層(region, place, locality, neighborhood, address)を使用した際の結果のデータ型です。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。
geometryオブジェクト返されたフィーチャの空間ジオメトリを記述するオブジェクトです。
geometry.coordinates配列そのフィーチャの座標を[longitude,latitude]としてフォーマットしたものです。
geometry.type文字列こちらは常に"Point"になります。
distance数値「origin」の位置までのおおよその距離をメートル単位で返します。リクエストにoriginnavigation_profileが使用されている場合のみ提供されます。
eta数値フィーチャから出発地点までの到着予定時間を分単位で表します。 リクエストに eta_type,origin,navigation_profileが使用されている場合のみ提供されます。住所が道路網上にない場合は、ETA(到着予想時刻)を提供できません。
maki文字列結果で使用するMakiアイコンを表す文字列です。
language文字列結果で使用する言語を示すIETFの言語タグです。
internal_id文字列内部メタデータ用のIDです。このIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
external_idsオブエクト外部のデータプロバイダーから渡されたIDです。これらのIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
mapbox_id文字列MapboxのインターナルIDです。このIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
context配列フィーチャのコンテキストです。
context.localized_layer文字列日本のplace_typeです。場所に関するデータ型については、本ドキュメントの「行政区画タイプ」のセクション行政区画タイプセクションをご参照ください。
context.layer文字列context.localized_layerの中にある日本のproperties.place_typeに対応するグローバルなplace_typeです。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。
context.name文字列フィーチャの名前です。
metadataオブジェクト日本の住所のメタデータ・フィールドです。
metadata.iso_3166_1文字列国名コードです。
metadata.iso_3166_2文字列国名コードと都道府県コードです。

レスポンス例: サジェストの取得

{
  "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms",
  "suggestions": [{
    "result_type": ["Address", "Address"],
    "maki": "maki",
    "metadata": {
      "iso_3166_1": "jp",
      "iso_3166_2": "JP-13"
    },
    "feature_name": "東京都",
    "distance": 0.8008281904610115,
    "internal_id": "internal_id",
    "matching_name": "東京都",
    "description": "東京都千代田区丸ノ内二丁目7番2号",
    "language": "ja",
    "external_ids": {
      "foursquare": "12345678"
    },
    "eta": 6.027456183070403,
    "mapbox_id": "mapbox_id",
    "context": [{}, {}],
    "action": {
      "endpoint": "retrieve",
      "method": "POST",
      "multi_retrievable": true,
      "body": {
        "id": "12345"
      }
    },
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    }
  }, {
    "result_type": ["Address", "Address"],
    "maki": "maki",
    "metadata": {
      "iso_3166_1": "jp",
      "iso_3166_2": "JP-13"
    },
    "feature_name": "東京都",
    "distance": 0.8008281904610115,
    "internal_id": "internal_id",
    "matching_name": "東京都",
    "description": "東京都千代田区丸ノ内二丁目7番2号",
    "language": "ja",
    "external_ids": {
      "foursquare": "12345678"
    },
    "eta": 6.027456183070403,
    "mapbox_id": "mapbox_id",
    "context": [{}, {}],
    "action": {
      "endpoint": "retrieve",
      "method": "POST",
      "multi_retrievable": true,
      "body": {
        "id": "12345"
      }
    },
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    }
  }],
  "response_uuid": "72f2166c-249c-40d7-b8ee-1ad0e223a647",
  "version": "foo:bar"
},
{
  "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms",
  "suggestions": [{
    "result_type": ["Address", "Address"],
    "maki": "maki",
    "metadata": {
      "iso_3166_1": "jp",
      "iso_3166_2": "JP-13"
    },
    "feature_name": "東京都",
    "distance": 0.8008281904610115,
    "internal_id": "internal_id",
    "matching_name": "東京都",
    "description": "東京都千代田区丸ノ内二丁目7番2号",
    "language": "ja",
    "external_ids": {
      "foursquare": "12345678"
    },
    "eta": 6.027456183070403,
    "mapbox_id": "mapbox_id",
    "context": [{}, {}],
    "action": {
      "endpoint": "retrieve",
      "method": "POST",
      "multi_retrievable": true,
      "body": {
        "id": "12345"
      }
    },
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    }
  }, {
    "result_type": ["Address", "Address"],
    "maki": "maki",
    "metadata": {
      "iso_3166_1": "jp",
      "iso_3166_2": "JP-13"
    },
    "feature_name": "東京都",
    "distance": 0.8008281904610115,
    "internal_id": "internal_id",
    "matching_name": "東京都",
    "description": "東京都千代田区丸ノ内二丁目7番2号",
    "language": "ja",
    "external_ids": {
      "foursquare": "12345678"
    },
    "eta": 6.027456183070403,
    "mapbox_id": "mapbox_id",
    "context": [{}, {}],
    "action": {
      "endpoint": "retrieve",
      "method": "POST",
      "multi_retrievable": true,
      "body": {
        "id": "12345"
      }
    },
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    }
  }],
  "response_uuid": "72f2166c-249c-40d7-b8ee-1ad0e223a647",
  "version": "foo:bar"
}

サジェストされたフィーチャを取得

POST /search/v1/retrieve/

/suggestエンドポイントに対するコールが成功した後、レスポンスのactionブロックに含まれる情報を使い、該当するフィーチャに関する情報を取得します。このエンドポイントを使用する際には、受け渡し用のパラメータは必要ありません。その代わりに、/suggestのコールから返された「action」ブロックに関する情報をこのエンドポイントに渡す必要があります。

POI search not available

Search APIのパブリックベータ版ではPOI(関心地点)検索はご利用いただけません。建物名、地元の店舗、公園などのPOIを検索する機能は今後実装する予定です。

必須パラメータデータ型概要
access_token文字列デフォルトのパーミッションを備えたMapboxアクセストークンaccess tokenです。
session_token文字列お客様が提供するセッション・トークンの値です。一連のリクエストをグループ化し、課金用に使用します。UUIDv4UUIDv4を推奨します。Search APIのコールを1つのセッションにまとめるsession_tokenについては、本ドキュメントにあるセッション毎の料金のセクションをご参照ください。
リクエストボディのプロパティデータ型概要
id文字列こちらのIDは、/suggestエンドポイントからのレスポンスにあるaction.body.idから取得します。

リクエスト例: サジェストされたフィーチャを取得

POST /search/v1/retrieve?access_token=YOUR_MAPBOX_ACCESS_TOKEN&session_token=[GENERATED-UUID]

リクエストボディの例:

{
	"id": "12345"
}

レスポンス: サジェストされたフィーチャを取得

/retrieveエンドポイントは、GeoJSONFeatureCollectionを返します。

プロパティデータ型概要
type文字列こちらは常に"FeatureCollection"となります。
attribution文字列結果の帰属データです。
version文字列サービスのバージョン情報です。Mapboxに問題を報告する際は、バージョン情報を明記の上、ご連絡ください。
response_uuid文字列サービスのバージョン情報です。Mapboxに問題を報告する際は、response_uuidを明記の上、ご連絡ください。
featuresオブジェクトの配列返されたフィーチャオブジェクトです。各フィーチャオブジェクトに含まれるプロパティについては、以下の表をご参照ください。

レスポンスボディの各フィーチャには、以下のプロパティが含まれます:

プロパティデータ型概要
bbox配列minimum longitude,minimum latitude,maximum longitude,maximum latitude形式のバウンディングボックスです。パブリックベータ期間中はご利用いただけません。
geometryオブジェクト返されたフィーチャの空間ジオメトリを記述するオブジェクトです。
geometry.coordinates配列フィーチャの座標で、[longitude,latitude]というフォーマットになっています。
geometry.type文字列こちらは常に"Point"になります。
type文字列こちらは常に"Feature"になります。
propertiesオブジェクト返されたフィーチャに関連する特定のプロパティです。
properties.maki文字列結果で使用するMakiアイコンを表す文字列です。
properties.metadataオブジェクト日本の住所のメタデータ・フィールドです。
properties.metadata.iso_3166_1文字列国名コードです。
properties.metadata.iso_3166_2文字列国名コードと都道府県コードです。
properties.address文字列結果に住所が含まれる場合、現地形式の住所になります。
properties.feature_name文字列フィーチャの名前です。
properties.matching_name文字列検索アルゴリズムでマッチしたフィーチャー名です。
properties.internal_id文字列内部メタデータ用のIDです。このIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
properties.external_idsオブジェクト外部のデータプロバイダーから渡されたIDです。これらのIDは、安定性や一意性が保証されていないため、開発には役立ちません。
properties.mapbox_id文字列MapboxのインターナルIDです。このIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
properties.place_type配列結果の型です。場所に関するデータ型については、行政区画タイプセクションをご参照ください。
properties.language文字列IETF言語タグです。
properties.address_number文字列住所オブジェクトの住居番号です。
properties.contextオブジェクトの配列フィーチャのコンテキストです。
properties.context.localized_layer文字列日本のplace_typeです。場所に関するデータ型については、行政区画タイプセクションをご参照ください。
properties.context.layer文字列context.localized_layer内の日本のproperties.place_typeに対応するグローバルなplace_typeです。場所に関するデータ型については、行政区画タイプセクションをご参照ください。
properties.context.name文字列フィーチャの名前です。

レスポンス例: サジェストされたフィーチャを取得

{
  "features": [{
    "bbox": [139.0365, 38.8977, 139.1365, 38.9977],
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    },
    "type": "Feature",
    "properties": {
      "maki": "maki",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13"
      },
      "address": "北海道札幌市中央区旭ケ丘1丁目",

      "feature_name": "北海道札幌市中央区旭ケ丘1丁目",
      "internal_id": "internal_id",
      "matching_name": "北海道札幌市中央区旭ケ丘1丁目",
      "mapbox_id": "mapbox_id",
      "place_type": ["address", "address"],
      "context": [{
        "layer": "neighborhood",
        "localized_layer": "chome",
        "name": "1丁目"
      }, {
        "layer": "locality",
        "localized_layer": "oaza",
        "name": "旭ケ丘"
      }, {
        "layer": "place",
        "localized_layer": "city",
        "name": "札幌市中央区"
      }, {
        "layer": "region",
        "localized_layer": "prefecture",
        "name": "北海道"
      }],
      "language": "ja",
      "external_ids": {
        "foursquare": "12345678"
      },
      "address_number": "4"
    }
  }, {
    "bbox": [139.0365, 38.8977, 139.1365, 38.9977],
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    },
    "type": "Feature",
    "properties": {
      "maki": "maki",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13"
      },
      "address": "北海道札幌市中央区旭ケ丘1丁目",
      "feature_name": "北海道札幌市中央区旭ケ丘1丁目",
      "internal_id": "internal_id",
      "matching_name": "北海道札幌市中央区旭ケ丘1丁目",
      "mapbox_id": "mapbox_id",
      "place_type": ["address", "address"],
      "context": [{
        "layer": "neighborhood",
        "localized_layer": "chome",
        "name": "1丁目"
      }, {
        "layer": "locality",
        "localized_layer": "oaza",
        "name": "旭ケ丘"
      }, {
        "layer": "place",
        "localized_layer": "city",
        "name": "札幌市中央区"
      }, {
        "layer": "region",
        "localized_layer": "prefecture",
        "name": "北海道"
      }],
      "language": "ja",
      "external_ids": {
        "foursquare": "12345678"
      },
      "address_number": "4"
    }
  }],
  "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms",
  "response_uuid": "72f2166c-249c-40d7-b8ee-1ad0e223a647",
  "type": "FeatureCollection",
  "version": "foo:bar"
}

フォワードジオコーディング

GET /search/v1/forward/{search_text}

ユーザーからの問い合わせ(ユーザークエリ)に応じて、地理座標を含む特定のフィーチャに関する情報を取得することができます。

POI search not available

Search APIのパブリックベータ版ではPOI(関心地点)検索はご利用いただけません。建物名、地元の店舗、公園などのPOIを検索する機能は今後実装する予定です。

必須パラメータデータ型概要
access_token文字列デフォルトのパーミッションを備えたMapboxアクセストークンaccess tokenです。
search_text文字列ユーザーのクエリ文字列です。クエリ文字列の上限は120文字までです。
language文字列返されるISO言語コードになります。正確な結果を出すためには、パラメータの値をjaに設定してください.
country文字列「ISO 3166 alpha 2」の国名コードになります。正確な結果を出すためには、パラメータの値をjaに設定してください。

このエンドポイントに対するクエリの結果を、以下のオプションのパラメータでさらに使いやすくできます:

任意のパラメータデータ型概要
bbox数値指定されたバウンディングボックス内に含まれるものだけに結果を限定します。バウンディングボックスを指定するには、次の4つの数値、minimum longitude,minimum latitude,maximum longitude,maximum latitudeの順にカンマ区切りで指定します。バウンディングボックスは、180度の子午線を越えることはできません。
limit整数返される結果の数を設定します(最大100件)。デフォルトでは、5件の結果を返すよう設定されています。
navigation_profile文字列使用するナビゲーション・ルーティング・プロファイルです。 ご利用可能なプロファイルは、driving, walking, cyclingです。navigation_profileoriginは距離の計算に必要になります。
types文字列結果を1つまたは複数のデータ型のフィーチャに限定して、カンマ区切りのリストを提供します。1つまたは複数のデータ型名をカンマ区切りのリストとして渡します。指定されたデータ型がない場合は、利用可能なすべてのデータ型を返します。以下のデータ型がご利用いただけます:country, region, prefecture, postcode, district, place, city, locality, oaza, neighborhood, chome, block, street, address。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。

リクエスト例: フォワードジオコーディング

$ curl "https://api.mapbox.com/search/v1/forward/東京?language=ja&country=jp&types=prefecture&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

パーマネントフォワードジオコーディング

GET /search/v1/permanent/forward/{search_text}

Mapboxの利用規約では、/suggest, /retrieve, /forward, /reverseのいずれかのエンドポイントから返されるすべてのデータは、一時利用のみが可能であると規定されています。位置情報を保存するユースケースの場合は、Mapbox担当営業までお問い合わせください。この規定はmapbox.places-permanent endpointエンドポイントに適用されるMapbox Geocoding APIコールの利用規約と同様です。

/permanent/forwardエンドポイントは、/forward endpointと同じパスとクエリパラメータを使用します。

レスポンス: フォワードジオコーディング

/forwardエンドポイントに対してリクエストを実行した際、返されるレスポンスは、GeoJSON FeatureCollectionです。

デフォルトでは、検索1回に対し最大5件の結果を返します。limitパラメータを使用すると、検索結果の最大数を100件まで増やせます。現段階ではページネーションのご利用はできませんが、将来のリリースで追加される可能性があります。また、検索結果の順序をカスタマイズするオプションはありません。

プロパティデータ型概要
type文字列こちらは常に"FeatureCollection"となります。
attribution文字列結果の帰属データです。
version文字列サービスのバージョン情報です。Mapboxに問題を報告する際は、バージョン情報を明記の上、ご連絡ください。
response_uuid文字列サービスのバージョン情報です。Mapboxに問題を報告する際は、response_uuidを明記の上、ご連絡ください。
featuresオブジェクトの配列返されたフィーチャオブジェクトです。各フィーチャオブジェクトに含まれるプロパティについては、以下の表をご参照ください。

レスポンスボディの各フィーチャには、以下のプロパティが含まれます:

プロパティデータ型概要
bbox配列次の4つのフォーマット(minimum longitude, minimum latitude, maximum longitude, maximum latitude)のバウンディングボックスです。パブリックベータ期間中はご利用いただけません。
geometryオブジェクト返されたフィーチャの空間ジオメトリを記述するオブジェクトです。
geometry.coordinates配列そのフィーチャの座標を[longitude,latitude]としてフォーマットしたものです。
geometry.type文字列こちらは常に"Point"になります。
type文字列こちらは常に"Feature"になります。
propertiesオブジェクト返されたフィーチャに関連する特定のプロパティ。
properties.maki文字列結果で使用するMakiアイコンを表す文字列です。
properties.metadataオブジェクト日本の住所のメタデータ・フィールドです。
properties.metadata.iso_3166_1文字列国名コードです。
properties.metadata.iso_3166_2文字列国名コードと都道府県コードです。
properties.address文字列結果に住所が含まれる場合、現地形式の住所になります。
properties.address_number文字列住所オブジェクトの住居番号です。
properties.feature_name文字列フィーチャの名前です。
properties.matching_name文字列検索アルゴリズムでマッチしたフィーチャー名です。
properties.place_type配列結果の型です。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。
properties.language文字列IETF言語タグです。
properties.internal_id文字列内部メタデータ用のIDです。このIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
properties.external_idsオブジェクト外部のデータプロバイダーから渡されたIDです。これらのIDは、安定性や一意性が保証されていないため、開発には役立ちません。
properties.mapbox_id文字列MapboxのインターナルIDです。このIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
properties.contextオブジェクトの配列フィーチャのコンテキストです。
properties.context.localized_layer文字列日本のplace_typeです。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。
properties.context.layer文字列context.localized_layerの中にある日本のproperties.place_typeに対応するグローバルなplace_typeです。 場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。
properties.context.name文字列フィーチャの名前です。

レスポンス例: フォワードジオコーディング

{
  "features": [{
    "bbox": [139.0365, 38.8977, 139.1365, 38.9977],
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    },

    "type": "Feature",
    "properties": {
      "maki": "maki",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13"
      },
      "address": "北海道札幌市中央区旭ケ丘1丁目",
      "feature_name": "北海道札幌市中央区旭ケ丘1丁目",
      "internal_id": "internal_id",
      "matching_name": "北海道札幌市中央区旭ケ丘1丁目",
      "mapbox_id": "mapbox_id",
      "place_type": ["address", "address"],
      "context": [{
        "layer": "neighborhood",
        "localized_layer": "chome",
        "name": "1丁目"
      }, {
        "layer": "locality",
        "localized_layer": "oaza",
        "name": "旭ケ丘"
      }, {
        "layer": "place",
        "localized_layer": "city",
        "name": "札幌市中央区"
      }, {
        "layer": "region",
        "localized_layer": "prefecture",
        "name": "北海道"
      }],
      "language": "ja",
      "external_ids": {
        "foursquare": "12345678"
      },
      "address_number": "4"
    }
  }, {
    "bbox": [139.0365, 38.8977, 139.1365, 38.9977],
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    },
    "type": "Feature",
    "properties": {
      "maki": "maki",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13"
      },
      "address": "北海道札幌市中央区旭ケ丘1丁目",
      "feature_name": "北海道札幌市中央区旭ケ丘1丁目",
      "internal_id": "internal_id",
      "matching_name": "北海道札幌市中央区旭ケ丘1丁目",
      "mapbox_id": "mapbox_id",
      "place_type": ["address", "address"],
      "context": [{
        "layer": "neighborhood",
        "localized_layer": "chome",
        "name": "1丁目"
      }, {
        "layer": "locality",
        "localized_layer": "oaza",
        "name": "旭ケ丘"
      }, {
        "layer": "place",
        "localized_layer": "city",
        "name": "札幌市中央区"
      }, {
        "layer": "region",
        "localized_layer": "prefecture",
        "name": "北海道"
      }],
      "language": "ja",
      "external_ids": {
        "foursquare": "12345678"
      },
      "address_number": "4"
    }
  }],
  "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms",
  "response_uuid": "72f2166c-249c-40d7-b8ee-1ad0e223a647",
"type": "FeatureCollection",
  "version": "foo:bar"
}

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

GET /search/v1/reverse/{search_text}

/reverseエンドポイントでは、一組の座標を検索し、その場所に存在する地理的特徴やフィーチャを返すことができます。

必須パラメータデータ型概要
access_token文字列デフォルトのパーミッションを備えたMapboxアクセストークンaccess tokenです。
search_text文字列ユーザーのクエリ文字列です。クエリ文字列の上限は120文字までです。
language文字列表示されるISO言語コードになります。正確な結果を出すためには、パラメータの値をjaに設定してください。

以下のオプションを使い、このエンドポイントに対するクエリの結果をより使いやすくできます:

オプション・パラメータデータ型概要
limit整数返される結果の数を設定します(最大100件)。デフォルトでは、5件の結果を返すよう設定されています。
country文字列「ISO 3166 alpha 2」の国名コードです。正確な結果を出すためには、このパラメータの値をJPに設定してください。
types文字列検索1回に対し最大5件の結果を返します。結果を1つまたは複数のデータ型のフィーチャに限定して、カンマ区切りのリストを提供します。1つまたは複数のデータ型名をカンマ区切りのリストとして渡します。指定されたデータ型がない場合は、利用可能なすべてのデータ型を返します。以下のデータ型がご利用いただけます:country, region, prefecture, postcode, district, place, city, locality, oaza, neighborhood, chome, block, street, address。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。

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

$ "https://api.mapbox.com/search/v1/reverse/139.58028,35.29556?language=ja&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

レスポンス: リバースジオコーディング

/reverseエンドポイントに対してリクエストを実行した際、返されるレスポンスは、GeoJSON FeatureCollectionです。デフォルトでは、5件の結果を返すよう設定されています。limitパラメータを使用すると、検索結果の最大数を100件まで増やせます。現段階ではページネーションのご利用はできませんが、将来のリリースで追加される可能性があります。また、検索結果の順序をカスタマイズするオプションはありません。

プロパティデータ型概要
type文字列こちらは常に"FeatureCollection"となります。
attribution文字列結果の帰属データです。
version文字列サービスのバージョン情報です。Mapboxに問題を報告する際は、バージョン情報を明記の上、ご連絡ください。
response_uuid文字列サービスのバージョン情報です。Mapboxに問題を報告する際は、response_uuidを明記の上、ご連絡ください。
featuresオブジェクトの配列返されたフィーチャオブジェクトです。各フィーチャオブジェクトに含まれるプロパティについては、以下の表をご参照ください。

レスポンスボディの各フィーチャには、以下のプロパティが含まれます:

プロパティデータ型概要
bbox配列次の4つのフォーマット(minimum longitude, minimum latitude, maximum longitude, maximum latitude)のバウンディングボックスです。パブリックベータ期間中はご利用いただけません。
geometryオブジェクト返されたフィーチャの空間ジオメトリを記述するオブジェクトになります。
geometry.coordinates配列そのフィーチャの座標を[longitude,latitude]としてフォーマットしたもの。
geometry.type文字列こちらは常に"Point"になります。
type文字列こちらは常に"Feature"になります。
propertiesオブジェクト返されたフィーチャに関連する特定のプロパティです。
properties.maki文字列結果で使用するMakiアイコンを表す文字列です。
properties.metadataオブジェクト日本の住所のメタデータ・フィールド。
properties.metadata.iso_3166_1文字列国名コードです。
properties.metadata.iso_3166_2文字列国名コードと都道府県コードです。
properties.address文字列結果に住所が含まれる場合、現地形式の住所になります。
properties.feature_name文字列フィーチャの名前です。
properties.matching_name文字列検索アルゴリズムでマッチしたフィーチャー名です。
properties.place_type配列結果の型です。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。
properties.language文字列IETF言語タグです。
properties.internal_id文字列内部メタデータ用のIDです。このIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
properties.external_idsオブジェクト外部のデータプロバイダーから渡されたIDです。これらのIDは、安定性や一意性が保証されていないため、開発には役立ちません。
properties.mapbox_id文字列MapboxのインターナルIDです。このIDは、安定性や一意性を保証するものではなく、開発には役立ちません。
properties.address_number文字列住所オブジェクトの住居番号です。
properties.contextオブジェクトの配列フィーチャのコンテキストです。
properties.context.localized_layer文字列日本のplace_typeです。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。
properties.context.layer文字列context.localized_layerの中にある日本のproperties.place_typeに対応するグローバルなplace_typeです。場所に関するデータ型については、本ドキュメントの行政区画タイプセクションをご参照ください。
properties.context.name文字列フィーチャの名前です。

レスポンス例: リバースジオコーディング

{
  "features": [{
    "bbox": [139.0365, 38.8977, 139.1365, 38.9977],
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    },
    "type": "Feature",
    "properties": {
      "maki": "maki",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13"
      },
      "address": "北海道札幌市中央区旭ケ丘1丁目",
      "feature_name": "北海道札幌市中央区旭ケ丘1丁目",
      "internal_id": "internal_id",
      "matching_name": "北海道札幌市中央区旭ケ丘1丁目",
      "mapbox_id": "mapbox_id",
      "place_type": ["address", "address"],
      "context": [{
        "layer": "neighborhood",
        "localized_layer": "chome",
        "name": "1丁目"

      }, {
        "layer": "locality",
        "localized_layer": "oaza",
        "name": "旭ケ丘"
      }, {
        "layer": "place",
        "localized_layer": "city",
        "name": "札幌市中央区"
      }, {
        "layer": "region",
        "localized_layer": "prefecture",
        "name": "北海道"
      }],
      "language": "ja",
      "external_ids": {
        "foursquare": "12345678"
      },
      "address_number": "4"
    }
  }, {
    "bbox": [139.0365, 38.8977, 139.1365, 38.9977],
    "geometry": {
      "coordinates": [139.0365, 38.8977],
      "type": "Point"
    },
    "type": "Feature",
    "properties": {
      "maki": "maki",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13"
      },
      "address": "北海道札幌市中央区旭ケ丘1丁目",
      "feature_name": "北海道札幌市中央区旭ケ丘1丁目",
      "internal_id": "internal_id",
      "matching_name": "北海道札幌市中央区旭ケ丘1丁目",
      "mapbox_id": "mapbox_id",
      "place_type": ["address", "address"],
      "context": [{
        "layer": "neighborhood",
        "localized_layer": "chome",
        "name": "1丁目"
      }, {
        "layer": "locality",
        "localized_layer": "oaza",
        "name": "旭ケ丘"
      }, {
        "layer": "place",
        "localized_layer": "city",
        "name": "札幌市中央区"
      }, {
        "layer": "region",
        "localized_layer": "prefecture",
        "name": "北海道"
      }],
      "language": "ja",
      "external_ids": {
        "foursquare": "12345678"
      },
      "address_number": "4"
    }
  }],
  "attribution": "© 2021 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms",
  "response_uuid": "72f2166c-249c-40d7-b8ee-1ad0e223a647",
  "type": "FeatureCollection",
  "version": "foo:bar"
}

Search APIのエラー

レスポンスボディのメッセージ messageHTTP エラーコード概要
Not authorized401クエリで使用しているアクセストークンを確認してください。
Bad request400エンドポイント、パスパラメーター、クエリパラメーターに構文エラーがないか、リクエストを確認してください。
Forbidden403お使いのアカウントに問題がある可能性があります。詳しくは アカウントをご確認ください。

また、アクセストークンでURLを制限して使用すると、403エラーになる場合があります。詳しくは、トークン管理ガイドをご覧ください。
Not found404クエリにsearch_textが指定されていません。

Search APIの制限

  • Mapbox Search APIのレート制限は、デフォルトで毎分600リクエストです。レート制限を増加するにはMapboxの担当営業までお問い合わせください。
  • Search APIの/suggest/retrieveエンドポイントのコールには、session_tokenパラメータを含める必要があります。検索セッション内で行われる各APIコールは、コール1回ごとにレート制限にカウントされます。例えば、同じsession_tokenを用いて/suggestに連続で10回コールを行い、さらに/retrieveに1回コールを行うと、11回のリクエストを行ったことになります。ですが、請求の際には1つのセッションとしてカウントされます。Search APIの課金方法については、本ドキュメントにあるセッション毎の料金 のセクションで詳しく説明しています。

Search API使用料

Search APIの使用料は、検索セッションsearch sessionAPI callごとに請求されます。また、この使用料は、ご利用されているSearch APIのエンドポイントに応じて変動します。日本限定リリースされたベータ版での価格情報は、日本版の料金設定でご確認いただけます。このページでは、無料版に含まれるリクエスト数や、有料で行える追加リクエストの単価などの情報をご確認いただけます。

セッションの使用料

Search APIの/suggest/retrieveエンドポイントには、session_tokenパラメータを含める必要があります。共通のsession_tokenを持つ/suggest/retrieveに対するコールは、セッションごと の請求となります。セッション辺りの料金については、Mapbox担当営業までお問い合わせください。

以下の行為は、一回のセッションとしてカウントされます:

  • 共通のsession_tokenを用いて/suggestにコールをした後に/retrieve に連続でコールを行った場合。
  • 共通のsession_tokenを用いて/suggestに50回連続でコールを行った場合。
  • /suggestにコール後、60分以内に/retrieveにコールを行わなかった場合。

セッションあたりの価格に関しては、Mapbox担当営業までご連絡ください。

APIコールの使用料

Search APIの /forward, /permanent/forward, /reverse エンドポイントに対するコールは、APIコールごとの請求となります。これらのエンドポイントにコールする際の請求方法については、日本版の価格設定をご覧ください。