Questa pagina è stata tradotta dall'API Cloud Translation.

Ricerca nelle vicinanze (Novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

Una richiesta Ricerca nelle vicinanze (nuova) accetta uno o più tipi di luoghi e restituisce un elenco di luoghi corrispondenti all'interno dell'area specificata. È obbligatoria una maschera di campo che specifichi uno o più tipi di dati. Ricerca nelle vicinanze (nuova) supporta solo le richieste POST.

L'API Explorer ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e le opzioni dell'API:

Prova!

Prova la demo interattiva per vedere i risultati della Ricerca nelle vicinanze (nuova) visualizzati su una mappa.

Richieste di Nearby Search (nuova)

Una richiesta di Ricerca nelle vicinanze (nuova) è una richiesta POST HTTP a un URL nel formato:

https://places.googleapis.com/v1/places:searchNearby

Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte della richiesta POST. Ad esempio:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Risposte di Nearby Search (novità)

Ricerca nelle vicinanze (nuova) restituisce un oggetto JSON come risposta. Nella risposta:

L'array places contiene tutti i luoghi corrispondenti.
Ogni luogo nell'array è rappresentato da un oggetto Place. L'oggetto Place contiene informazioni dettagliate su un singolo luogo.
Il valore FieldMask passato nella richiesta specifica l'elenco di campi restituiti nell'oggetto Place.

L'oggetto JSON completo è nel formato:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Parametri obbligatori

FieldMask

Specifica l'elenco dei campi da restituire nella risposta creando una maschera di campo della risposta. Passa la maschera del campo di risposta al metodo utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP X-Goog-FieldMask. Nella risposta non è presente un elenco predefinito dei campi restituiti. Se ometti la maschera di campo, il metodo restituisce un errore.

La mascheratura dei campi è una buona prassi di progettazione per assicurarti di non richiedere dati non necessari, il che consente di evitare tempi di elaborazione e costi di fatturazione non necessari.

Specifica un elenco separato da virgole di tipi di dati dei luoghi da restituire. Ad esempio, per recuperare il nome visualizzato e l'indirizzo del luogo.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
Nota: gli spazi non sono consentiti nell'elenco dei campi.

Utilizza * per recuperare tutti i campi.
```
X-Goog-FieldMask: *
```
Il carattere jolly "*" seleziona tutti i campi. Tuttavia, anche se questo carattere jolly è accettabile per lo sviluppo, Google sconsiglia di utilizzare la maschera del campo di risposta con carattere jolly (*) in produzione a causa dell'elevata quantità di dati che possono essere restituiti.

Ulteriori indicazioni per l'utilizzo di places.iconMaskBaseUri e places.iconBackgroundColor sono disponibili nella sezione Icone di luogo.

Specifica uno o più dei seguenti campi:
- I seguenti campi attivano lo SKU Ricerca nelle vicinanze (di base):
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks^*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name^**, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport
  
  ^* Il campo places.googleMapsLinks è nella fase di anteprima pre-GA e non è previsto alcun addebito, il che significa che la fatturazione è pari a 0 $per l'utilizzo durante l'anteprima.
  
  ^** Il campo places.name contiene il nome della risorsa del luogo nel formato: places/PLACE_ID. Usa places.displayName per accedere al nome del luogo in formato testo.
- I seguenti campi attivano lo SKU Ricerca nelle vicinanze (avanzata):
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- I seguenti campi attivano lo SKU per la ricerca nelle vicinanze (opzione preferita):
  
  places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.routingSummaries,^* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout
  
  ^* Solo Ricerca di testi e Ricerca nelle vicinanze
locationRestriction

La regione da cercare specificata come cerchio, definita dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50000,0 inclusi. Il raggio predefinito è 0,0. Devi impostarlo nella richiesta su un valore maggiore di 0,0.

Ad esempio:
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

Parametri facoltativi

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

Consente di specificare un elenco di tipi della Tabella A utilizzati per filtrare i risultati di ricerca. In ogni categoria di limitazione del tipo è possibile specificare fino a 50 tipi.

Nota: i valori nella Tabella B vengono restituiti solo nella risposta. Non puoi utilizzare i valori della Tabella B come filtro.

Un luogo può avere un solo tipo principale tra i tipi della Tabella A associati. Ad esempio, il tipo principale potrebbe essere "mexican_restaurant" o "steak_house". Utilizza includedPrimaryTypes e excludedPrimaryTypes per filtrare i risultati in base al tipo principale di un luogo.

A un luogo possono essere associati anche più valori di tipo dei tipi elencati nella Tabella A. Ad esempio, un ristorante potrebbe avere i seguenti tipi: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Utilizza includedTypes e excludedTypes per filtrare i risultati nell'elenco dei tipi associati a un luogo.

Quando specifichi un tipo principale generale, ad esempio "restaurant" o "hotel", la risposta può contenere luoghi con un tipo principale più specifico rispetto a quello specificato. Ad esempio, specifichi di includere un tipo principale di "restaurant". La risposta può quindi contenere luoghi con un tipo principale di "restaurant", ma può anche contenere luoghi con un tipo principale più specifico, come "chinese_restaurant" o "seafood_restaurant".

Se una ricerca è specificata con più restrizioni di tipo, vengono restituiti solo i luoghi che soddisfano tutte le restrizioni. Ad esempio, se specifichi {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, i luoghi restituiti forniscono servizi correlati a "restaurant", ma non operano principalmente come "steak_house".

Se nella richiesta ometti includedTypes, excludedTypes, includedPrimaryTypes e excludedPrimaryTypes, la ricerca restituisce luoghi di tutti i tipi all'interno dei limiti di restrizione della località.

includedTypes

Un elenco separato da virgole dei tipi di luoghi della Tabella A da cercare. Se questo parametro viene omesso, vengono restituiti luoghi di tutti i tipi.

excludedTypes

Un elenco separato da virgole di tipi di luoghi della Tabella A da escludere da una ricerca.

Se nella richiesta specifichi sia includedTypes ( ad es. "school") sia excludedTypes (ad es. "primary_school"), la risposta include i luoghi classificati come "school", ma non come "primary_school". La risposta include i luoghi che corrispondono a almeno uno dei includedTypes e a nessuno dei excludedTypes.

Se sono presenti tipi in conflitto, ad esempio un tipo visualizzato sia in includedTypes che in excludedTypes, viene restituito un errore INVALID_REQUEST.

includedPrimaryTypes

Un elenco con valori separati da virgole dei tipi di luoghi principali della Tabella A da includere in una ricerca.

excludedPrimaryTypes

Un elenco separato da virgole di tipi di luoghi principali della Tabella A da escludere da una ricerca.

Se sono presenti tipi principali in conflitto, ad esempio un tipo visualizzato sia in includedPrimaryTypes sia in excludedPrimaryTypes, viene restituito un errore INVALID_ARGUMENT.
languageCode

La lingua in cui restituire i risultati.
- Consulta l'elenco delle lingue supportate. Google spesso aggiorna le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
- Se non viene fornito languageCode, l'API imposta en come valore predefinito. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
- L'API fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in uno script leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono tutti restituiti nella stessa lingua, scelta dal primo componente.
- Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più simile.
- La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che possono essere validi in una lingua, ma non in un'altra.
maxResultCount

Specifica il numero massimo di risultati relativi ai luoghi da restituire. Deve essere compreso tra 1 e 20 (valore predefinito) inclusi.
rankPreference

Il tipo di ranking da utilizzare. Se questo parametro viene omesso, i risultati vengono classificati in base alla popolarità. Può essere uno dei seguenti:
- POPULARITY (impostazione predefinita) Ordina i risultati in base alla loro popolarità.
- DISTANCE Ordina i risultati in ordine crescente in base alla distanza dalla località specificata.
regionCode

Il codice regione utilizzato per formattare la risposta, specificato come valore di un codice CLDR a due caratteri. Non è presente alcun valore predefinito.

Se il nome del paese del campo formattedAddress nella risposta corrisponde a regionCode, il codice paese viene omesso da formattedAddress. Questo parametro non ha alcun effetto su adrFormatAddress, che include sempre il nome del paese, o su shortFormattedAddress, che non lo include mai.

La maggior parte dei codici CLDR è identica ai codici ISO 3166-1, con alcune eccezioni notevoli. Ad esempio, il TLD di primo livello del Regno Unito è "uk" (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord"). Il parametro può influire sui risultati in base alla legge vigente.

Esempi di Nearby Search (nuova versione)

Trovare luoghi di un determinato tipo

L'esempio seguente mostra una richiesta di Ricerca nelle vicinanze (nuova) per i nomi visualizzati di tutti i ristoranti entro un raggio di 500 metri, definito da circle:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Tieni presente che l'intestazione X-Goog-FieldMask specifica che la risposta contiene i seguenti campi di dati: places.displayName. La risposta è quindi nel seguente formato:

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

Aggiungi altri tipi di dati alla maschera di campo per restituire ulteriori informazioni. Ad esempio, aggiungi places.formattedAddress,places.types,places.websiteUri per includere nella risposta l'indirizzo, il tipo e l'indirizzo web del ristorante:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

La risposta ora è nel seguente formato:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Trovare luoghi di più tipi

L'esempio seguente mostra una richiesta di Ricerca nelle vicinanze (nuova) per i nomi visualizzati di tutti i minimarket e i negozi di liquori entro un raggio di 1000 metri dal circle specificato:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby

Questo esempio aggiunge places.primaryType e places.types alla maschera di campo in modo che la risposta includa informazioni sul tipo di ogni luogo, facilitando la selezione del luogo appropriato dai risultati.

Escludere un tipo di luogo da una ricerca

L'esempio seguente mostra una richiesta di ricerca nelle vicinanze (nuova) per tutti i luoghi di tipo "school", escludendo tutti i luoghi di tipo "primary_school", con il ranking dei risultati in base alla distanza:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Cercare tutti i luoghi vicino a un'area, con un ranking in base alla distanza

L'esempio seguente mostra una richiesta di ricerca nelle vicinanze (nuova) per i luoghi vicino a un punto nel centro di San Francisco. In questo esempio, includi il parametro rankPreference per classificare i risultati in base alla distanza:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Prova

L'Explorer API ti consente di effettuare richieste di esempio per familiarizzare con l'API e le relative opzioni.

Seleziona l'icona dell'API sul lato destro della pagina.
Se vuoi, espandi Mostra parametri standard e imposta il parametro fields sulla maschera di campo.
Se vuoi, modifica il corpo della richiesta.
Seleziona il pulsante Esegui. Nel popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona di espansione, , per espandere la finestra di Explorer API.

Ricerca nelle vicinanze (Novità)

Richieste di Nearby Search (nuova)

Risposte di Nearby Search (novità)

Parametri obbligatori

FieldMask

locationRestriction

Parametri facoltativi

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode