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 prefissoplaces/
.
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).