Search

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

Search APIエンドポイント

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

サジェスト

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

取得

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

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

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

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

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

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

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

パーマネントリバースジオコーディング

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

行政区画タイプ

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

サジェストの取得

GET /search/v1/suggest/{search_text}

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

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

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

# Search for 新橋一丁十番一号,東京都港区新橋1丁目10番1号 using language, country, proximity, and limit parameters

$ curl "https://api.mapbox.com/search/v1/suggest/新橋一丁十番一号,東京都港区新橋1丁目10番1号?language=ja&limit=1&session_token=[GENERATED-UUID]&proximity=13.38333,52.51667&country=JP&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

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

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

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

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

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

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

{
  "suggestions": [{
    "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
    "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
    "description": "",
    "result_type": [
      "address"
    ],
    "language": "ja",
    "action": {
      "endpoint": "retrieve",
      "method": "POST",
      "body": {
        "id": "abc123"
      },
      "multi_retrievable": false
    },
    "maki": "marker",
    "internal_id": "example internal id",
    "external_ids": {
      "service": "2wwRMXwBRYqRl13lTvTP"
    },
    "context": [{
        "layer": "block",
        "localized_layer": "block",
        "name": "10"
      },
      {
        "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": "東京都"
      }
    ],
    "metadata": {
      "iso_3166_1": "jp",
      "iso_3166_2": "JP-13",
      "reading": {
        "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
        "ja_latin": "toukyouto minatoku shinbashi"
      }
    }
  }],
  "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": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "4b659949-c8c7-42d8-a541-6b427e5806cc"
}

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

POST /search/v1/retrieve/

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

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

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

リクエストボディの例:

{
	"id": "12345"
}

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

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

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

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

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.7596417,
        35.6675028
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "description": "",
      "place_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "id": "2wwRMXwBRYqRl13lTvTP",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "block",
          "localized_layer": "block",
          "name": "10"
        },
        {
          "layer": "chome",
          "localized_layer": "chome",
          "name": "1丁目"
        },
        {
          "layer": "oaza",
          "localized_layer": "oaza",
          "name": "新橋"
        },
        {
          "layer": "city",
          "localized_layer": "city",
          "name": "港区"
        },
        {
          "layer": "prefecture",
          "localized_layer": "prefecture",
          "name": "東京都"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "japan_address": "2wwRMXwBRYqRl13lTvTP"
      },
      "accuracy": "rooftop",
      "address": "〒105-0004 東京都港区新橋1丁目10番1号",
      "address_number": "1",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13",
        "reading": {
          "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
          "ja_latin": "toukyouto minatoku shinbashi"
        }
      }
    }
  }],
  "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": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "55491b50-f5df-4725-aeb1-3e8ed4a07b17"
}

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

GET /search/v1/forward/{search_text}

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

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

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

$ curl "https://api.mapbox.com/search/v1/forward/新橋一丁十番一号,東京都港区新橋1丁目10番1号?language=ja&limit=1&proximity=13.38333,52.51667&country=JP&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です。

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

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

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

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.7596417,
        35.6675028
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "matching_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "description": "",
      "place_name": "〒105-0004 東京都港区新橋1丁目10番1号",
      "id": "2wwRMXwBRYqRl13lTvTP",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "block",
          "localized_layer": "block",
          "name": "10"
        },
        {
          "layer": "chome",
          "localized_layer": "chome",
          "name": "1丁目"
        },
        {
          "layer": "oaza",
          "localized_layer": "oaza",
          "name": "新橋"
        },
        {
          "layer": "city",
          "localized_layer": "city",
          "name": "港区"
        },
        {
          "layer": "prefecture",
          "localized_layer": "prefecture",
          "name": "東京都"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "japan_address": "2wwRMXwBRYqRl13lTvTP"
      },
      "accuracy": "rooftop",
      "address": "〒105-0004 東京都港区新橋1丁目10番1号",
      "address_number": "1",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-13",
        "reading": {
          "ja_kana": "ﾄｳｷｮｳﾄﾐﾅﾄｸｼﾝﾊﾞｼ",
          "ja_latin": "toukyouto minatoku shinbashi"
        }
      }
    }
  }],
  "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": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "733725e4-3992-43e5-9cad-bac75698eb59"
}

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

GET /search/v1/reverse/{search_text}

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

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

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

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

パーマネントリバースジオコーディング

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

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

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

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

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

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

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

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "coordinates": [
        139.58041388935513,
        35.29559166696336
      ],
      "type": "Point"
    },
    "properties": {
      "feature_name": "逗子5丁目2番",
      "matching_name": "逗子5丁目2番",
      "description": "日本, 神奈川県逗子市逗子5丁目2番16",
      "place_name": "日本, 神奈川県逗子市逗子5丁目2番16",
      "id": "address.141324126",
      "place_type": [
        "address"
      ],
      "context": [{
          "layer": "postcode.15947689941269040",
          "localized_layer": "postcode.15947689941269040",
          "name": "249-0006"
        },
        {
          "layer": "place.9212495244633840",
          "localized_layer": "place.9212495244633840",
          "name": "逗子市"
        },
        {
          "layer": "region.3991212366959510",
          "localized_layer": "region.3991212366959510",
          "name": "神奈川県"
        },
        {
          "layer": "country.9827633378530190",
          "localized_layer": "country.9827633378530190",
          "name": "日本"
        }
      ],
      "language": "ja",
      "maki": "marker",
      "internal_id": "example internal id",
      "external_ids": {
        "carmen": "address.141324126",
        "federated": "carmen.address.141324126"
      },
      "accuracy": "point",
      "address_number": "16",
      "metadata": {
        "iso_3166_1": "jp",
        "iso_3166_2": "JP-14"
      },
      "routable_points": []
    }
  }],
  "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": "11:061a06471ec519420eeca5be2b87e043f2fe4cbe",
  "response_uuid": "29135029-2b4d-477e-bc30-67303b12ddad"
}

Search APIのエラー

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