Dettagli luogo (nuovo)

Seleziona la piattaforma: Android iOS JavaScript Servizio web
Sviluppatori dello Spazio economico europeo (SEE)

Introduzione

Una volta che hai un ID luogo, puoi richiedere maggiori dettagli su una determinata attività o punto d'interesse avviando una richiesta Place Details (New). Una richiesta Place Details (New) restituisce informazioni più complete sul luogo indicato, come l'indirizzo completo, il numero di telefono, la valutazione degli utenti e le recensioni.

Esistono molti modi per ottenere un ID luogo. Puoi utilizzare:

L'Explorer API ti consente di effettuare richieste live per familiarizzare con l'API e le opzioni dell'API:

Richieste Place Details (New)

Una richiesta Place Details (New) è una richiesta HTTP GET nel formato:

https://places.googleapis.com/v1/places/PLACE_ID

Passa tutti i parametri come parametri URL o nelle intestazioni come parte della richiesta GET. Ad esempio:

https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY

Oppure in un comando 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

Risposte Place Details (New)

Place Details (New) restituisce un oggetto JSON come risposta. Nella risposta:

  • La risposta è rappresentata da un Place oggetto. L'oggetto Place contiene informazioni dettagliate sul luogo.
  • Il FieldMask passato nella richiesta specifica l'elenco dei campi restituiti nell'oggetto Place.

L'oggetto JSON completo ha il seguente formato:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

Parametri obbligatori

  • FieldMask

    Specifica l'elenco dei campi da restituire nella risposta creando una maschera dei campi di risposta. Passa la maschera dei campi di risposta al metodo utilizzando il parametro URL $fields o fields, oppure utilizzando l'intestazione HTTP X-Goog-FieldMask. Nella risposta non è presente un elenco predefinito di campi restituiti. Se ometti la maschera dei campi, il metodo restituisce un errore.

    La maschera dei campi è una buona pratica di progettazione per assicurarti di non richiedere dati non necessari, il che aiuta a evitare tempi di elaborazione e addebiti di fatturazione non necessari.

    Specifica un elenco separato da virgole dei tipi di dati del luogo da restituire. Ad esempio, per recuperare il nome visualizzato e l'indirizzo del luogo.

    X-Goog-FieldMask: displayName,formattedAddress

    Utilizza * per recuperare tutti i campi.

    X-Goog-FieldMask: *

    Specifica uno o più dei seguenti campi:

    • I seguenti campi attivano lo SKU Place Details Essentials IDs Only:

      attributions
      id
      moved_place
      moved_place_id
      name*
      photos

      * Il campo name contiene il nome della risorsa del luogo nel formato: places/PLACE_ID. Per ottenere il nome testuale del luogo, richiedi il campo displayName nello SKU Pro.

    • I seguenti campi attivano lo SKU Place Details Essentials:

      addressComponents
      addressDescriptor*
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

      * I descrittori dell'indirizzo sono generalmente disponibili per i clienti in India e sono sperimentali altrove.

    • I seguenti campi attivano lo SKU Place Details Pro:

      accessibilityOptions
      businessStatus
      containingPlaces
      displayName
      googleMapsLinks
      googleMapsUri
      iconBackgroundColor
      iconMaskBaseUri
      openingDate
      primaryType
      primaryTypeDisplayName
      pureServiceAreaBusiness
      subDestinations
      timeZone
      utcOffsetMinutes

    • I seguenti campi attivano lo SKU Place Details Enterprise:

      currentOpeningHours
      currentSecondaryOpeningHours
      internationalPhoneNumber
      nationalPhoneNumber
      priceLevel
      priceRange
      rating
      regularOpeningHours
      regularSecondaryOpeningHours
      transitStation
      userRatingCount
      websiteUri

    • I seguenti campi attivano lo SKU Place Details Enterprise + Atmosphere:

      allowsDogs
      consenteCanicurbsidePickup
      ritiroSulMarciapiededelivery
      consegnadineIn
      mangiaSulPostoeditorialSummary
      riepilogoEditorialeevChargeAmenitySummary
      riepilogoServiziRicaricaEVevChargeOptions
      opzioniRicaricaEVfuelOptions
      opzioniCarburantegenerativeSummary
      riepilogoGenerativogoodForChildren
      adattoAiBambinigoodForGroups
      adattoAiGruppigoodForWatchingSports
      adattoPerGuardareEventiSportiviliveMusic
      musicaDalVivomenuForChildren
      menuPerBambinineighborhoodSummary
      riepilogoQuartiereparkingOptions
      opzioniParcheggiopaymentOptions
      opzioniPagamentooutdoorSeating
      postiAllApertoreservable
      prenotabilerestroom
      bagnoreviews
      recensionireviewSummary
      riepilogoRecensioniroutingSummaries*
      riepiloghiPercorsiservesBeer
      serveBirraservesBreakfast
      serveColazioneservesBrunch
      serveBrunchservesCocktails
      serveCocktailservesCoffee
      serveCaffeservesDessert
      serveDolciservesDinner
      serveCenaservesLunch
      servePranzoservesVegetarianFood
      serveCiboVegetarianoservesWine
      serveVinotakeout
      daAsporto
      * Solo Ricerca testuale e Ricerca nelle vicinanze

  • placeId

    Un identificatore testuale che identifica in modo univoco un luogo, restituito da una Ricerca testuale (New) o da una Nearby Search (New). Per saperne di più sugli ID luogo, consulta la panoramica degli ID luogo.

    La stringa places/PLACE_ID è detta anche nome della risorsa del luogo. Nella risposta a una richiesta Place Details (New), Ricerca nelle vicinanze (New) e Ricerca testuale (New) questa stringa è contenuta nel campo name della risposta. L'ID luogo autonomo è contenuto nel campo id della risposta.

Parametri facoltativi

  • languageCode

    La lingua in cui restituire i risultati.

    • Consulta l'elenco delle lingue supportate . Google aggiorna spesso le lingue supportate, quindi questo elenco potrebbe non essere esaustivo.
    • Se languageCode non viene fornito, l'API utilizza per impostazione predefinita en. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • L'API fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in uno script leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, scelta dal primo componente.
    • Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.
    • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra.

  • regionCode

    Il codice regione utilizzato per formattare la risposta, specificato come valore del codice CLDR di due caratteri. Non è presente un valore predefinito.

    Se il nome del paese del campo formattedAddress nella risposta corrisponde a regionCode, il codice paese viene omesso da formattedAddress. Questo parametro non ha alcun effetto su adrFormatAddress, che include sempre il nome del paese o su shortFormattedAddress, che non lo include mai.

    La maggior parte dei codici CLDR sono identici ai codici ISO 3166-1, con alcune eccezioni importanti. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il suo codice ISO 3166-1 è "gb" (tecnicamente per l' entità "Regno Unito di Gran Bretagna e Irlanda del Nord"). Il parametro può influire sui risultati in base alla legge applicabile.

  • sessionToken

    I token di sessione sono stringhe generate dall'utente che monitorano le chiamate Autocomplete (New) come "sessioni." Autocomplete (New) utilizza i token di sessione per raggruppare le fasi di query e selezione del luogo di una ricerca di completamento automatico dell'utente in una sessione discreta a fini di fatturazione. I token di sessione vengono passati alle chiamate Place Details (New) che seguono le chiamate Autocomplete (New). Per saperne di più, vedi Token di sessione.

Esempio di Place Details (New)

L'esempio seguente richiede i dettagli di un luogo in base a 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

Tieni presente che l'intestazione X-Goog-FieldMask specifica che la risposta contiene i seguenti campi di dati: id,displayName. La risposta ha il seguente formato:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

Aggiungi altri tipi di dati alla maschera dei campi per restituire informazioni aggiuntive. Ad esempio, aggiungi formattedAddress,plusCode per includere l' indirizzo e il codice Plus nella risposta:

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

La risposta ha ora il seguente formato:

{
  "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"
  }
}

Recuperare i descrittori dell'indirizzo

I descrittori dell'indirizzo forniscono informazioni relazionali sulla posizione di un luogo, inclusi i punti di riferimento nelle vicinanze e le aree contenenti.

L'esempio seguente mostra una richiesta Place Details (New) per un grande magazzino in un centro commerciale di San Jose. In questo esempio, includi addressDescriptors nella maschera dei campi:

  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"

La risposta include il luogo specificato nella richiesta, un elenco di punti di riferimento nelle vicinanze e la relativa distanza dal luogo e un elenco di aree e la relativa relazione di contenimento con il luogo:

  {
    "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"
        }
      ]
    }
  }

Visualizzare i dettagli del luogo per un luogo spostato

Se un luogo a cui fai riferimento nella tua app è stato trasferito, puoi utilizzare i campi movedPlace e movedPlaceId per visualizzare i dettagli del nuovo luogo.

Per i luoghi chiusi definitivamente, Place Details (New) restituisce CLOSED_PERMANENTLY nel businessStatus campo e omette i campi movedPlace e movedPlaceId nel corpo della risposta.

Per i luoghi che sono stati trasferiti in una nuova sede, Place Details (New) restituisce CLOSED_PERMANENTLY nel campo businessStatus e restituisce la nuova sede nei campi movedPlace e movedPlaceId del corpo della risposta.

Per i luoghi che non sono stati spostati, Place Details (New) non restituisce movedPlace o movedPlaceId nel corpo della risposta.

L'esempio seguente richiede informazioni sul luogo Marche IGA St-Canut in Quebec, Canada:

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

La richiesta restituisce la seguente risposta:

{
  "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ",
  "businessStatus": "CLOSED_PERMANENTLY",
  "displayName": {
    "text": "Marche IGA St-Canut",
    "languageCode": "en"
  },
  "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ",
  "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ"
}

Per richiedere i dettagli del nuovo luogo, utilizza il nome della risorsa Place nel campo movedPlace in una nuova richiesta Place Details (New).

Per i luoghi che sono stati trasferiti più volte, per ottenere i dettagli della sede attuale potrebbero essere necessarie più richieste Place Details (New) concatenate. I campi movedPlace e movedPlaceId di un risultato del luogo puntano solo alla sede successiva, non all'ultima sede nota. Un luogo si trova nella sua sede attuale se una richiesta Place Details (New) omette i campi movedPlace e movedPlaceId nel corpo della risposta.

Trovare le attività che apriranno in futuro

Puoi richiedere i dettagli delle attività che dovrebbero aprire in futuro. Nearby Search (New) popolerà il campo openingDate se la data di apertura prevista include almeno il mese e manca meno di 90 giorni.

L'esempio seguente mostra una richiesta Nearby Search (New) per un'attività che aprirà in futuro a New Meadows, Idaho:

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"

La risposta include lo stato dell'attività del luogo e la data di apertura prevista:

{
  "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
  "businessStatus": "FUTURE_OPENING",
  "openingDate": {
    "year": 2026,
    "month": 4,
    "day": 15
  }
}

Visualizzare le informazioni sulla stazione di transito

Puoi utilizzare Place Details (New) per visualizzare le informazioni sulle stazioni di transito. Il corpo della risposta include informazioni sulla stazione, tra cui il nome della stazione, le aziende di trasporto pubblico affiliate e le linee di trasporto pubblico che servono la stazione. Inoltre, la risposta include un'icona del veicolo e i colori che puoi utilizzare per visualizzare le informazioni sulla stazione di transito.

L'esempio seguente mostra una richiesta di informazioni sulla stazione di transito per la Grand Central Station:

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"

Il corpo della risposta include informazioni su ogni stazione nel raggio, sulle linee servite dalla stazione, sugli avvisi emessi dalle aziende di trasporto pubblico presso la fermata e sulle informazioni sulle partenze:

  {
  "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
      }
      ...
    ]
  }
}

Fai una prova!

L'Explorer API ti consente di effettuare richieste di esempio per familiarizzare con l'API e le opzioni dell'API.

  1. Seleziona l'icona dell'API api sul lato destro della pagina.

  2. Se vuoi, modifica i parametri della richiesta.

  3. Seleziona il pulsante Esegui. Nella finestra di dialogo, scegli l'account che vuoi utilizzare per effettuare la richiesta.

  4. Nel riquadro Explorer API, seleziona l'icona a schermo intero fullscreen per espandere la finestra Explorer API.