Ricerca nelle vicinanze (novità)

Seleziona la piattaforma:Android iOS JavaScript Servizio web

Sviluppatori dello Spazio economico europeo (SEE)

Una richiesta di ricerca nelle vicinanze (nuova) prende 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, ognuno 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 o escludere esplicitamente dalla risposta. Ad esempio, puoi specificare di includere nella risposta solo i luoghi di tipo "ristorante", "panificio" e "caffetteria" oppure escludere tutti i luoghi di tipo "scuola".

Richieste di Nearby Search (nuovo)

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 o se ometti l'elenco dei campi, la chiamata restituisce un errore.
  • La limitazione della posizione per l'area di ricerca, definita come una coppia di latitudine/longitudine e un valore del raggio, in metri.

Questa richiesta di ricerca nelle vicinanze 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. Inoltre, filtra la risposta in modo da restituire solo i luoghi di tipo "ristorante" e "caffè", ma esclude i luoghi di tipo "pizzeria" 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.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 alla ricerca nelle vicinanze (nuova)

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 dei campi trasmesso 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'oggetto SearchNearbyRequest per specificare i parametri richiesti per la ricerca.

  • Elenco dei 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 pratica di progettazione per assicurarsi di non richiedere dati non necessari, il che aiuta a evitare tempi di elaborazione e addebiti non necessari.

    Specifica uno o più dei seguenti campi:

    • I seguenti campi attivano lo SKU Pro Ricerca nelle vicinanze:

      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 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

    • I seguenti campi attivano lo SKU Enterprise di ricerca nelle vicinanze:

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

    • I seguenti campi attivano lo SKU di ricerca nelle vicinanze di 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 impostare il parametro dell'elenco dei campi, chiama il metodo setPlaceFields() quando crei l'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 della località

    Un LocationRestriction oggetto che definisce la regione da cercare specificata come un cerchio, definito da punto centrale e raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,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() 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 dalla tabella A Tabella A utilizzata per filtrare i risultati di ricerca. È possibile specificare fino a 50 tipi in ogni categoria di limitazione dei tipi.

    Un luogo può avere un solo tipo principale tra i tipi 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.

    Un luogo può avere anche più valori di tipo dai tipi Tabella A associati. 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 di quello specificato. Ad esempio, specifichi di includere un tipo principale di "restaurant". La risposta può quindi contenere luoghi con un tipo principale "restaurant", ma 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 di ricerca nelle vicinanze (nuova).

    Tipi inclusi

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

    Se sono presenti tipi in conflitto, ad esempio un tipo che compare 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 da Tabella A da escludere da una ricerca.

    Se sono presenti tipi primari in conflitto, ad esempio un tipo che compare 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 di 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 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 un 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 sono identici ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il TLD specifico per paese 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 vigente.

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

Visualizzare le attribuzioni 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 le norme per Places SDK for Android.