Parametri di richiesta

Questo documento descrive i parametri di richiesta per l'API Places Aggregate e include approfondimenti e best practice per l'utilizzo di questo servizio.

L'API Places Aggregate consente di eseguire diverse funzioni chiave:

• Conteggio dei luoghi: determina il numero di luoghi che corrispondono a criteri specifici, come tipo di località, stato di attività, livello di prezzo e valutazioni.
• Recupera i dettagli dei luoghi: ottieni i nomi dei luoghi che soddisfano i filtri specificati, quindi recupera informazioni più dettagliate utilizzando l'API Places.
• Filtri flessibili: applica filtri completi per ottenere aggregati precisi. I filtri disponibili includono:
  • Area geografica (cerchio, regione o poligono personalizzato)
  • Tipi di luoghi
  • Stato di attività
  • Livelli di prezzo
  • Intervalli di valutazione

Parametri obbligatori

Questa sezione illustra i parametri obbligatori per l'invio di una richiesta all'API Places Aggregate. Ogni richiesta deve fornire quanto segue:

• Un tipo di insight.
• Un filtro per località e un filtro per tipo.

Tipo di approfondimento

Specifica il tipo di insight che vuoi calcolare. Sono supportati i seguenti tipi di insight:

• INSIGHT_COUNT: restituisce il numero di luoghi corrispondenti ai criteri di filtro.
• INSIGHT_PLACES: restituisce gli ID luogo corrispondenti ai criteri di filtro.

Nota: se selezioni INSIGHT_PLACES, l'API Places Aggregate restituisce gli ID luogo solo se count è pari o inferiore a 100.

Filtri

Specifica i criteri per filtrare i luoghi. Come minimo, devi specificare LocationFilter e TypeFilter.

Filtro località

Un filtro di località può avere uno dei seguenti tipi:

• circle: definisce un'area come un cerchio con un centro e un raggio.
• region: : definisce un'area come regione.
• customArea: definisce un'area come poligono personalizzato.

Importante: l'area di qualsiasi filtro di località deve essere compresa tra 1556,86 metri quadrati (all'incirca le dimensioni di un piccolo isolato) e 2000 miliardi di metri quadrati (all'incirca le dimensioni dell'Alaska). Le richieste con aree al di fuori di questo intervallo restituiranno un errore INVALID_ARGUMENT.

Nota: per le entità con confini poligonali definiti, come parchi o aeroporti, l'entità viene considerata all'interno dell'area di ricerca se una parte del suo poligono interseca l'area di ricerca definita (cerchio, regione o poligono personalizzato). Il punto centrale dell'entità non deve necessariamente trovarsi all'interno dell'area di ricerca.

Cerchio

Se selezioni la tua area geografica come cerchio, devi fornire un center e un radius. center può essere una latitudine e una longitudine o l'ID luogo del centro del cerchio. Questo metodo consente un filtro preciso e accurato in base alla regione circolare definita.

• center:
  • latLng: latitudine e longitudine del centro del cerchio. Le latitudini devono essere un numero compreso tra -90 e 90 inclusi. La longitudine deve essere un numero compreso tra -180 e 180 inclusi.
  • place: ID luogo del centro del cerchio. Tieni presente che sono supportati solo i luoghi puntuali. Questa stringa deve iniziare con il prefisso places/.
• radius: raggio del cerchio in metri. Questo numero deve essere positivo.

Regione

