Parametri di richiesta

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

L'API Places Insights ti consente di eseguire diverse funzioni chiave:

• Conta luoghi: determina il numero di luoghi che corrispondono a criteri specifici, come tipo di località, stato di funzionamento, livello di prezzo e valutazioni.
• Recupero dei dettagli dei luoghi: ottieni i nomi dei luoghi che soddisfano i filtri specificati, quindi recupera informazioni più dettagliate utilizzando l'API Places.
• Filtro flessibile: applica filtri completi per ottenere informazioni precise. 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 quando viene inviata una richiesta all'API Places Insights. Ogni richiesta deve fornire quanto segue:

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

Tipo di approfondimento

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

• 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 Insights 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 posizione può essere di uno dei seguenti tipi:

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

Importante: l'area per qualsiasi filtro posizione deve essere compresa tra 1556,86 m² (circa le dimensioni di un piccolo isolato) e 2 trilioni di m² (circa le dimensioni dell'Alaska). Le richieste con aree esterne a questo intervallo restituiranno un errore INVALID_ARGUMENT.

Nota: per le entità con confini poligonali definiti, come parchi o aeroporti, l'entità è 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 centro dell'entità non deve necessariamente trovarsi all'interno dell'area di ricerca.

Cerchio

Se selezioni la tua area geografica come un 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 di applicare filtri precisi e accurati 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 punti di interesse. 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, in Florida, è places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Tieni presente che non tutti gli ID luogo hanno una geometria ben definita e, in questi casi, l'API di Dati dei luoghi restituisce un codice di errore 400 con un messaggio che indica che la regione non è supportata. Inoltre, per le regioni geografiche complesse, le ottimizzazioni dell'elaborazione interna potrebbero portare a una leggera sovrastima dell'area (fino al 2-3%) che rappresenta la regione.

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

Per saperne di più su come vengono identificate le regioni in discussione, consulta Precisazioni su confini e nomi di paesi.

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

• Tipi di regioni così grandi da comportare una latenza elevata.
• Tipi di regioni così piccole 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 luoghi associati all'ID luogo, ad esempio city, neighborhood o country.

I tipi di luoghi non supportati includono:

• establishment: in genere indica un luogo che non è stato ancora classificato.
• street_number: indica il numero civico esatto.
• floor: indica il piano di un indirizzo dell'edificio.
• post_box: indica una cassetta postale specifica.
• street_address: indica un indirizzo preciso.
• room: indica la stanza di un indirizzo dell'edificio.
• intersection: indica un incrocio importante, in genere di due strade principali.
• landmark: indica un luogo nelle vicinanze utilizzato come riferimento per agevolare la navigazione.
• subpremise: indica un'entità indirizzabile al di sotto del livello della proprietà, ad esempio un appartamento, un'unità o una suite.
• sublocality_level_5: il livello granulare più specifico dei componenti dell'indirizzo della località secondaria. In genere rappresenta una suddivisione molto piccola del quartiere o un'area iperlocale all'interno di una città.

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 antiorario indica che l'interno del poligono si trova a sinistra dei bordi di confine.

Importante: le aree personalizzate devono avere al massimo 7000 vertici.

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

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

Inoltre, non è consentito l'intersezione di spigoli non adiacenti e non sono consentiti spigoli di lunghezza pari a 180 gradi (ovvero i vertici adiacenti non possono essere antipodi).

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 tipo

Specifica i tipi di luoghi da includere o escludere. Per un elenco dei tipi di luoghi principali e secondari supportati dall'API Places Insights, 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 luogo, consulta scopri di più sui filtri dei tipi.

Parametri facoltativi

Questi filtri sono facoltativi:

• operatingStatus: specifica gli stati dei luoghi da includere o escludere. Il valore predefinito è il filtro per operatingStatus: OPERATING_STATUS_OPERATIONAL (un valore specifico).
• priceLevels: specifica i livelli di prezzo dei luoghi. Il valore predefinito è nessun filtro (tutti i livelli di prezzo sono inclusi nei risultati).
• ratingFilter: specifica l'intervallo di valutazione dei luoghi. Il valore predefinito è nessun 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 operativo o chiuso temporaneamente). Se il filtro operatingStatus non è impostato, nei risultati vengono inclusi solo i luoghi con stato di funzionamento OPERATING_STATUS_OPERATIONAL.

Livello dei prezzi

Con il filtro price_levels, puoi filtrare in base al livello di prezzo (ad es. senza costi, moderato o costoso). Se il filtro price_levels non è impostato, tutti i livelli di prezzo sono inclusi nei risultati.

Filtro valutazione

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

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

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