はじめに
プレイス ID の取得後 Place Details (New) リクエストを開始して、特定の店や スポットに関する詳細をリクエストできます。Place Details (New) リクエストは、指定の場所に関する包括的な情報(完全な住所、電話番号、ユーザーのレビューや評価など)を返します。
プレイス ID を取得する方法はたくさんあります。以下を使用できます。
API Explorer を使用すると、ライブ リクエストを作成して、API と API オプションに慣れることができます。
Place Details (New) リクエスト
Place Details (New) リクエストは、次のような形式の HTTP GET リクエストです。
https://places.googleapis.com/v1/places/PLACE_ID
すべてのパラメータを URL パラメータとして、または GET リクエストの一部としてヘッダーに渡します。次に例を示します。
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEYまたは curl コマンドで次のようにします。
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
Place Details (New) レスポンス
Place Details (New) は、レスポンスとして JSON オブジェクトを返します。レスポンスの説明:
- レスポンスは
Placeオブジェクトで表されます。Placeオブジェクトには、 場所に関する詳細情報が含まれています。 - リクエストで渡された FieldMask は、
Placeオブジェクトで返されるフィールドのリストを指定します。
完全な JSON オブジェクトは次の形式です。
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
必須パラメータ
-
FieldMask
レスポンス フィールド マスクを作成して、レスポンスで返すフィールドのリストを指定します。 URL パラメータ
$fieldsまたはfieldsを使用するか、HTTP ヘッダーX-Goog-FieldMaskを使用して、レスポンス フィールド マスクをメソッドに渡します。レスポンスで返されるフィールドのデフォルト リストはありません。 フィールド マスクを省略すると、メソッドはエラーを返します。フィールド マスキングは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間や 請求を回避できます。
返す場所のデータタイプのカンマ区切りのリストを指定します。たとえば、 場所の表示名と住所を取得する場合などです。
X-Goog-FieldMask: displayName,formattedAddress
*を使用してすべてのフィールドを取得します。X-Goog-FieldMask: *
次のフィールドを 1 つ以上指定します。
次のフィールドは、Place Details Essentials IDs Only SKU をトリガーします。
attributions
consumerAlert
id
movedPlace
movedPlaceId
name*
photos
*
nameフィールドには、場所の リソース名 形式の場所のリソース名が含まれます。places/PLACE_ID場所のテキスト名を取得するには、Pro SKU でdisplayNameフィールドをリクエストします。フィールドとそれに関連付けられた SKU の完全なリストについては、場所のデータ フィールド(新版)をご覧ください。
次のフィールドは、Place Details Essentials SKU をトリガーします。
addressComponents
addressDescriptor*
adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
* 住所記述子は、インドのお客様には一般提供されていますが、他の地域では試験運用版です。
フィールドとそれに関連付けられた SKU の完全なリストについては、場所のデータ フィールド(新版)をご覧ください。
次のフィールドは、Place Details Pro SKU をトリガーします。
accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsTypeLabel
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
openingDate
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
timeZone
utcOffsetMinutes
フィールドとそれに関連付けられた SKU の完全なリストについては、場所のデータ フィールド(新版)をご覧ください。
次のフィールドは、Place Details Enterprise SKU をトリガーします。
currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
transitStation
userRatingCount
websiteUriフィールドとそれに関連付けられた SKU の完全なリストについては、場所のデータ フィールド(新版)をご覧ください。
次のフィールドは、Place Details Enterprise + Atmosphere SKU をトリガーします。
allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries*
servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
* テキスト検索と周辺検索のみフィールドとそれに関連付けられた SKU の完全なリストについては、場所のデータ フィールド(新版)をご覧ください。
-
placeId
場所を一意に識別するテキスト表記の ID。 テキスト検索(新版)または 周辺検索(新版)から返されます。 プレイス ID について詳しくは、 プレイス ID の概要をご覧ください。
文字列
新しい API では、このフィールドはplaces/PLACE_IDは、場所の リソース名とも呼ばれます。Place Details(新版)、Nearby Search(新版)、テキスト検索(新版)リクエストからのレスポンスでは、この文字列はレスポンスのnameフィールドに含まれています。スタンドアロンの プレイス ID は、レスポンスのidフィールドに含まれています。displayNameと呼ばれます。
オプション パラメータ
languageCode
結果を返す言語。
- サポートされている言語の 一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
-
languageCodeが指定されていない場合、API はデフォルトでenに設定されます。無効な言語コードを指定すると、API はINVALID_ARGUMENTエラーを返します。 - API は、ユーザーと地域住民の両方が読める番地を提供できるよう 最善を尽くします。そのために、優先言語に従って、必要に応じてユーザーが読めるスクリプトに音訳された番地を現地の言語で返します。その他の 住所はすべて優先言語で返されます。住所コンポーネントは すべて同じ言語で返されます。この言語は最初の コンポーネントから選択されます。
- 優先言語で名前が使用できない場合、API は最も近い一致を使用します。
- 優先言語は、API が返す結果のセットと、結果が返される順序にわずかな影響を与えます。ジオコーダは、言語によって略語の解釈が異なります。たとえば、通りの種類の略語や、ある言語では有効でも別の言語では有効でない同義語などです。
regionCode
レスポンスのフォーマットに使用されるリージョン コード。 2 文字の CLDR コード値として指定します。デフォルト値はありません。
レスポンスの
formattedAddressフィールドの国名がregionCodeと一致する場合、国コードはformattedAddressから省略されます。 このパラメータは、常に国名を含むadrFormatAddressにも、国名を含まないshortFormattedAddressにも影響しません。ほとんどの CLDR コードは ISO 3166-1 コードと同一ですが、 いくつか注意が必要な例外もあります。たとえば、イギリスの ccTLD は 「uk」(.co.uk)ですが、ISO 3166-1 コードは「gb」(厳密には 「グレートブリテンおよび北アイルランド連合王国」のエンティティ)です。 このパラメータは、適用される法律に基づいて結果に影響を与える可能性があります。
-
sessionToken
セッション トークンは、オートコンプリート(新版)の呼び出しを 「セッション」として追跡するユーザー生成の文字列です。オートコンプリート(新版)はセッション トークンを使用して、予測入力検索でのユーザーのクエリと場所の選択フェーズを、請求処理のために個別のセッションにグループ化します。セッション トークンは、オートコンプリート(新版)の呼び出しに続く Place Details(新版) の呼び出しに渡されます。詳細については、 セッション トークンをご覧ください。
Place Details (New) の例
次の例では、placeId で場所の詳細をリクエストします。
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
X-Goog-FieldMask ヘッダーは、レスポンスに id,displayName のデータ フィールドが含まれることを指定します。レスポンスは次の形式になります。
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
フィールド マスクにデータタイプを追加して、追加情報を返します。
たとえば、formattedAddress,plusCode を追加して、
レスポンスに
住所と Plus Code を含めます。
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
レスポンスは次の形式になります。
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "plusCode": { "globalCode": "849VCWC7+RW", "compoundCode": "CWC7+RW Mountain View, CA, USA" }, "displayName": { "text": "Googleplex", "languageCode": "en" } }
住所記述子を取得する
住所記述子は、近くの ランドマークや含まれるエリアなど、場所の位置に関するリレーショナル情報を提供します。
次の例は、サンノゼのショッピング モールにあるデパートの Place Details (New) リクエストを示しています
。この例では、フィールド マスクに addressDescriptors
を含めます。
curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: name,displayName,addressDescriptor"
レスポンスには、リクエストで指定された場所、近くのランドマークとその場所からの 距離のリスト、エリアとその場所との 包含関係のリストが含まれます。
{ "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "displayName": { "text": "Macy's", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "food", "movie_theater", "point_of_interest", "restaurant", "shoe_store", "shopping_mall", "store" ], "spatialRelationship": "WITHIN", "straightLineDistanceMeters": 220.29175 }, { "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4", "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4", "displayName": { "text": "Nordstrom", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 329.45178 }, { "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "displayName": { "text": "Monroe Parking Garage", "languageCode": "en" }, "types": [ "establishment", "parking", "point_of_interest" ], "straightLineDistanceMeters": 227.05153 }, { "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM", "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM", "displayName": { "text": "Studios Inn by Daiwa Living California Inc.", "languageCode": "en" }, "types": [ "establishment", "lodging", "point_of_interest", "real_estate_agency" ], "straightLineDistanceMeters": 299.9955 }, { "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "displayName": { "text": "Din Tai Fung", "languageCode": "en" }, "types": [ "establishment", "food", "point_of_interest", "restaurant" ], "straightLineDistanceMeters": 157.70943 } ], "areas": [ { "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "displayName": { "text": "Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM", "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM", "displayName": { "text": "Central San Jose", "languageCode": "en" }, "containment": "WITHIN" } ] } }
移動した場所の Place Details を取得する
アプリで参照されている場所が移転した場合は、
movedPlace フィールドと movedPlaceId フィールドを使用して、新しい場所の詳細を取得できます。
閉業した 場所の場合、Place Details(新版)は CLOSED_PERMANENTLY を
businessStatus フィールドに返し、レスポンスの本文で movedPlace と
movedPlaceId フィールドを省略します。
新しい場所に移転した 場所の場合、Place Details(新版)は CLOSED_PERMANENTLY を
businessStatus フィールドに返し、レスポンスの本文の movedPlace と
movedPlaceId フィールドに新しい場所を返します。
**移動していない** 場所の場合、Place Details(新版)はレスポンスの本文に
movedPlace または movedPlaceId を返しません。
次の例では、カナダのケベック州にある Marche IGA St-Canut の場所情報をリクエストします。
curl -X GET -H 'Content-Type: application/json' \ -H 'x-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \ https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ
リクエストは次のレスポンスを返します。
{ "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ", "businessStatus": "CLOSED_PERMANENTLY", "displayName": { "text": "Marche IGA St-Canut", "languageCode": "en" }, "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ", "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ" }
新しい場所の詳細をリクエストするには、新しい Place Details (New) リクエストの movedPlace フィールド
で場所のリソース名を使用します。
複数回移転した 場所の場合、現在の場所の詳細を取得するには
、複数の Place Details (New) リクエストをチェーン接続する必要がある場合があります。場所の結果の movedPlace フィールドと
movedPlaceId フィールドは、最後に
確認された場所ではなく、次の場所のみを指します。Place Details (New) リクエスト
でレスポンスの本文の movedPlace フィールドと movedPlaceId フィールドが省略されている場合、場所は現在の場所にあります。
今後オープンするビジネスを探す
今後オープンする予定のビジネスの詳細をリクエストできます。
Nearby Search(新版)は、openingDate フィールドに、オープン予定日が少なくとも月を含み、90 日未満の場合、入力します。
次の例は、アイダホ州ニューメドウズで今後オープンするビジネスの Nearby Search(新版)リクエストを示しています。
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,businessStatus,openingDate" \ "https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"
レスポンスには、場所のビジネス ステータスとオープン予定日が含まれます。
{ "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "openingDate": { "year": 2026, "month": 4, "day": 15 } }
交通機関の駅の情報を取得する
Place Details(新版)を使用して、交通機関の駅に関する情報を取得できます。レスポンスの本文には、駅名、提携する交通機関、駅に乗り入れている路線など、駅に関する情報が含まれます。また、レスポンスには、交通機関の駅の情報を表示するために使用できる車両のアイコンと色が含まれます。
次の例は、グランドセントラル駅の交通機関の駅の情報をリクエストしています。
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,transitStation" \ "https://places.googleapis.com/v1/places/ChIJLVaKiQFZwokRgcybX3K6Pzg"
レスポンスの本文には、半径内の各駅の情報、駅に乗り入れている路線、その停留所で交通機関が発行したアラート、出発情報が含まれます。
{ "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "MTA New York City Transit", "languageCode": "en" }, "url": "http://www.mta.info/", "lines": [ { "id": "ChIJ420yFwBZwokR903kVZLSsFc", "vehicleType": "SUBWAY", "displayName": { "text": "42 St Shuttle", "languageCode": "en" }, "shortDisplayName": { "text": "S", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#808183", "url": "https://www.mta.info/schedules/subway/42-st-shuttle", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } }, { "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM", "vehicleType": "SUBWAY", "displayName": { "text": "5 Train (Lexington Av Express)", "languageCode": "en" }, "shortDisplayName": { "text": "5 Line", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#00933C", "url": "https://www.mta.info/schedules/subway/5-train", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } } ... ] }, { "displayName": { "text": "MTA", "languageCode": "en" }, "url": "https://new.mta.info/", "lines": [ { "id": "ChIJcwVpzKpZwokR24EBeh8arww", "vehicleType": "BUS", "displayName": { "text": "United Nations - W 42 St Pier", "languageCode": "en" }, "shortDisplayName": { "text": "M42", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#1D59B3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" } } ] }, { "displayName": { "text": "Long Island Rail Road", "languageCode": "en" }, "url": "http://www.mta.info/lirr", "lines": [ { "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Ronkonkoma Branch", "languageCode": "en" }, "shortDisplayName": { "text": "LIRR", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#A626AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" } } ... ] } ], "stops": [ { "id": "ChIJRcemlf1YwokRhFqqw5jKBFM", "stopCode": { "text": "GCT" }, "location": { "latitude": 40.755161, "longitude": -73.975456 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJ57l2zANZwokRD1pyhuwpfKY", "signageText": { "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7", "languageCode": "en" }, "location": { "latitude": 40.750983, "longitude": -73.9750686 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc", "displayName": { "text": "E 42 St/Park Av", "languageCode": "en" }, "location": { "latitude": 40.7518199, "longitude": -73.9771918 }, "wheelchairAccessibleEntrance": true } ... ] } }
入り口とナビゲーション ポイントを取得する
目的地の入り口とナビゲーション ポイントをリクエストできます。入り口は、場所の出入り口(空港やショッピング モールの異なるゲートなど)を定義します。ナビゲーション ポイントは、ナビゲーションを終了する道路沿いの場所を定義します。これは、ユーザーを道路の正しい側や特定の降車場所に誘導するのに役立ちます。
ナビゲーション ポイントは navigationPointToken を返します。このトークンを Navigation SDK(Android または iOS で利用可能)または Routes API に渡して、ドライバーを特定の場所に誘導できます。詳細については、ナビゲーション ポイント トークンをご覧ください。
次の例では、サンフランシスコ国際空港(プレイス ID ChIJVVVVVYx3j4ARP-3NGldc8qQ)の詳細をリクエストします。フィールド マスクに entrances と navigationPoints を含めます。
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,entrances,navigationPoints" \ https://places.googleapis.com/v1/places/ChIJVVVVVYx3j4ARP-3NGldc8qQ
レスポンスには、場所の入り口とナビゲーション ポイントが含まれます。
{ "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "entrances": [ { "location": { "latitude": 37.6172154, "longitude": -122.3839724 } }, { "location": { "latitude": 37.6174073, "longitude": -122.384196 } }, ... ], "navigationPoints": [ { "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...", "displayName": { "text": "International Terminal Departures Level", "languageCode": "en" }, "location": { "latitude": 37.6153121, "longitude": -122.3900833 }, "travelModes": ["WALK"] }, { "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...", "displayName": { "text": "Domestic Garage - SFO Short Term Parking", "languageCode": "en" }, "location": { "latitude": 37.6157153, "longitude": -122.3885012 }, "travelModes": ["DRIVE", "WALK"], "usages": ["PARKING"] }, ... ] }
試してみよう:
API Explorer を使用すると、サンプル リクエストを作成して、API と API オプションに慣れることができます。
ページの右側にある API アイコン api を選択します。
必要に応じて、リクエスト パラメータを編集します。
[実行] ボタンを選択します。ダイアログで、リクエストの送信に使用するアカウント を選択します。
API Explorer パネルで、全画面表示アイコン fullscreen を選択して、API Explorer ウィンドウを拡大します。