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 secountè 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: definisce un'area come poligono personalizzato.
Cerchio
Se selezioni la tua area geografica come un cerchio, devi fornire un center
e un radius. Il centro può essere una latitudine e una longitudine oppure l'ID luogo del centro del cerchio.
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 prefissoplaces/.
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 404.
La tabella seguente elenca i tipi di regioni non supportati. Per determinare se un ID luogo rappresenta un tipo di regione non supportato, passalo in una richiesta dell'API Geocoding. La risposta include l'array type che elenca le regioni associate all'ID luogo, ad esempio city, neighborhood o country.
| 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 |
Area personalizzata
Definisce l'area di un poligono personalizzato utilizzando le coordinate di latitudine e longitudine.
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 univoche. Oltre alle coordinate prima e ultima, non devono essere presenti altre coordinate duplicate. Inoltre, non è consentito che i bordi non adiacenti si intersechino e non sono consentiti bordi 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 di tipo e dei tipi di luogo, consulta scopri di più sui filtri di tipo.
Parametri facoltativi
Questi filtri sono facoltativi:
operatingStatus: specifica gli stati dei luoghi da includere o escludere. Il valore predefinito è il filtro peroperatingStatus: 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à
Filtra in base allo stato di attività (ad esempio operativo o chiuso temporaneamente).
Livello dei prezzi
Filtra in base al livello di prezzo (ad es. senza costi, moderato o costoso).
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).