Ricerca nelle vicinanze (novità)

Seleziona la piattaforma:Android iOS JavaScript Servizio web
Sviluppatori dello Spazio economico europeo (SEE)

Introduzione

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 del campo che specifichi uno o più tipi di dati. La ricerca nelle vicinanze (nuova) supporta solo le richieste POST.

L'Explorer API ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e le relative opzioni:

Prova la demo interattiva per visualizzare i risultati della ricerca nelle vicinanze (nuova) visualizzati su una mappa.

Richieste di Nearby Search (nuovo)

Una richiesta di ricerca nelle vicinanze (nuova) è una richiesta HTTP POST a un URL nel formato:

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

Trasmetti 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 alla ricerca nelle vicinanze (nuova)

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

  • L'array places contiene tutti i luoghi corrispondenti.
  • Ogni posizione nell'array è rappresentata da un oggetto Place. L'oggetto Place contiene informazioni dettagliate su un singolo luogo.
  • Il FieldMask passato 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. Passa la maschera del campo di risposta al metodo utilizzando il parametro URL $fields o fields oppure utilizzando l'intestazione HTTP X-Goog-FieldMask. Nella risposta non è presente un elenco predefinito di campi restituiti. Se ometti la maschera del campo, il metodo restituisce un errore.

    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 di fatturazione non necessari.

    Specifica un elenco separato da virgole dei tipi di dati sui 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 Pro:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      places.adrFormatAddress
      places.attributions
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.id
      places.location
      places.name**
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * I descrittori degli indirizzi sono generalmente disponibili per i clienti in India e sono sperimentali altrove.

      ** Il campo places.name contiene il nome risorsa del luogo nel formato: places/PLACE_ID. Utilizza places.displayName per accedere al nome testuale del luogo.

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

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

    • I seguenti campi attivano lo SKU Nearby Search Enterprise + Atmosphere:

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * Solo ricerca di testo e ricerca nelle vicinanze

  • locationRestriction

    La regione da cercare specificata come un 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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Consente di specificare un elenco di tipi dalla tabella A Tabella A utilizzati 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 di "restaurant", ma può anche contenere luoghi con un tipo principale più specifico, come "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": ["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 luogo della tabella A da cercare. Se questo parametro viene omesso, vengono restituiti luoghi di tutti i tipi.

    excludedTypes

    Un elenco separato da virgole di tipi di luoghi della 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.

    includedPrimaryTypes

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

    excludedPrimaryTypes

    Un elenco separato da virgole dei tipi di luoghi principali della 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.

  • languageCode

    La lingua in cui restituire i risultati.

    • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, quindi questo elenco potrebbe non essere esaustivo.
    • Se languageCode non viene fornito, l'API utilizza en come valore predefinito. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
    • L'API fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per gli abitanti del luogo. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in un sistema di scrittura leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, scelta dal primo componente.
    • Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.
    • 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 geocoder interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni dei tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra.

  • maxResultCount

    Specifica il numero massimo di risultati di 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 (impostazione predefinita) Ordina i risultati in base alla loro 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 un 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 alcun effetto su adrFormatAddress, che include sempre il nome del paese, né su shortFormattedAddress, che non lo include mai.

    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.

Esempi di Nearby Search (nuovo)

Trovare 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 è 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 ulteriori informazioni. 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 ha il seguente 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"
      }
    },
...
}

Trovare luoghi di più tipi

L'esempio seguente mostra una richiesta di ricerca nelle vicinanze (nuova) per i nomi visualizzati di tutti i minimarket e 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 sul tipo di ogni 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", escludendo tutti i luoghi di tipo "primary_school" e 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

Cercare tutti i luoghi vicino a un'area, ordinati per 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

Recupera i descrittori dell'indirizzo

I descrittori di indirizzo forniscono informazioni relazionali sulla posizione di un luogo, inclusi punti di riferimento nelle vicinanze e aree contenute.

L'esempio seguente mostra una richiesta di ricerca nelle vicinanze (nuova) per i luoghi vicino a un centro commerciale di San Jose. In questo esempio, includi addressDescriptors nella maschera del campo:

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

La risposta include il luogo specificato nella richiesta, un elenco di punti di riferimento nelle vicinanze e la loro distanza dal luogo, nonché un elenco di aree e la loro relazione di contenimento con il luogo:

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "displayName": {
                "text": "Nordstrom",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "department_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "straightLineDistanceMeters": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "areas": [
            {
              "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "displayName": {
                "text": "Westfield Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "displayName": {
                "text": "Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "displayName": {
                "text": "Central San Jose",
                "languageCode": "en"
              },
              "containment": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

Prova

L'Explorer API ti consente di effettuare richieste di esempio per familiarizzare con l'API e le relative opzioni.

  1. Seleziona l'icona API api sul lato destro della pagina.

  2. (Facoltativo) Modifica i parametri della richiesta.

  3. Seleziona il pulsante Esegui. Nella finestra di dialogo, scegli l'account che vuoi utilizzare per effettuare la richiesta.

  4. Nel riquadro Explorer API, seleziona l'icona a schermo intero fullscreen per espandere la finestra di Explorer API.