Ricerca nelle vicinanze (novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

Una richiesta di ricerca nelle vicinanze (nuova) riceve come input la regione da cercare specificata come cerchio, definita dalle coordinate di latitudine e longitudine del punto centrale del cerchio e dal raggio in metri. La richiesta restituisce un elenco di luoghi corrispondenti, ciascuno rappresentato da un oggetto Place, all'interno dell'area di ricerca specificata.

Per impostazione predefinita, la risposta contiene luoghi di tutti i tipi all'interno dell'area di ricerca. Se vuoi, puoi filtrare la risposta specificando un elenco di tipi di luoghi da includere esplicitamente nella risposta o da escludere. Ad esempio, puoi specificare di includere nella risposta solo i luoghi di tipo "ristorante", "pasticceria" e "bar" oppure escludere tutti i luoghi di tipo "scuola".

Nota: la ricerca nelle vicinanze (nuova) è disponibile in Places SDK for Android versione 3.5.0 e successive. Per ulteriori informazioni, vedi Scegliere la versione dell'SDK. Per ulteriori informazioni sull'utilizzo delle API Kotlin aggiunte nella versione 4.0.0, consulta la Panoramica di riferimento.

Richieste di Nearby Search (nuova)

Effettua una richiesta di ricerca nelle vicinanze (nuova) chiamando PlacesClient.searchNearby, passando un oggetto SearchNearbyRequest che definisce i parametri della richiesta.

L'oggetto SearchNearbyRequest specifica tutti i parametri obbligatori e facoltativi per la richiesta. I parametri obbligatori includono:

• L'elenco dei campi da restituire nell'oggetto Place, noto anche come maschera di campi. Se non specifichi almeno un campo nell'elenco dei campi o se ometti l'elenco dei campi, la chiamata restituisce un errore.
• La limitazione della località per l'area di ricerca, definita come una coppia di latitudine/longitudine e un valore del raggio, in metri.

Questo esempio di richiesta di ricerca nelle vicinanze specifica che gli oggetti Place della risposta devono contenere i campi dei luoghi Place.Field.ID e Place.Field.DISPLAY_NAME per ogni oggetto Place nei risultati di ricerca. Inoltre, filtra la risposta in modo da restituire solo luoghi di tipo "restaurant" e "cafe", ma esclude i luoghi di tipo "pizza_restaurant" e "american_restaurant".

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Nota: per ulteriori informazioni sull'inizializzazione di PlacesClient, consulta Inizializzare il client dell'API Places.

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta a una delle classi di richiesta (ad esempio FetchPlaceRequest). L'annullamento viene eseguito secondo il criterio del "best effort". Una volta inviata una richiesta di annullamento, non verrà restituita alcuna risposta. L'emissione di un token di annullamento NON garantisce che una determinata richiesta verrà annullata e ti potrebbe essere addebitato l'importo della richiesta anche se non viene restituita alcuna risposta.

Risposte di Nearby Search (novità)

La classe SearchNearbyResponse rappresenta la risposta a una richiesta di ricerca. Un oggetto SearchNearbyResponse contiene:

• Un elenco di oggetti Place che rappresentano tutti i luoghi corrispondenti, con un oggetto Place per ogni luogo corrispondente.
• Ogni oggetto Place contiene solo i campi definiti dall'elenco di campi passato nella richiesta.

Ad esempio, nella richiesta hai definito un elenco di campi come:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

Questo elenco di campi indica che ogni oggetto Place nella risposta contiene solo l'ID e il nome di ogni luogo corrispondente. Puoi quindi utilizzare i metodi Place.getId() e Place.getName() per accedere a questi campi in ogni oggetto Place.

Per altri esempi di accesso ai dati in un oggetto Place, consulta Accedere ai campi di dati dell'oggetto Luogo.

Parametri obbligatori

Utilizza l'oggetto SearchNearbyRequest per specificare i parametri richiesti per la ricerca.

• Elenco di campi

  Quando richiedi i dettagli del luogo, devi specificare i dati da restituire nell'oggetto Place per il luogo come maschera di campo. Per definire la maschera di campo, passa un array di valori da Place.Field all'oggetto SearchNearbyRequest. Il mascheramento dei campi è una buona prassi di progettazione per assicurarti di non richiedere dati non necessari, il che consente di evitare tempi di elaborazione e addebiti in fatturazione non necessari.

  Specifica uno o più dei seguenti campi:

  • I seguenti campi attivano lo SKU Ricerca nelle vicinanze (di base):

    Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • I seguenti campi attivano lo SKU Ricerca nelle vicinanze (avanzata):

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI
    
    Nota: i campi Place.Field.PHONE_NUMBER e Place.Field.USER_RATINGS_TOTAL sono stati ritirati nella versione 4.0 di Places SDK for Android. Utilizza Place.Field.INTERNATIONAL_PHONE_NUMBER e Place.USER_RATING_COUNT, rispettivamente.

  • I seguenti campi attivano lo SKU Ricerca nelle vicinanze (preferito):

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT
  Nota: la versione 4.0 di Places SDK for Android ha introdotto il ritiro di diversi campi di dati dei luoghi e l'aggiunta di nuovi campi. Per ulteriori informazioni, consulta Eseguire la migrazione ai nuovi campi di dati dei luoghi in Places SDK for Android 4.0 .

  Per impostare il parametro dell'elenco di campi, chiama il metodo setPlaceFields() durante la creazione dell'oggetto SearchNearbyRequest.

  L'esempio seguente definisce un elenco di due valori di campo per specificare che l'oggetto Place restituito da una richiesta contiene i campi Place.Field.ID e Place.Field.DISPLAY_NAME:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

• Limitazione di località

  Un oggetto LocationRestriction che definisce la regione da cercare specificata come un cerchio, definito dal centro e dal raggio in metri. Il raggio deve essere maggiore di 0,0 e minore o uguale a 50000,0, tenendo presente che se specifichi un raggio troppo piccolo, la risposta sarà ZERO_RESULTS.

  Per impostare il parametro di limitazione della località, chiama il metodo setLocationRestriction() quando crei l'oggetto SearchNearbyRequest.

Parametri facoltativi

Utilizza l'oggetto SearchNearbyRequest per specificare i parametri facoltativi per la ricerca.

• Tipi e tipi principali

  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 elencati nella Tabella A. 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 "restaurant", ma anche luoghi con un tipo principale più specifico, ad esempio "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 = Arrays.asList("restaurant") e excludedPrimaryTypes = Arrays.asList("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à.

  Per un esempio di come utilizzare includedTypes e excludedTypes, consulta Richieste di Ricerca nelle vicinanze (nuova).

  Tipi inclusi

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

  Per impostare il parametro dei tipi inclusi, chiama il metodo setIncludedTypes() durante la creazione dell'oggetto SearchNearbyRequest.

  Tipi esclusi

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

  Se nella richiesta specifichi sia includedTypes (ad esempio "school") sia excludedTypes (ad esempio "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.

  Per impostare il parametro dei tipi esclusi, chiama il metodo setExcludedTypes() durante la creazione dell'oggetto SearchNearbyRequest.

  Tipi principali inclusi

  Un elenco di tipi di luoghi principali della Tabella A da includere in una ricerca.

  Per impostare il parametro dei tipi principali inclusi, chiama il metodo setIncludedPrimaryTypes() durante la creazione dell'oggetto SearchNearbyRequest.

  Tipi principali esclusi

  Un elenco 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.

  Per impostare il parametro dei tipi principali esclusi, chiama il metodo setExcludedPrimaryTypes() durante la creazione dell'oggetto SearchNearbyRequest.

• Numero massimo di risultati

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

  Per impostare il parametro del conteggio massimo dei risultati, chiama il metodo setMaxResultCount() durante la creazione dell'oggetto SearchNearbyRequest.

• Preferenza di ranking

  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.

  Per impostare il parametro di preferenza del ranking, chiama il metodo setRankPreference() durante la creazione dell'oggetto SearchNearbyRequest.

• Codice regione

  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 FORMATTED_ADDRESS nella risposta corrisponde a regionCode, il codice paese viene omesso da FORMATTED_ADDRESS.

  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.

  Per impostare il parametro del codice regione, chiama il metodo setRegionCode() durante la creazione dell'oggetto SearchNearbyRequest.

Mostrare le attribuzioni nell'app

Quando la tua app mostra informazioni ottenute da PlacesClient, come foto e recensioni, deve anche mostrare le attribuzioni richieste.

Per ulteriori informazioni, consulta le norme per Places SDK per Android.