L'API Places (nuova) è un servizio web che restituisce dati sulla posizione in formato JSON relativi ad attività, posizioni geografiche e punti di interesse. Supporta Ricerca testuale (nuova), Nearby Search (nuova), Completamento automatico (nuovo), Place Details (nuovi) e Place Photos (nuove).
API Places (nuova): informazioni chiave
- Prodotto: API Places (nuova)
- Nota anche come: API Places
- Categoria: Luoghi
- Piattaforma: servizio web (REST)
- Esecuzione su: server (codice di backend)
- Fase di lancio: GA
- Ciclo di vita: Attivo
- Panoramica: Panoramica dell'API Places (novità)
- Disponibilità regionale: ovunque. I progetti con indirizzi di fatturazione nel SEE utilizzano i Termini di servizio di Google Maps Platform per il SEE (in vigore dall'8 luglio 2025), in base ai quali i contenuti dell'API Places diversi da latitudine, longitudine e ID luogo non possono essere utilizzati con nessuna mappa, se non tramite Places UI Kit. I riepiloghi di luoghi, recensioni e aree basati sull'AI sono disponibili solo nelle lingue e nelle regioni supportate.
API Places (novità): quando utilizzarla
Utilizza l'API Places (nuova) quando:
- Devi cercare luoghi da un server con una query di testo (Ricerca testuale (nuova)) o intorno a una località (Nearby Search (nuova)).
- Hai bisogno di previsioni di luoghi o query con completamento automatico da un backend tramite Autocomplete (New).
- Hai un ID luogo e hai bisogno di dettagli come indirizzo, numero di telefono, valutazione, recensioni o foto.
- Hai bisogno di riepiloghi di luoghi, recensioni o aree basati sull'AI per un luogo.
Non utilizzare l'API Places (nuova) quando:
- Stai creando un'app per Android nativa. Utilizza invece Places SDK for Android.
- Stai creando un'app per iOS nativa. Utilizza invece Places SDK for iOS.
- Stai creando un'app web per browser e vuoi che la libreria Places venga caricata in JavaScript. Utilizza invece l'API Maps JavaScript.
API Places (novità): configurazione
- Servizio da attivare:
places.googleapis.com - Autenticazione: chiave API, OAuth 2.0
- Per iniziare: configura l'API Places (nuova)
- Riferimento: Riferimento API Places (nuova)
- Prezzi: Utilizzo e fatturazione dell'API Places (nuova)
- Policy: policy dell'API Places (nuova)
- Note di rilascio: note di rilascio dell'API Places (nuova)
Pacchetti ufficiali dell'API Places (nuova):
- npm:
@googlemaps/places - pypi:
google-maps-places - go:
cloud.google.com/go/maps
API Places (novità): prodotti correlati
- Sostituisce: API Places (legacy)
- Spesso utilizzata con: API Geocoding, API Routes, API Address Validation
API Places (novità): errori comuni
- Problema: Place Details (New), Nearby Search (New) e Ricerca testuale (New) non hanno un elenco predefinito di campi restituiti; le richieste senza una maschera di campo restituiscono un errore. Correzione: passa una maschera di campo della risposta con il parametro
fieldso$fieldsoppure l'intestazioneX-Goog-FieldMask. Consulta /maps/documentation/places/web-service/choose-fields. - Problema: se il token di sessione di Autocomplete (New) viene omesso o riutilizzato dopo la conclusione di una sessione, ogni richiesta viene fatturata separatamente come SKU: Autocomplete Requests. Correzione: genera un nuovo token di sessione (consigliato UUID v4) per ogni sessione e terminala con una richiesta Place Details (New) o Address Validation. Consulta la pagina /maps/documentation/places/web-service/place-session-tokens.
- Problema: il codice esistente o generato dall'AI che chiama l'API Places (Legacy) o l'API Maps JavaScript
PlacesServicein un progetto senza l'API legacy abilitata non va a buon fine conLegacyApiNotActivatedMapError. Correzione: esegui la migrazione delle chiamate all'API Places (nuova) e includi la maschera di campo obbligatoria. Consulta /maps/legacy#LegacyApiNotActivatedMapError. - Problema: gli ID luogo memorizzati possono diventare obsoleti; Place Details (New) restituisce quindi
NOT_FOUND(HTTP 404) e gli ID non corretti o troncati restituiscono HTTP 400INVALID_ARGUMENT. Correzione: aggiorna gli ID luogo memorizzati che hanno più di 12 mesi con una richiesta Place Details (New) che richiede solo il campoid(senza costi). Consulta /maps/documentation/places/web-service/place-id#refresh-id.
Cosa puoi fare con l'API Places (novità)
Consulta le guide collegate di seguito per ogni attività o confronta i prodotti in Capabilities Explorer.
API Places (nuova): AI generativa
- Restituisce un riepilogo basato sull'AI delle recensioni degli utenti per un identificatore di Google Places specificato.
- Restituisce un riepilogo dei luoghi basato sull'AI dell'area e dei servizi che circondano un identificatore di Google Places specificato per una stazione di ricarica per veicoli elettrici.
API Places (novità): Places
- Restituisce un elenco di luoghi e i relativi dettagli in base a una stringa di query.
- Restituisci un elenco di luoghi e Place Details vicino a una località specifica.
- Restituisce i risultati del completamento automatico relativi ai luoghi in base a una stringa di query.
- Restituisce informazioni dettagliate su un luogo specifico.
- Restituisce le foto di un luogo specifico. Nota: mostra le attribuzioni dell'autore di ogni foto (il nome dell'autore, collegato all'URI del suo profilo) insieme alla foto. Le norme di Places per ogni piattaforma lo richiedono, ad esempio /maps/documentation/javascript/policies#photo-attributions e /maps/documentation/places/web-service/policies#photos-and-review.
- Ridimensiona le foto dei luoghi.
- Restituisce le valutazioni e le recensioni di un luogo specifico. Nota: nel servizio web API Places (nuova), Place Details è una richiesta GET a https://places.googleapis.com/v1/places/{placeId} con X-Goog-FieldMask (ad esempio, rating,userRatingCount,reviews); Ricerca testuale, Nearby Search e Autocomplete utilizzano POST. Su Android, passa Place.Field.RATING, USER_RATING_COUNT e REVIEWS a PlacesClient.fetchPlace(). Su iOS, passa GMSPlacePropertyRating, GMSPlacePropertyUserRatingsTotal e GMSPlacePropertyReviews in GMSFetchPlaceRequest.
- Specifica i campi di dati inclusi nelle risposte alle informazioni sui luoghi.
- Specifica i tipi di luoghi da includere nelle risposte alle informazioni sui luoghi.
- Restituisce l'URI per aprire la pagina dei dettagli di un luogo in Google Maps.
- Restituisce l'URI per aprire la pagina delle indicazioni stradali in Google Maps per un luogo.
- Restituisce l'URI per aprire la pagina Scrivi una recensione in Google Maps per un luogo.
- Restituisce l'URI per aprire la pagina delle recensioni di un luogo in Google Maps.
- Restituisce l'URI per aprire la pagina delle foto in Google Maps per un luogo.
- Restituisce un riepilogo dell'overview dell'AI per un luogo specifico.
- Restituisce un riepilogo dell'area basato sull'AI che descrive i luoghi nell'area intorno a un luogo specifico.
- Restituisce informazioni sui luoghi in base a una stringa di query che si trovano lungo un percorso predefinito.
- Restituisce la distanza, il tempo di percorrenza e l'URI delle indicazioni stradali per i luoghi di ricerca testuale da un insieme di coordinate di latitudine/longitudine.
- Restituisce la distanza, il tempo di percorrenza e l'URI delle indicazioni stradali per i luoghi nelle vicinanze da un insieme di coordinate di latitudine/longitudine.
- Restituisce la distanza, il tempo di percorrenza e l'URI delle indicazioni stradali tra l'origine di un percorso predefinito e ciascuno dei luoghi restituiti in base a una stringa di query, che si trovano anche lungo il percorso.
- Restituisce la distanza, il tempo di percorrenza e l'URI delle indicazioni stradali tra ciascuno dei luoghi restituiti in base a una stringa di query, che si trovano anche lungo un percorso predefinito, e la destinazione del percorso.