Riferimento rapido dell'API Places (novità)

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:

API Places (novità): configurazione

Pacchetti ufficiali dell'API Places (nuova):

  • npm: @googlemaps/places
  • pypi: google-maps-places
  • go: cloud.google.com/go/maps

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 fields o $fields oppure l'intestazione X-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 PlacesService in un progetto senza l'API legacy abilitata non va a buon fine con LegacyApiNotActivatedMapError. 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 400 INVALID_ARGUMENT. Correzione: aggiorna gli ID luogo memorizzati che hanno più di 12 mesi con una richiesta Place Details (New) che richiede solo il campo id (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

API Places (novità): Places