Ricerca nelle vicinanze (Novità)

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Una Ricerca nelle vicinanze (novità) accetta uno o più tipi di luogo e restituisce un elenco di luoghi corrispondenti all'interno specifica. Una maschera di campo che specifica uno o più tipi di dati è obbligatorio. Ricerca nelle vicinanze (nuova) supporta solo richieste POST.

Explorer API ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e Opzioni API:

Prova!

Prova la modalità interattiva demo per visualizzare i risultati di Nearby Search (nuova) su una mappa.

Richieste di Ricerca nelle vicinanze (nuova)

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

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

Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte del 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)

La funzione Ricerca nelle vicinanze (nuova) restituisce un come risposta. Nella risposta:

  • L'array places contiene tutti i luoghi corrispondenti.
  • Ogni punto dell'array è rappresentato da un Place . L'oggetto Place contiene informazioni dettagliate su un singolo posto.
  • La FieldMask passata nella richiesta specifica l'elenco dei campi. restituito 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 un maschera del campo di risposta. Passa la maschera del campo di risposta al metodo utilizzando il parametro URL $fields o fields oppure tramite 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 pratica di progettazione per garantire di dati non necessari, così da evitare tempi di elaborazione non necessari addebiti di fatturazione.

    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.attributions, 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.types, places.utcOffsetMinutes, places.viewport

      * Il campo places.name contiene il luogo nome risorsa nel formato: places/PLACE_ID. Usa 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, 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.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.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 e 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 da Tabella A utilizzata per filtrare nei risultati di ricerca. È possibile specificare fino a 50 tipi per ogni categoria di limitazione dei tipi.

    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 specifichi un tipo principale generale, ad esempio "restaurant" o "hotel", la risposta può contenere luoghi con un tipo principale più specifico rispetto a quello specificato. Ad esempio, specifichi di includere un tipo primario di "restaurant". La risposta può quindi contenere luoghi con un tipo principale "restaurant", ma la risposta può anche contenere luoghi con un indirizzo di tipo principale, come "chinese_restaurant" o "seafood_restaurant".

    Se una ricerca viene specificata con più limitazioni di tipo, solo luoghi che soddisfano tutte le restrizioni. Ad esempio, se specifichi {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, i luoghi restituiti offrono 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 dei tipi di luogo dalla 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.

    includedPrimaryTypes

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

    excludedPrimaryTypes

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

  • languageCode

    La lingua in cui restituire i risultati.

    • Consulta l'elenco delle lingue supportate. spesso su Google aggiorna 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 INVALID_ARGUMENT .
    • L'API fa del suo meglio per fornire una via che sia leggibile sia per l'utente che per locali. Per raggiungere l'obiettivo, restituisce gli indirizzi nella lingua locale, traslitterato in uno script leggibile dall'utente se necessario, osservando lo script preferito lingua. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo tutti 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 scelto dall'API da restituire e l'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni dei tipi di strada 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. Il valore 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 loro distanza dal località specificata.

  • regionCode

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

    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.

Esempi di Ricerca nelle vicinanze (nuova)

Trova luoghi di un tipo

L'esempio seguente mostra una richiesta di Nearby Search (nuova) per la visualizzazione nomi 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 ha quindi la seguente forma:

{
  "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 il parametro l'indirizzo del ristorante, il tipo e l'indirizzo web 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 di Nearby Search (nuova) per visualizzare i nomi di tutti i minimarket e negozi di liquori entro un raggio di 1000 metri dalla specificato circle:

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
In questo esempio vengono aggiunti places.primaryType e places.types alla maschera del campo in modo che la risposta includa informazioni sul tipo di carattere per ogni luogo, semplificando la selezione del posto 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", classifica i risultati per 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 valore 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 ti consente di effettuare richieste di esempio di acquisire familiarità con le opzioni dell'API e delle 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 alla 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 Explorer API.