Ricerca nelle vicinanze (novità)

Una richiesta Nearby Search (New) accetta come input la regione in cui eseguire la ricerca specificata come un cerchio, definito dalle coordinate di latitudine e longitudine del punto centrale del cerchio e dal raggio in metri. La richiesta restituisce un elenco di luoghi corrispondenti, ognuno rappresentato da un Place oggetto, all'interno dell'area di ricerca specificata.

Per impostazione predefinita, la risposta contiene luoghi di tutti i tipi all'interno dell'area di ricerca. Facoltativamente, puoi filtrare la risposta specificando un elenco di tipi di luoghi da includere o escludere esplicitamente dalla risposta. Ad esempio, puoi specificare di includere nella risposta solo i luoghi di tipo "restaurant", "bakery" e "cafe" o escludere tutti i luoghi di tipo "school".

Richieste Nearby Search (New)

Invia una richiesta Nearby Search (New) 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 campo. 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.

Questa richiesta di Nearby Search di esempio specifica che gli oggetti Place della risposta contengono i campi del luogo Place.Field.ID e Place.Field.DISPLAY_NAME per ogni oggetto Place nei risultati di ricerca. Filtra anche la risposta in modo da restituire solo i 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();
    });

Risposte Nearby Search (New)

La SearchNearbyResponse classe 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 dei 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 luogo 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 Place.

Parametri obbligatori

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

• Elenco dei campi

  Quando richiedi i dettagli di un 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. L'applicazione di maschere ai campi è una buona pratica di progettazione per assicurarti di non richiedere dati non necessari, il che contribuisce a evitare tempi di elaborazione e addebiti di fatturazione non necessari.

  Specifica uno o più dei seguenti campi:

  • I seguenti campi attivano lo Nearby Search Pro SKU:

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
        * Utilizza questo campo al posto di Place.Field.NAME, che è deprecato.
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * Utilizza questo campo al posto di Place.Field.ICON_URL, che è deprecato.
    Place.Field.ID
Place.Field.LAT_LNG
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.RESOURCE_NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (New).

  • I seguenti campi attivano lo SKU Nearby Search Enterprise:

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * Utilizza questo campo al posto di Place.Field.PHONE_NUMBER, che è deprecato.
    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*
        * Utilizza questo campo al posto di Place.Field.USER_RATINGS_TOTAL, che è deprecato.
    Place.Field.WEBSITE_URI

    Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (New).

  • I seguenti campi attivano lo SKU Nearby Search Enterprise Plus:

    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

    Per un elenco completo dei campi e degli SKU associati, consulta Campi di dati dei luoghi (New).

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

  L'esempio seguente definisce un elenco di due valori di campo per specificare che l' Place oggetto 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 della località

  Un LocationRestriction oggetto che definisce la regione in cui eseguire la ricerca specificata come un cerchio, definito dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi, tenendo presente che se specifichi un raggio troppo piccolo verrà restituito ZERO_RESULTS come risposta.

  Per impostare il parametro di limitazione della località, chiama il setLocationRestriction() metodo durante la creazione dell'oggetto SearchNearbyRequest.

Parametri facoltativi

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

• Tipi e tipi principali

  Ti consente di specificare un elenco di tipi della tabella A dei tipi utilizzati per filtrare i risultati di ricerca. In ogni categoria di limitazione dei tipi è possibile specificare fino a 50 tipi.

  Un luogo può avere associato un solo tipo principale della tabella A dei tipi. 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.

  Un luogo può anche avere associati più valori di tipo della tabella A dei tipi. 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 in base all'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 di 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 la risposta può anche contenere luoghi con un tipo principale più specifico, ad esempio "chinese_restaurant" o "seafood_restaurant".

  Se una ricerca viene specificata con più limitazioni di tipo, vengono restituiti solo i luoghi che soddisfano tutte le limitazioni. 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".

  Per un esempio di come utilizzare includedTypes e excludedTypes, consulta Richieste Nearby Search (New).

  Tipi inclusi

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

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

  Tipi esclusi

  Un elenco di tipi di luoghi da tabella A 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 ad almeno uno dei includedTypes e nessuno dei excludedTypes.

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

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

  Tipi principali inclusi

  Un elenco dei tipi di luoghi principali da tabella A includere in una ricerca.

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

  Tipi principali esclusi

  Un elenco dei tipi di luoghi principali da tabella A escludere da una ricerca.

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

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

• Numero massimo di risultati

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

  Per impostare il parametro del numero massimo di 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 (valore predefinito) 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 della preferenza di ranking, chiama il setRankPreference() metodo durante la creazione dell'SearchNearbyRequest oggetto.

• Codice regione

  Il codice regione utilizzato per formattare la risposta, specificato come a valore del codice CLDR a due caratteri. Non esiste un 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 ccTLD del Regno Unito è "uk" (.co.uk), mentre il suo 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 applicabile.

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

Mostrare le attribuzioni nell'app

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

Per saperne di più, consulta Norme per Places SDK for Android.