Definisci la tua area come regione passando un ID luogo al parametro place. L'ID luogo rappresenta un'area geografica (ad esempio un'area rappresentabile da un poligono). Ad esempio, l'ID luogo di Tampa, FL è places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Tieni presente che non tutti gli ID luogo hanno una geometria ben definita e in questi casi l'API Places Aggregate restituisce un codice di errore 400 con un messaggio che indica che la regione non è supportata. Inoltre, per regioni geografiche complesse, le ottimizzazioni dell'elaborazione interna potrebbero portare a una leggera approssimazione per eccesso dell'area (fino al 2-3%) che rappresenta la regione.

Importante: quando utilizzi il filtro region con il tipo di insight INSIGHT_PLACES, le richieste che includono aree contese vengono rifiutate automaticamente per garantire l'accuratezza e la neutralità dei servizi Google. Le aree contese sono regioni con confini o rivendicazioni territoriali in conflitto tra paesi o entità diversi. I confini contestati vengono visualizzati come una linea grigia tratteggiata su Google Maps.

Per saperne di più su come vengono identificate le regioni contese, consulta Informazioni sui confini e sui nomi dei paesi.

Importante: Google non supporta alcuni ID luogo che appartengono ai seguenti tipi di regioni:

• Tipi di regioni così grandi da causare una latenza elevata.
• Tipi di regioni così piccoli da compromettere la conformità alla privacy.

Per determinare se un ID luogo rappresenta un tipo di luogo non supportato, passa l'ID luogo in una richiesta dell'API Geocoding. La risposta include l'array type che elenca i tipi di luogo associati all'ID luogo, ad esempio locality, neighborhood o country. Un luogo verrà rifiutato per il filtro per regione se uno dei suoi tipi corrisponde a questo elenco.

I tipi di luoghi non supportati includono:

• establishment: in genere indica un luogo che non è stato ancora classificato.
• intersection: indica un incrocio importante, di solito tra due strade principali.
• subpremise: indica un'entità indirizzabile al di sotto del livello della sede, ad esempio un appartamento, un'unità o una suite.

Nota: anche alcuni luoghi non elencati sopra potrebbero essere rifiutati se non hanno una geometria poligonale ben definita. Questo è più comune con tipi come neighborhood, locality, sublocality e le relative varianti numerate (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4). In questo caso viene restituito un codice di errore 400.

Area personalizzata

Definisce l'area di un poligono personalizzato utilizzando le coordinate di latitudine e longitudine.

Importante: le coordinate che definiscono i vertici del poligono devono essere elencate in ordine antiorario. Questo segue la convenzione standard di settore per la definizione dei poligoni, in cui l'ordine in senso antiorario indica che l'interno del poligono si trova a sinistra dei bordi del confine.

Importante: le aree personalizzate devono avere un massimo di 7000 vertici.

Puoi visitare https://geojson.io/ per disegnare un poligono personalizzato e inserire le coordinate nella richiesta. Un poligono deve avere almeno 4 coordinate, dove la prima e l'ultima coordinata sono identiche. Almeno 3 delle coordinate fornite devono essere univoche.

Le coordinate identiche consecutive verranno trattate come una singola coordinata. Tuttavia, le coordinate duplicate non consecutive (diverse dalle prime e ultime coordinate identiche richieste) genereranno un errore.

Inoltre, i lati non adiacenti non possono intersecarsi e non sono consentiti lati di lunghezza pari a 180 gradi (ovvero, i vertici adiacenti non possono essere antipodali).

Ad esempio:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

Filtro per tipo

Specifica i tipi di luoghi da includere o escludere. Per un elenco dei tipi di luoghi principali e secondari supportati dall'API Places Aggregate, consulta la Tabella A in Tipi di luoghi per l'API Places (nuova). Devi specificare almeno un tipo includedTypes o includedPrimaryTypes.

• includedTypes: elenco dei tipi di luoghi inclusi.
• excludedTypes: elenco dei tipi di luoghi esclusi.
• includedPrimaryTypes: elenco dei tipi di luoghi principali inclusi.
• excludedPrimaryTypes: elenco dei tipi di luoghi principali esclusi.

Per scoprire di più sul funzionamento dei filtri dei tipi e dei tipi di luoghi, consulta Scopri di più sui filtri dei tipi.

Nota: i filtri per tipo includono automaticamente i sottotipi dei tipi specificati. Ad esempio, se filtri in base a gym, i risultati includono anche i luoghi classificati nei relativi sottotipi, come yoga_studio.

Parametri facoltativi

Questi filtri sono facoltativi:

• operatingStatus: specifica gli stati dei luoghi da includere o escludere. Per impostazione predefinita, il filtro viene applicato in base a operatingStatus: OPERATING_STATUS_OPERATIONAL (un valore specifico).
• priceLevels: specifica i livelli di prezzo dei luoghi da includere. Per impostazione predefinita, non viene applicato alcun filtro per il livello di prezzo e vengono restituiti tutti i luoghi (compresi quelli senza informazioni sul livello di prezzo).
• ratingFilter: specifica l'intervallo di valutazione dei luoghi. Per impostazione predefinita, non viene applicato alcun filtro (tutte le classificazioni sono incluse nei risultati).

Stato di attività

Con il filtro operatingStatus, puoi filtrare in base allo stato di attività, ad esempio OPERATIONAL o TEMPORARILY_CLOSED. Il comportamento del filtro operatingStatus funziona nel seguente modo:

• Se non sono stati forniti filtri, nei risultati vengono inclusi solo i luoghi con uno stato di attività OPERATING_STATUS_OPERATIONAL.
• Se vengono forniti uno o più filtri, devi specificare valori validi per lo stato di attività (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED o OPERATING_STATUS_TEMPORARILY_CLOSED).

Livello dei prezzi

Con il filtro priceLevels, puoi filtrare i luoghi in base al loro livello di prezzo. I valori validi per il livello dei prezzi sono: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE e PRICE_LEVEL_VERY_EXPENSIVE.

Il comportamento del filtro priceLevels è il seguente:

• Se non vengono forniti filtri: vengono restituiti tutti i luoghi, indipendentemente dal fatto che abbiano un livello di prezzo assegnato. Sono inclusi i luoghi senza informazioni sul livello di prezzo, che potrebbero non essere restituiti quando si filtra in base a livelli di prezzo specifici.
• Se vengono forniti uno o più filtri: vengono restituiti solo i luoghi che corrispondono ai livelli di prezzo specificati.

Filtro valutazione

Filtra i luoghi in base alle valutazioni medie degli utenti. Entrambi i campi sono facoltativi, quindi se vengono omessi, per impostazione predefinita includeranno anche i luoghi che non hanno una valutazione.

• minRating: valutazione media minima degli utenti (tra 1,0 e 5,0).
• maxRating: valutazione media massima degli utenti (tra 1,0 e 5,0).

Inoltre, il valore minRating deve essere sempre inferiore o uguale al valore maxRating. Se minRating è specificato come maggiore di maxRating, viene restituito un errore INVALID_ARGUMENT.