はじめに
プレイス ID を取得したら、Place Details (New) リクエストを開始して、特定の店やスポットに関する詳細をリクエストできます。Place Details(新版)リクエストは、指定の場所に関する包括的な情報(完全な住所、電話番号、ユーザーのレビューや評価など)を返します。
プレイス 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(新版)のレスポンス
Place Details(新版)は、 レスポンスとして 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。テキスト検索(新版)またはNearby Search(新版)から返されます。プレイス ID について詳しくは、プレイス ID の概要をご覧ください。
文字列
places/PLACE_IDは、プレイス リソース名とも呼ばれます。Place Details(新版)、Nearby Search(新版)、テキスト検索(新版)のリクエストからのレスポンスでは、この文字列はレスポンスのnameフィールドに含まれます。スタンドアロンのプレイス ID は、レスポンスのidフィールドに含まれています。
オプション パラメータ
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
セッション トークンは、Autocomplete(新版)の呼び出しを「セッション」として追跡するユーザー生成の文字列です。Autocomplete(新版)はセッション トークンを使用して、予測入力検索でのユーザーのクエリと場所の選択フェーズを、請求処理のために個別のセッションにグループ化します。セッション トークンは、Autocomplete(新規)呼び出しに続く Place Details(新規)呼び出しに渡されます。詳細については、セッション トークンをご覧ください。
Place Details(新規)の例
次の例では、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 を追加して、レスポンスに住所とプラスコードを含めます。
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(新)リクエストを示しています。この例では、フィールド マスクに 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(新版)は businessStatus フィールドに CLOSED_PERMANENTLY を返し、レスポンス本文の movedPlace フィールドと movedPlaceId フィールドを省略します。
新しい場所に移動した場所の場合、Place Details(新版)は businessStatus フィールドで CLOSED_PERMANENTLY を返し、レスポンス本文の 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(新版)リクエストの movedPlace フィールドで Place リソース名を使用します。
複数回移転した場所の場合、現在の場所の詳細を取得するには、複数の Place Details(新版)リクエストをチェーンする必要がある場合があります。場所の結果の movedPlace フィールドと movedPlaceId フィールドは、最後に見かけた場所ではなく、次の場所のみを指します。Place Details(新版)リクエストのレスポンスの本文で movedPlace フィールドと movedPlaceId フィールドが省略されている場合、その場所は現在の場所にあります。
今後オープン予定のビジネスを探す
今後オープン予定のビジネスの詳細をリクエストできます。
Nearby Search(新機能)では、予定されているオープン日が少なくとも月を含み、90 日以内である場合、openingDate フィールドが入力されます。
次の例は、アイダホ州ニューメドウズで今後オープンするビジネスの 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 に渡して、ドライバーを特定の場所に誘導できます。詳しくは、ナビゲーション ポイント トークンをご覧ください。
次の例では、フィールド マスクに entrances と navigationPoints を含めて、サンフランシスコ国際空港(プレイス ID ChIJVVVVVYx3j4ARP-3NGldc8qQ)の詳細をリクエストしています。
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 ウィンドウを拡大します。