Nearby Search (Legacy) ti consente di cercare luoghi all'interno di un'area specifica. Puoi perfezionare la richiesta di ricerca fornendo parole chiave o specificando il tipo di luogo che stai cercando.
Richieste di Nearby Search (legacy)
Una richiesta di Nearby Search (Legacy) è un URL HTTP nel seguente formato:
https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters
dove output può essere uno dei seguenti valori:
json(consigliato) indica l'output in JavaScript Object Notation (JSON)xmlindica l'output in formato XML
Per avviare una richiesta di Nearby Search (Legacy) sono necessari alcuni parametri. Come è standard negli URL, tutti i parametri sono separati utilizzando il carattere e commerciale (&).
Parametri obbligatori
-
località
Il punto intorno al quale recuperare le informazioni sul luogo. Deve essere specificato come
latitude,longitude. -
raggio
Definisce la distanza (in metri) entro la quale restituire i risultati dei luoghi. Puoi influenzare i risultati in base a un cerchio specificato passando un parametro
locatione un parametroradius. In questo modo, il servizio Places viene istruito a preferire la visualizzazione dei risultati all'interno di quel cerchio; i risultati al di fuori dell'area definita potrebbero comunque essere visualizzati.Il raggio verrà automaticamente limitato a un valore massimo a seconda del tipo di ricerca e di altri parametri.
- Completamento automatico: 50.000 metri
-
Nearby Search:
- con
keywordoname: 50.000 metri -
senza
keywordoname-
Fino a 50.000 metri, regolati dinamicamente in base alla densità dell'area, indipendentemente dal parametro
rankby. -
Quando utilizzi
rankby=distance, il parametro radius non verrà accettato e verrà generato un erroreINVALID_REQUEST.
-
Fino a 50.000 metri, regolati dinamicamente in base alla densità dell'area, indipendentemente dal parametro
- con
- Query Autocomplete: 50.000 metri
- Ricerca testuale: 50.000 metri
Parametri facoltativi
-
parola chiave
La stringa di testo su cui eseguire la ricerca, ad esempio "ristorante" o "123 Main Street". Deve essere un nome di luogo, un indirizzo o una categoria di attività. Qualsiasi altro tipo di input può generare errori e non è garantito che restituisca risultati validi. Il servizio Google Places restituirà le corrispondenze candidate in base a questa stringa e ordinerà i risultati in base alla loro pertinenza percepita.
L'inclusione esplicita dei dati sulla posizione utilizzando questo parametro potrebbe entrare in conflitto con i parametri location, radius e rankby, causando risultati imprevisti.
Se questo parametro viene omesso, i luoghi con un business_status CLOSED_TEMPORARILY o CLOSED_PERMANENTLY non verranno restituiti.
-
language
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
languagenon viene fornito, l'API tenta di utilizzare la lingua preferita specificata nell'intestazioneAccept-Language. - L'API fa del suo meglio per fornire un indirizzo leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua, che viene 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 geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada in ungherese.
-
maxprice
Limita i risultati solo ai luoghi compresi nell'intervallo specificato. I valori validi sono compresi tra 0 (più economico) e 4 (più costoso) inclusi. L'importo esatto indicato da un valore specifico varia da regione a regione.
-
minprice
Limita i risultati solo ai luoghi compresi nell'intervallo specificato. I valori validi sono compresi tra 0 (più economico) e 4 (più costoso) inclusi. L'importo esatto indicato da un valore specifico varia in base alla regione.
-
nome
Equivalente a
keyword. I valori di questo campo vengono combinati con i valori del campokeyworde trasmessi come parte della stessa stringa di ricerca. -
opennow
Restituisce solo i luoghi aperti al momento dell'invio della query. I luoghi che non specificano l'orario di apertura nel database di Google Places non verranno restituiti se includi questo parametro nella query.
-
pagetoken
Restituisce fino a 20 risultati di una ricerca eseguita in precedenza. L'impostazione di un parametro
pagetokenesegue una ricerca con gli stessi parametri utilizzati in precedenza; tutti i parametri diversi dapagetokenvengono ignorati. -
rankby
Specifica l'ordine in cui vengono elencati i risultati. I valori possibili sono:
-
prominence(valore predefinito). Questa opzione ordina i risultati in base alla loro importanza. Il ranking favorirà i luoghi in evidenza all'interno del raggio impostato rispetto ai luoghi nelle vicinanze che corrispondono, ma che sono meno in evidenza. L'importanza può essere influenzata dal ranking di un luogo nell'indice di Google, dalla popolarità globale e da altri fattori. Quando viene specificata la rilevanza, il parametroradiusè obbligatorio. -
distance. Questa opzione influisce sui risultati di ricerca in ordine crescente in base alla distanza dalla località specificata. Quando viene specificatodistance, sono obbligatori uno o più valori dikeyword,nameotypeeradiusnon è consentito.
-
-
tipo
Limita i risultati ai luoghi corrispondenti al tipo specificato. Puoi specificare un solo tipo. Se fornisci più di un tipo, l'API ignora tutti i tipi successivi alla prima voce.
-
type=hospital|pharmacy|doctordiventatype=hospital type=hospital,pharmacy,doctorviene ignorato completamente
Consulta l'elenco dei tipi supportati.
Nota: l'aggiunta dikeywordetypecon lo stesso valore (keyword=cafe&type=cafeokeyword=parking&type=parking) può generareZERO_RESULTS. -
Esempio di Nearby Search (legacy)
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522%2C151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY'HTTP
https://maps.googleapis.com/maps/api/place/nearbysearch/json ?keyword=cruise &location=-33.8670522%2C151.1957362 &radius=1500 &type=restaurant &key=YOUR_API_KEY
Nota: in questo esempio, devi sostituire key con la tua chiave API affinché la richiesta funzioni nella tua applicazione.
Risposte di Nearby Search (legacy)
L'esempio seguente mostra una risposta di Nearby Search (Legacy).
JSON
{ "html_attributions": [], "results": [ { "business_status": "OPERATIONAL", "geometry": { "location": { "lat": -33.8587323, "lng": 151.2100055 }, "viewport": { "northeast": { "lat": -33.85739847010727, "lng": 151.2112436298927 }, "southwest": { "lat": -33.86009812989271, "lng": 151.2085439701072 }, }, }, "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png", "icon_background_color": "#FF9E67", "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet", "name": "Cruise Bar", "opening_hours": { "open_now": false }, "photos": [ { "height": 608, "html_attributions": [ 'A Google User', ], "photo_reference": "Aap_uECvJIZuXT-uLDYm4DPbrV7gXVPeplbTWUgcOJ6rnfc4bUYCEAwPU_AmXGIaj0PDhWPbmrjQC8hhuXRJQjnA1-iREGEn7I0ZneHg5OP1mDT7lYVpa1hUPoz7cn8iCGBN9MynjOPSUe-UooRrFw2XEXOLgRJ-uKr6tGQUp77CWVocpcoG", "width": 1080, }, ], "place_id": "ChIJi6C1MxquEmsR9-c-3O48ykI", "plus_code": { "compound_code": "46R6+G2 The Rocks, New South Wales", "global_code": "4RRH46R6+G2", }, "price_level": 2, "rating": 4, "reference": "ChIJi6C1MxquEmsR9-c-3O48ykI", "scope": "GOOGLE", "types": ["bar", "restaurant", "food", "point_of_interest", "establishment"], "user_ratings_total": 1269, "vicinity": "Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks", }, { "business_status": "OPERATIONAL", "geometry": { "location": { "lat": -33.8675219, "lng": 151.2016502 }, "viewport": { "northeast": { "lat": -33.86614532010728, "lng": 151.2031259298927 }, "southwest": { "lat": -33.86884497989272, "lng": 151.2004262701072 }, }, }, "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png", "icon_background_color": "#7B9EB0", "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet", "name": "Sydney Harbour Dinner Cruises", "opening_hours": { "open_now": true }, "photos": [ { "height": 835, "html_attributions": [ 'A Google User', ], "photo_reference": "Aap_uEBVsYnNcrpRixtrlHBztigZh70CwYkNWZzQnqJ39SjeBo_wvgKf-kXc6tgaMLBdQrRKmxmSKjOezoZrv-sHKVbTX0OI48HBqYYVnQiZQ-WGeuQDsLEPwX7LaVPa68nUAxX114Zpqt7bryoO9wL4qXdgEnopbOp5WWLALhKEHoIEH7f7", "width": 1200, }, ], "place_id": "ChIJM1mOVTS6EmsRKaDzrTsgids", "plus_code": { "compound_code": "46J2+XM Sydney, New South Wales", "global_code": "4RRH46J2+XM", }, "rating": 4.8, "reference": "ChIJM1mOVTS6EmsRKaDzrTsgids", "scope": "GOOGLE", "types": [ "tourist_attraction", "travel_agency", "restaurant", "food", "point_of_interest", "establishment", ], "user_ratings_total": 9, "vicinity": "32 The Promenade, Sydney", }, // ... ], "status": "OK", }
XML
<?xml version="1.0" encoding="UTF-8"?> <PlaceSearchResponse> <status>OK</status> <result> <name>Cruise Bar</name> <vicinity>Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks</vicinity> <type>bar</type> <type>restaurant</type> <type>food</type> <type>point_of_interest</type> <type>establishment</type> <geometry> <location> <lat>-33.8587323</lat> <lng>151.2100055</lng> </location> <viewport> <southwest> <lat>-33.8600981</lat> <lng>151.2085440</lng> </southwest> <northeast> <lat>-33.8573985</lat> <lng>151.2112436</lng> </northeast> </viewport> </geometry> <rating>4.0</rating> <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png</icon> <reference>ChIJi6C1MxquEmsR9-c-3O48ykI</reference> <opening_hours> <open_now>false</open_now> </opening_hours> <photo> <photo_reference>Aap_uEALIq4sgBHhIYWWapOH2NV1T2I7YdOiLzEH7z-483I764cId1sZkbzSq-hVYTk1PQeaHuZzlRfA7-ilwJ3QWon4b37ePd-PBwZbOwFZHxhYs0Cs7jRSgMHWfOzGivp6ZFG4iupyz50qS5pBZT1WbA2ufacTq_U21TtgffQD31wKRPQk</photo_reference> <width>1080</width> <height>608</height> <html_attribution><a href="https://maps.google.com/maps/contrib/112582655193348962755">A Google User</a></html_attribution> </photo> <price_level>2</price_level> <user_ratings_total>1269</user_ratings_total> <place_id>ChIJi6C1MxquEmsR9-c-3O48ykI</place_id> <scope>GOOGLE</scope> <plus_code> <global_code>4RRH46R6+G2</global_code> <compound_code>46R6+G2 The Rocks, New South Wales</compound_code> </plus_code> <icon_background_color>#FF9E67</icon_background_color> <business_status>OPERATIONAL</business_status> <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet</icon_mask_base_uri> </result> <result> <name>Sydney Harbour Dinner Cruises</name> <vicinity>32 The Promenade, Sydney</vicinity> <type>tourist_attraction</type> <type>restaurant</type> <type>food</type> <type>travel_agency</type> <type>point_of_interest</type> <type>establishment</type> <geometry> <location> <lat>-33.8675219</lat> <lng>151.2016502</lng> </location> <viewport> <southwest> <lat>-33.8688450</lat> <lng>151.2004263</lng> </southwest> <northeast> <lat>-33.8661453</lat> <lng>151.2031259</lng> </northeast> </viewport> </geometry> <rating>4.8</rating> <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png</icon> <reference>ChIJM1mOVTS6EmsRKaDzrTsgids</reference> <opening_hours> <open_now>true</open_now> </opening_hours> <photo> <photo_reference>Aap_uEB5jH7GXdcozv1Y5HX18syo4f128S58NVUnqBbLJMpWbC39K49wp-wzsLOsUT8QKDaag6ISFL8hl1vVuig4jkc5fMMkWKiqw5PY-ebcWZ5tI3gEXEYGGoG_mDAulaMLudUpSwgBx2_RLnA0SSiugqqQUTYlkGyCZSe8HSyngVczy6XN</photo_reference> <width>1200</width> <height>835</height> <html_attribution><a href="https://maps.google.com/maps/contrib/109764923610545394994">A Google User</a></html_attribution> </photo> <user_ratings_total>9</user_ratings_total> <place_id>ChIJM1mOVTS6EmsRKaDzrTsgids</place_id> <scope>GOOGLE</scope> <plus_code> <global_code>4RRH46J2+XM</global_code> <compound_code>46J2+XM Sydney, New South Wales</compound_code> </plus_code> <icon_background_color>#7B9EB0</icon_background_color> <business_status>OPERATIONAL</business_status> <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri> </result> <!-- ... --> </PlaceSearchResponse>
PlacesNearbySearchResponse
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
required | Array<string> |
Può contenere un insieme di attribuzioni relative a questa scheda che devono essere mostrate all'utente (alcune schede potrebbero non avere attribuzioni). |
|
required | Array<Place> |
Contiene un array di luoghi.
Le richieste Place Search restituiscono un sottoinsieme dei campi restituiti dalle richieste Place Details. Se il campo che ti interessa non viene restituito da Place Search, puoi utilizzare Place Search per ottenere un
place_id, quindi utilizzare questo ID luogo per effettuare una richiesta Place Details.
Per saperne di più, consulta Place. |
|
elemento obbligatorio | PlacesSearchStatus |
Contiene lo stato della richiesta e può contenere informazioni di debug per aiutarti a individuare il motivo per cui la richiesta non è andata a buon fine. Per saperne di più, consulta PlacesSearchStatus. |
|
facoltativo | stringa |
Quando il servizio restituisce un codice di stato diverso da |
|
facoltativo | Array<string> |
Quando il servizio restituisce informazioni aggiuntive sulla specifica della richiesta, potrebbe essere presente un campo |
|
facoltativo | stringa |
Contiene un token che può essere utilizzato per restituire fino a 20 risultati aggiuntivi. Se non sono presenti altri risultati da visualizzare, non verrà restituito un token next_page_token. Il numero massimo di risultati che è possibile restituire è 60. Esiste un breve ritardo tra l'emissione di un token next_page_token e il momento in cui diventa valido. |
PlacesSearchStatus
Codici di stato restituiti dal servizio.
OK, che indica che la richiesta API è andata a buon fine.-
ZERO_RESULTSche indica che la ricerca è andata a buon fine, ma non ha restituito risultati. Questo può accadere se alla ricerca è stato passato unlatlngin una località remota. -
INVALID_REQUESTindica che la richiesta API non era in un formato valido, in genere a causa di un parametro di query obbligatorio mancante (locationoradius). -
OVER_QUERY_LIMITche indica uno dei seguenti elementi:- Hai superato i limiti di QPS.
- La fatturazione non è stata abilitata sul tuo account.
- È stato superato il credito mensile di 200 $o un limite di utilizzo autoimposto.
- Il metodo di pagamento fornito non è più valido (ad esempio, una carta di credito è scaduta).
-
REQUEST_DENIEDche indica che la tua richiesta è stata rifiutata, in genere perché:- La richiesta non contiene una chiave API.
- Il parametro
keynon è valido.
UNKNOWN_ERRORche indica un errore sconosciuto.
Luogo
Le risposte di Place Search restituiscono il seguente sottoinsieme di campi Place. Non tutti gli attributi sono disponibili per tutti i tipi di luoghi. Per recuperare i campi che Place Search non restituisce, ad esempio address_components, formatted_phone_number, reviews o website, passa il valore place_id restituito in una richiesta Place Details (Legacy). Per la disponibilità dei campi e i livelli di prezzo tra gli endpoint, consulta Campi di dati di Place (legacy).
| Campo | Tipo | Descrizione |
|---|---|---|
business_status |
string |
Indica lo stato di attività del luogo, se si tratta di un'attività:
OPERATIONAL, CLOSED_TEMPORARILY o
CLOSED_PERMANENTLY. Omesso se non esistono dati sullo stato.
|
formatted_address |
string |
L'indirizzo leggibile di questo luogo. Restituito da Ricerca testuale (Legacy) e Trova luogo (Legacy). Non analizzare l'indirizzo formattato in modo programmatico; richiedi invece address_components in Place Details (Legacy).
|
geometry |
Geometry
|
Contiene il location geocodificato con le coordinate lat e lng e il viewport preferito con i limiti northeast e southwest.
|
icon |
string |
L'URL di un'icona suggerita che puoi mostrare quando indichi questo risultato su una mappa. |
icon_background_color
|
string |
Il codice colore esadecimale predefinito per la categoria del luogo. |
icon_mask_base_uri |
string |
L'URL di base di un'icona consigliata, senza l'estensione del tipo di file SVG o PNG. |
name |
string |
Il nome leggibile del risultato restituito. Per i risultati establishment, questo valore è in genere il nome dell'attività in formato canonico.
|
opening_hours |
PlaceOpeningHours
|
Informazioni sull'orario di apertura. Gli endpoint di Place Search restituiscono solo il sottocampo booleano open_now; richiedi opening_hours in Place Details (Legacy) per periods e weekday_text.
|
permanently_closed |
boolean |
Ritirato: utilizza business_status per controllare lo stato di attività di un'attività.
|
photos |
Array<PlacePhoto>
|
Un array di oggetti PlacePhoto, ognuno contenente photo_reference, height, width e html_attributions. Per i dettagli sull'utilizzo, consulta Foto dei luoghi (legacy).
|
place_id |
string |
Un identificatore testuale che identifica in modo univoco un luogo. Passa questo ID nel parametro place_id di una richiesta Place Details (Legacy). Consulta la panoramica degli ID luogo.
|
plus_code |
PlusCode
|
Un riferimento di posizione codificato derivato dalle coordinate di latitudine e longitudine, contenente un global_code e un compound_code facoltativo.
|
price_level |
integer |
Il livello di prezzo del luogo su una scala da 0 a 4, dal meno costoso al più costoso. Consulta price_level.
|
rating |
number |
La valutazione del luogo, da 1.0 a 5.0, in base alle recensioni aggregate degli utenti.
|
reference |
string |
Deprecato: utilizza place_id.
|
scope |
string |
Deprecato: indica l'ambito di place_id, che è sempre GOOGLE. Restituito da Nearby Search (Legacy).
|
types |
Array<string> |
Un array di tipi di caratteristiche che descrivono il risultato specificato. Consulta Tipi di luoghi (legacy). |
user_ratings_total |
integer |
Il numero totale di valutazioni, con o senza testo della recensione, per questo luogo. |
vicinity |
string |
Un indirizzo semplificato del luogo, inclusi il nome della via, il numero civico e la località, senza stato o provincia, codice postale o paese. Restituito da Nearby Search (Legacy). |
Accesso a risultati aggiuntivi
Per impostazione predefinita, ogni risposta restituisce fino a 20 risultati establishment per query. Tuttavia, ogni ricerca può restituire fino a 60 risultati, suddivisi in tre pagine. Se la ricerca restituisce più di 20 risultati, la risposta di ricerca includerà un valore aggiuntivo: next_page_token. Passa il valore di next_page_token al parametro pagetoken di una nuova richiesta per visualizzare il successivo insieme di risultati.
- Se
next_page_tokenè null o non viene restituito, non ci sono altri risultati. - Se ripeti la richiesta con lo stesso
next_page_token, verrà restituita la pagina di risultati successiva. - L'impostazione di
pagetokencomporterà l'ignoramento di tutti gli altri parametri. - Puoi richiedere una nuova pagina fino a due volte dopo la query originale.
- Ogni richiesta, inclusa una richiesta che utilizza
next_page_token, viene conteggiata come una singola richiesta ai fini dei limiti di utilizzo e viene addebitata separatamente. - C'è un ritardo di alcuni secondi tra l'emissione di un
next_page_tokene il momento in cui diventa valido. Se richiedi la pagina successiva prima che sia disponibile, verrà restituita una rispostaINVALID_REQUEST. Le richieste connext_page_tokenvengono sempre addebitate.
Ad esempio, nella query seguente, cerchiamo ristoranti vicino a Darling Harbour, a Sydney, in Australia, e ordiniamo i risultati in base alla distanza. Puoi vedere che la risposta contiene una proprietà next_page_token.
{
"html_attributions" : [],
"next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
"results" : [...]
"status" : "OK"
}Per visualizzare il successivo insieme di risultati, puoi inviare una nuova query, passando il risultato di next_page_token al parametro pagetoken. Ad esempio:
https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY