Ricerca nelle vicinanze (Novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

Una richiesta Ricerca nelle vicinanze (nuova) accetta uno o più tipi di luoghi e restituisce un elenco di luoghi corrispondenti all'interno dell'area specificata. È necessaria una maschera di campo che specifichi uno o più tipi di dati. Ricerca nelle vicinanze (nuova) supporta solo richieste POST.

Explorer API ti consente di effettuare richieste in tempo reale per acquisire familiarità con l'API e le relative opzioni:

Prova!

Prova la demo interattiva per visualizzare i risultati di Ricerca nelle vicinanze (nuova) mostrati su una mappa.

Richieste di Ricerca nelle vicinanze (nuova)

Una richiesta Nearby Search (nuova) è una richiesta POST HTTP a un URL nel modulo:

https://places.googleapis.com/v1/places:searchNearby

Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte della richiesta POST. Ad esempio:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Risposte di Nearby Search (nuove)

Nearby Search (New) restituisce un oggetto JSON come risposta. Nella risposta:

  • L'array places contiene tutti i luoghi corrispondenti.
  • Ogni luogo nell'array è rappresentato da un oggetto Place. L'oggetto Place contiene informazioni dettagliate su un singolo luogo.
  • La FieldMask passata nella richiesta specifica l'elenco dei campi restituiti nell'oggetto Place.

L'oggetto JSON completo ha il seguente formato:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Parametri obbligatori

  • FieldMask

    Specifica l'elenco dei campi da restituire nella risposta creando una maschera del campo di risposta. Trasmetti la maschera del campo di risposta al metodo utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP X-Goog-FieldMask. La risposta non contiene un elenco predefinito dei campi restituiti. Se ometti la maschera di campo, il metodo restituisce un errore.

    Il mascheramento dei campi è una buona prassi di progettazione per evitare di richiedere dati non necessari, evitando così tempi di elaborazione e addebiti di fatturazione superflui.

    Specifica un elenco separato da virgole dei tipi di dati dei luoghi da restituire. Ad esempio, per recuperare il nome visualizzato e l'indirizzo del luogo.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Utilizza * per recuperare tutti i campi.

    X-Goog-FieldMask: *

    Specifica uno o più dei seguenti campi:

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

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinations, places.adrFormatAddress{1/resource.} places.adrFormatAddress {1/resource}, places.adrFormatAddressplaces.nameplaces.typesplaces.utcOffsetMinutesplaces.viewport

      places/PLACE_ID Utilizza places.displayName per accedere al nome testuale del luogo.

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

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount e places.websiteUri

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

      places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.servesBeer, places.delivery, places.delivery, places.delivery, places.deliveryplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • locationRestriction

    La regione da cercare specificata sotto forma di cerchio, definita dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il raggio predefinito è 0,0. Devi impostarlo nella richiesta su un valore maggiore di 0,0.

    Ad esempio: 

    "locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

Parametri facoltativi

  • InclusoType/excludedTypes, IncludeMainTypes/excludedprimaryTypes

    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": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, i luoghi restituiti forniscono servizi correlati a "restaurant", ma non operano principalmente come "steak_house".

    includedTypes

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

    excludedTypes

    Un elenco separato da virgole di tipi di luoghi da escludere dalla ricerca dalla Tabella A.

    Se specifichi nella richiesta 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.

    includedPrimaryTypes

    Un elenco separato da virgole dei tipi di luoghi principali della Tabella A da includere nella ricerca.

    excludedPrimaryTypes

    Un elenco separato da virgole dei tipi di luoghi principali dalla Tabella A da escludere dalla 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.

  • languageCode

    La lingua in cui restituire i risultati.

    • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
    • Se languageCode non viene fornito, l'API predefinita sarà en. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • L'API fa del suo meglio per fornire un indirizzo che sia leggibile sia per l'utente sia per la gente del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in uno script leggibile dall'utente se necessario, osservando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti degli indirizzi vengono restituiti nella stessa lingua, che viene scelta dal primo componente.
    • Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più simile.
    • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni dei tipi di strade o i sinonimi che possono essere validi in una lingua, ma non in un'altra.

  • maxResultCount

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

  • rankPreference

    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.

  • regionCode

    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. Questo parametro non ha effetto su adrFormatAddress, che include sempre il nome del paese, oppure su shortFormattedAddress, che non lo include mai.

    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.

Esempi di Ricerca nelle vicinanze (nuova)

Trova luoghi di un tipo

L'esempio seguente mostra una richiesta di ricerca nelle vicinanze (nuova) per i nomi visualizzati di tutti i ristoranti entro un raggio di 500 metri, definito da circle: 

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Tieni presente che l'intestazione X-Goog-FieldMask specifica che la risposta contiene i seguenti campi di dati: places.displayName. La risposta si presenta quindi nel formato:

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

Aggiungi altri tipi di dati alla maschera del campo per restituire informazioni aggiuntive. Ad esempio, aggiungi places.formattedAddress,places.types,places.websiteUri per includere l'indirizzo, il tipo e l'indirizzo web del ristorante nella risposta:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

La risposta ora è nel formato:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Trova luoghi di vari tipi

L'esempio seguente mostra una richiesta Ricerca nelle vicinanze (nuova) per i nomi visualizzati di tutti i minimarket e i negozi di liquori entro un raggio di 1000 metri dal circle specificato:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
Questo esempio aggiunge places.primaryType e places.types alla maschera del campo in modo che la risposta includa informazioni di tipo su ciascun luogo, semplificando la selezione del luogo appropriato dai risultati.

L'esempio seguente mostra una richiesta di Ricerca nelle vicinanze (nuova) per tutti i luoghi di tipo "school", esclusi tutti i luoghi di tipo "primary_school", classificando i risultati in base alla distanza:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Cerca tutti i luoghi nelle vicinanze di un'area, classificandoli in base alla distanza

L'esempio seguente mostra una richiesta di Ricerca nelle vicinanze (nuova) per luoghi vicino a un punto nel centro di San Francisco. In questo esempio, includi il parametro rankPreference per classificare i risultati in base alla distanza:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Prova.

Explorer API consente di effettuare richieste di esempio, per acquisire familiarità con le opzioni API e API.

  1. Seleziona l'icona dell'API Espandi Explorer API. sul lato destro della pagina.
  2. Se vuoi, espandi Mostra parametri standard e imposta il parametro fields sulla maschera del campo.
  3. Se vuoi, modifica il corpo della richiesta.
  4. Seleziona il pulsante Esegui. Nella finestra popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.

  5. Nel riquadro Explorer API, seleziona l'icona Espandi, Espandi Explorer API., per espandere la finestra di Explorer API.