Ricerca nelle vicinanze (Novità)

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Una richiesta di Nearby Search (nuova) prende come input la regione per eseguire una ricerca specificata come un cerchio, definita dalla latitudine e dalla longitudine coordinate del punto centrale del cerchio e il raggio in metri. La restituisce un elenco di luoghi corrispondenti, ognuno dei quali è rappresentato da un 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 luogo da includi o escludi esplicitamente dalla risposta. Ad esempio, puoi specificare per includere nella risposta solo i luoghi di tipo "ristorante", "panetteria" e "bar" oppure escludi tutte le aree di tipo "scuola".

Nota: Ricerca nelle vicinanze (nuova) è disponibile nell'SDK Places per Android 3.5.0 e versioni successive. Per ulteriori informazioni, consulta la sezione Scegliere l'SDK dell'audiodescrizione.

Richieste di Ricerca nelle vicinanze (nuova)

Effettua una richiesta di Nearby Search (nuova) chiamando PlacesClient.searchNearby, passando un SearchNearbyRequest che definisce i parametri della richiesta.

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

• L'elenco di campi da restituire nell'oggetto Place, noto anche come maschera del campo di testo. Se non specifichi almeno un campo nell'elenco dei campi o se Se ometti l'elenco dei campi, la chiamata restituisce un errore.
• La restrizione 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 la risposta Place oggetti deve contenere i campi Place.Field.ID e Place.Field.NAME per ogni Oggetto Place nei risultati di ricerca. Inoltre filtra la risposta per mostrare restituisce luoghi di tipo "ristorante" e "caffè", ma escludere luoghi di tipo "pizza_ristorante" 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();
    });

Nota: per ulteriori informazioni sull'inizializzazione di PlacesClient, vedi Inizializza il client API Places.

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta a una delle classi di richiesta (ad esempio, FetchPlaceRequest). L'annullamento avviene 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à annullato e ti potrebbe comunque essere addebitato il costo della richiesta, anche se non viene restituita.

Risposte di Nearby Search (nuove)

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

• Un elenco di Place oggetti che rappresentano tutti i luoghi corrispondenti, con uno Place oggetto per 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 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 e il nome di ogni luogo corrispondente. Dopodiché potrai usare 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 Luogo di accesso campi di dati dell'oggetto.

Parametri obbligatori

Utilizza la SearchNearbyRequest per specificare i parametri richiesti per la ricerca.

• Elenco campi

  Quando richiedi i dettagli del luogo, devi specificare i dati da restituire nel Oggetto Place per il luogo come maschera di campo. Per definire la maschera del campo, passa un array di valori Place.Field all'oggetto SearchNearbyRequest. Il mascheramento dei campi è una buona pratica di progettazione per evitare di richiedere dati non necessari, evitando così inutili tempi di elaborazione e addebiti di fatturazione.

  Specifica uno o più dei seguenti campi:

  • I seguenti campi attivano la funzione Nearby Search (Di base) SKU:

    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 la funzione Nearby Search (Avanzato) SKU:

    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 la funzione Nearby Search (Preferito) SKU:

    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 di campi, richiama il metodo setPlaceFields() quando si crea l'oggetto SearchNearbyRequest.

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

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

  R LocationRestriction che definisce la regione da ricercare specificata come un cerchio, definita da punto centrale e raggio in metri. Il raggio deve essere compreso tra maggiore di 0,0 e minore o uguale a 50000,0, tenendo presente che specificando un raggio troppo piccolo restituisce ZERO_RESULTS come risposta.

  Per impostare il parametro di limitazione di località, richiama il metodo setLocationRestriction() quando si crea l'oggetto SearchNearbyRequest.

Parametri facoltativi

Utilizza la SearchNearbyRequest per specificare i parametri facoltativi per la ricerca.

• Tipi e tipi principali

  Consente di specificare un elenco di tipi da Tabella A utilizzata per filtrare nei risultati di ricerca. È possibile specificare fino a 50 tipi per ogni categoria di limitazione dei tipi.

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

  Un luogo può avere un solo singolo tipo principale tra i tipi Tabella A associata a li annotino. Ad esempio, il tipo principale potrebbe essere "mexican_restaurant" o "steak_house". Utilizza le funzionalità di includedPrimaryTypes e excludedPrimaryTypes per filtrare i risultati in base a il tipo principale di un luogo.

  Un luogo può anche avere più valori di tipo di tipi Tabella A associate. Ad esempio, un ristorante potrebbe avere i seguenti tipi: "seafood_restaurant", "restaurant", "food" "point_of_interest" "establishment". Usa includedTypes e excludedTypes per filtrare i risultati nell'elenco dei tipi associati a un luogo.

  Se una ricerca viene specificata con più limitazioni di tipo, solo luoghi che soddisfano tutte le restrizioni. Ad esempio, se specifichi includedTypes = Arrays.asList("restaurant") e excludedPrimaryTypes = Arrays.asList("steak_house"), i luoghi restituiti offrono servizi correlati a "restaurant" ma non operano principalmente come "steak_house".

  Se ometti includedTypes, excludedTypes, includedPrimaryTypes e excludedPrimaryTypes dalla richiesta, la ricerca restituisce i luoghi per tutti i tipi che rientrano nei limiti delle limitazioni di località.

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

  Tipi inclusi

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

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

  Se sono presenti tipi in conflitto, ad esempio un tipo visualizzato in includedTypes e 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 da 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 luogo principali da Tabella A da escludere da una ricerca.

  Se sono presenti tipi principali in conflitto, ad esempio un tipo che compare in includedPrimaryTypes e excludedPrimaryTypes, Viene restituito l'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. Il valore 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 loro distanza dal località 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 codice CLDR a due caratteri. Non esiste un valore predefinito.

  Se il nome del paese nel campo formattedAddress nella risposta corrisponde al regionCode, il codice paese è omesso da formattedAddress.

  La maggior parte dei codici CLDR è identica a i codici ISO 3166-1 con alcune degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk) mentre il codice ISO 3166-1 è "gb" (tecnicamente per persona giuridica del "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.

Attribuzioni display nell'app

Quando la tua app mostra informazioni ottenute da PlacesClient, come foto e recensioni, nell'app devono essere mostrate anche le attribuzioni richieste.

Per ulteriori informazioni, consulta la sezione Norme per l'SDK Places per Android.