はじめに
プレイス ID は、Google プレイスのデータベースおよび Google マップで、特定の場所を一意に識別する ID です。プレイス ID は、次の Maps API へのリクエストで承認されます。
- Geocoding API とジオコーディング サービス（Maps JavaScript API）でプレイス ID の住所を取得する。
- Routes API および Directions API（従来版）、ルートサービス、Maps JavaScript API（従来版）で出発地、目的地、中間地点を指定する。
- Routes API、Distance Matrix API（レガシー）、Distance Matrix Service、Maps JavaScript API（レガシー）で出発地と目的地を指定する。
- Places API（新）、Places SDK for Android（新）、Places SDK for iOS（新）、プレイス ライブラリで Place Details を取得する。
- Maps Embed API でプレイス ID パラメータを使用する。
- マップの URL で検索クエリを取得する。
- Roads API で制限速度を表示する。
- 境界線用データドリブン スタイル設定における境界ポリゴンの検索、スタイル設定を行う。
特定のプレイス ID の取得
特定の場所のプレイス ID を検索する場合は、以下のプレイス ID 検索ツールを使用して場所を検索し、ID を取得してください。
または、Maps JavaScript API のドキュメントにあるコードを使用して、プレイス ID 検索ツールを表示することもできます。
概要
プレイス ID は、場所を一意に識別するテキスト表記の ID です。識別子の長さはさまざまです（プレイス ID の長さに上限はありません）。例:
-
ChIJgUbEo8cfqokR5lP9_Wh_DaM -
GhIJQWDl0CIeQUARxks3icF8U8A -
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN -
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E -
IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ
プレイス ID は、お店やサービス、名所、公園、交差点など、ほとんどの場所に利用できます。同じ場所や拠点に、複数のプレイス ID が付与されている場合もあります。プレイス ID は今後変更される可能性があります。
Places API と複数の Google Maps Platform API で、同じプレイス ID を使用できます。たとえば、Places API、Maps JavaScript API、Geocoding API、Maps Embed API、Roads API で、同じプレイス ID を使用して場所を参照することができます。
プレイス ID を使って場所の詳細を取得する
一般的にプレイス ID は、Places API、または Maps JavaScript API のプレイス ライブラリを利用して場所を検索するために使用されます。次に、返されたプレイス ID を使用して Place Details を取得します。プレイス ID を保存しておき、その ID を使って後で同じ場所の詳細を取得することも可能です。詳しくは、このドキュメントの後半にあるプレイス ID の保存をご覧ください。
次の例は、Places API（新規）と Places API（従来版）でアイコンの URL をリクエストする方法を示しています。
Places API（新版）
Places API を使用して、テキスト検索（新版）リクエストを実行することで、プレイス ID を取得できます。
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'レスポンスには、次のように id フィールドにプレイス ID が含まれます。
{
"places": [
{
"id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
"formattedAddress": "29 King St, Sydney NSW 2000, Australia",
"displayName": {
"text": "Peace Harmony",
"languageCode": "en"
}
},
...
}リクエスト URL にプレイス ID を含めることで、Place Details（新版）リクエストを作成できるようになりました。
https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY
Places API（以前のバージョン）
Places API を使用すると、Place Search リクエストを実行してプレイス ID を見つけることができます。
次の例は、オーストラリアのシドニーにある地点から半径 1,500 m 以内にある「cruise」という単語を含む「restaurant」タイプの場所を検索するリクエストです。
https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY
レスポンスには、次のスニペットに示すように、place_id フィールドにプレイス ID が含まれます。
{
"html_attributions" : [],
"results" : [
{
"geometry" : {
"location" : {
"lat" : -33.870775,
"lng" : 151.199025
}
},
...
"place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
...
}
],
"status" : "OK"
}Place Details（以前のバージョン）リクエストを送信し、place_id パラメータにプレイス ID を指定します。
https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEYプレイス ID を後で使えるように保存する
プレイス ID は、Google Maps Platform 利用規約のセクション 3.2.3（b）で定められているキャッシュ制限の対象外となります。このため、プレイス ID 値は後で使用するために保存しても問題ありません。
保存済みのプレイス ID を更新する
Google マップのデータベースの更新によってプレイス ID が変更される可能性があるため、12 か月以上経過しているプレイス ID は更新することをおすすめします。プレイス ID は無料で更新できます。更新する場合は、fields パラメータのプレイス ID フィールドのみを指定して Place Details リクエストを実行します。
Places API（新版）
たとえば、Place Details（New）を使用する場合:
https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY
Places API（以前のバージョン）
たとえば、Places API（従来版）を使用する場合:
https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY
これにより、Place Detail New Essentials IDs Only または Places Details - ID Refresh の SKU がトリガーされます。
プレイス ID 使用時のエラーコード
INVALID_REQUEST
INVALID_REQUEST ステータス コードは、指定されたプレイス ID が無効であることを意味します。プレイス ID が不完全、または変更され、正しくない場合は、INVALID_REQUEST が返されることがあります。
NOT_FOUND
NOT_FOUND ステータス コードは、指定されたプレイス ID が古くなっていることを意味します。お店やサービスが閉業した場合や移転した場合、プレイス ID が古くなることがあります。プレイス ID は、Google マップのデータベースの更新によって変わることもあります。そのような場合、場所には新しいプレイス ID が付与され、古い ID は NOT_FOUND レスポンスを返します。
プレイス ID が古くなった場合に結果を更新するには、それぞれのプレイス ID を返した元のリクエストを保存しておき、必要に応じてリクエストを再発行します。再発行されたリクエストは、適切な SKU で請求されます。
プレイス ID の種類によっては、NOT_FOUND レスポンスが返される場合があります。また、API によって、レスポンスで別のプレイス ID が返される場合もあります。これに該当するのは次のようなプレイス ID です。
- Google マップ上に正確な住所はないものの、住所の範囲から推定される番地。
- リクエストで都市や地域区分も指定されている場合の長いルートの区間。
- 交差点。
subpremiseタイプの住所コンポーネントが含まれる場所。
ほとんどの場合、こうした場所の ID は長い文字列になります（プレイス ID の長さに上限はありません）。例は次のとおりです。
EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4