Ricerca nelle vicinanze (Novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

Una richiesta di ricerca nelle vicinanze (nuova) utilizza come input la regione per la ricerca specificata sotto forma di cerchio, definita dalle coordinate di latitudine e longitudine del punto centrale del cerchio e dal raggio in metri. La richiesta restituisce un elenco di posizioni corrispondenti, ciascuna rappresentata 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. 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 punti di tipo "ristorante", "panetteria" e "bar" oppure di escludere tutti i punti di tipo "scuola".

Richieste di Ricerca nelle vicinanze (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 campo. Se non specifichi almeno un campo nell'elenco dei campi oppure se ometti l'elenco dei campi, la chiamata restituisce un errore.
  • La limitazione di località per l'area di ricerca, definita come coppia latitudine/longitudine e valore del raggio, in metri.

Questo esempio di richiesta di ricerca nelle vicinanze specifica che gli oggetti Place di risposta contengono i campi luogo Place.Field.ID e Place.Field.NAME per ogni oggetto Place nei risultati di ricerca. Inoltre, filtra la risposta per restituire solo i luoghi di tipo "ristorante" e "bar", escludendo quelli di tipo "ristorante_pizza" e "ristorante_americano".

// 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);

// 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 di Nearby Search (nuove)

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

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

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

// 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 Luogo di accesso.

Parametri obbligatori

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

  • Elenco 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 del campo, passa un array di valori da Place.Field all'oggetto SearchNearbyRequest. Il mascheramento dei campi è una buona prassi di progettazione per evitare di richiedere dati superflui, evitando tempi di elaborazione e addebiti di fatturazione non necessari.

    Specifica uno o più dei seguenti campi:

    • I seguenti campi attivano lo SKU Nearby Search (Basic):

      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.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 Nearby Search (Advanced):

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

    • I seguenti campi attivano lo SKU Nearby Search (Preferred):

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

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

    L'esempio seguente definisce un elenco di due valori di campi per specificare che l'oggetto Place restituito da una richiesta contiene i campi Place.Field.ID e Place.Field.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.NAME);

  • Restrizione di località

    Un oggetto LocationRestriction che definisce la regione da cercare specificata sotto forma di cerchio, definita dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra maggiore di 0,0 e minore o uguale a 50.000,0.Tieni presente che specificando un raggio troppo piccolo verrà restituito ZERO_RESULTS.

    Per impostare il parametro della limitazione di località, chiama il metodo setLocationRestriction() durante la creazione dell'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 dai tipi Tabella A utilizzati per filtrare i risultati di ricerca. È possibile specificare fino a 50 tipi per ogni categoria di limitazione dei tipi.

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

    Un luogo può anche avere più valori di tipo associati ai tipi 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 in base all'elenco dei tipi associati a un luogo.

    Se una ricerca è specificata con più limitazioni di tipi, 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 di Ricerca nelle vicinanze (nuova).

    Tipi inclusi

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

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

    Tipi esclusi

    Un elenco di tipi di luogo dalla 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 le posizioni classificate come "school" ma non come "primary_school". La risposta include i luoghi che corrispondono ad almeno uno degli 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 tipi esclusi, chiama il metodo setExcludedTypes() durante la creazione dell'oggetto SearchNearbyRequest.

    Tipi principali inclusi

    Un elenco dei tipi di luogo 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 dei tipi di luoghi principali della Tabella A da escludere da una ricerca.

    Se sono presenti tipi principali in conflitto, ad esempio un tipo presente sia in includedPrimaryTypes che 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 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 (predefinito) Ordina i risultati in base alla popolarità.
    • DISTANCE Ordina i risultati in ordine crescente in base alla distanza dalla posizione specificata.

    Per impostare il parametro di preferenza di 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 codice CLDR a due caratteri. Non esiste un valore predefinito.

    Se il nome del paese del campo formattedAddress nella risposta corrisponde a regionCode, il codice paese viene omesso da formattedAddress.

    La maggior parte dei codici CLDR è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "The United Kingdom of 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.

Attribuzioni display nell'app

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

Per maggiori informazioni, consulta la pagina Norme per l'SDK Places per Android.