Parametri di richiesta

Questo documento fornisce una chiara panoramica di tutti i parametri all'interno del API Places Insights. Approfondiremo ciascun aspetto, offrendoti gli approfondimenti e le migliori per aiutarti a utilizzare questo strumento per le tue esigenze di dati geografici.

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

  • Conteggia luoghi: determina il numero di luoghi che corrispondono a specifiche come tipo di località, stato dell'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 API Places.
  • Filtri flessibili: applica filtri completi per ottenere informazioni precise. I filtri disponibili sono i seguenti:
    • Area geografica (cerchio, regione o poligono personalizzato)
    • Tipi di luogo
    • Stato di attività
    • Livelli di prezzo
    • Intervalli di valutazione

Parametri obbligatori

Questa sezione illustra i parametri richiesti quando si invia una richiesta al API Places Insights. Ogni richiesta deve fornire quanto segue:

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

Insight

Specifica il tipo di insight che vuoi calcolare. I seguenti tipi di insight sono supportati:

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

Nota: se questa opzione è selezionata, l'API Places Insights restituisce gli ID luogo. solo se count è 100 o inferiore.

Filtro

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.
  • custom_area: definisce un'area come poligono personalizzato.
Cerchio

Se selezioni l'area geografica sotto forma di cerchio, devi fornire un valore center e radius. Il centro può essere una latitudine e una longitudine oppure il luogo ID del centro del cerchio.

  • al centro:
    • lat_lng: latitudine e longitudine del centro del cerchio. Latitudine deve essere un numero compreso tra -90 e 90 inclusi. La longitudine deve essere un numero tra -180 e 180 inclusi.
    • place: ID posizione del centro del cerchio. Tieni presente che solo il punto luoghi sono supportati. Questa stringa deve iniziare con il prefisso places/.
  • radius: raggio del cerchio in metri. Questo numero deve essere positivo.
Regione

Puoi definire la tua area come regione utilizzando il parametro place. Utilizza un ID luogo che rappresenta un'area geografica (come un'area rappresentabile da poligono). Ad esempio, l'ID luogo di Tampa, FL è places/ChIJ4dG5s4K3wogRY7SWr4kTX6c.

Tipi di regioni non supportati
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark subpremise

Puoi utilizzare il campo types di una chiamata dell'API Geocoding per determinare il tipo di località o indirizzo associato a un ID luogo, ad esempio se si tratta di un città, quartiere o paese.

Area personalizzata

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

Puoi visitare https://geojson.io/ per disegnare un poligono personalizzato e inserire queste coordinate nella richiesta. Un poligono deve avere almeno 4 coordinate in cui la prima e l'ultima coordinate sono identiche. Oltre al la prima e l'ultima coordinata, non devono esserci altre coordinate duplicate. 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
   }
]

Tipo di filtro

Specifica i tipi di luoghi da includere o escludere. Per un elenco dei principali e i tipi di località secondari supportati dall'API Places Insights, fai riferimento alla Tabella A nella guida Tipi di luogo per l'API Places (Novità). Almeno un tipo included_types o included_primary_types deve essere inclusi.

  • included_types: elenco dei tipi di luogo inclusi.
  • excluded_types: elenco dei tipi di luoghi esclusi.
  • included_primary_types: elenco dei tipi di luogo principali inclusi.
  • excluded_primary_types: elenco dei tipi di luoghi principali esclusi.

Per saperne di più su come funzionano i filtri per tipo e i tipi di luogo, consulta ulteriori informazioni sul tipo filtri.

Parametri facoltativi

I tre filtri rimanenti sono facoltativi:

  • operating_status: specifica gli stati dei luoghi da includere o escludere. Il filtro predefinito è operating_status: OPERATING_STATUS_OPERATIONAL (un valore specifico).
  • price_levels: specifica i livelli di prezzo dei luoghi. Il valore predefinito è no (nei risultati sono inclusi tutti i livelli di prezzo).
  • rating_filter: specifica l'intervallo di valutazione dei luoghi. Il valore predefinito è no (nei risultati sono incluse tutte le valutazioni).

Stato di attività

Filtra in base allo stato di attività (ad esempio operativo o temporaneo chiuso).

Livello dei prezzi

Filtra in base al livello di prezzo (ad esempio senza costi, moderato o costoso).

Filtro valutazione

Filtra i luoghi in base alla media delle valutazioni degli utenti. Entrambi questi campi sono facoltativi e, quindi, se vengono omessi, per impostazione predefinita includeranno anche i luoghi che non hanno una classificazione.

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