Questo documento descrive come trovare un hotel, un ristorante o una stazione di servizio lungo un percorso pianificato. Scoprirai come utilizzare l'API Route per ottenere un polilinea del percorso e utilizzarlo con la richiesta Ricerca lungo il percorso (SAR) dell'API Places. Inoltre, scoprirai come ottenere i risultati migliori impostando l'origine della ricerca lungo il percorso, ad esempio dopo 2 ore di viaggio.
API Routes
Per cercare i luoghi lungo il percorso, utilizzeremo l'API Routes. I dati del percorso ricavati dalla risposta dell'API Routes sono una serie di coordinate LatLong dall'origine alla destinazione. I dati del percorso contengono tratti e passaggi che seguono la rete stradale.
I percorsi vengono restituiti anche come polilinea codificata, che viene trasmessa come parametro di input alla richiesta SAR. La codifica di polilinee è un algoritmo di compressione con perdita che consente di memorizzare una serie di coordinate come una singola stringa. L'ottenimento del polilinea dall'API Routes non è obbligatorio. Puoi creare i dati autonomamente, ma ai fini di questo esempio, l'API Routes è un modo rapido e sicuro per ottenere i dati richiesti.
In questo tutorial utilizziamo un percorso da Londra (-37.8167,144.9619) a Manchester (-37.8155, 144.9663)
Percorso nell'esempio: da Londra a Manchester
Passaggio 1: ottieni un percorso dall'API Routes
Per ottenere un itinerario dall'API Routes, dovrai fornire le seguenti informazioni:
- Le località di partenza e di destinazione
- La modalità di trasporto (guida, a piedi e così via)
- Eventuali waypoint (facoltativo)
- Eventuali preferenze (evitare pedaggi, evitare autostrade e così via)
- La preferenza di routing in base al traffico ti fornirà le stime più precise, ma è un'operazione più complessa dal punto di vista computazionale e, di conseguenza, aumenta la latenza della risposta.
{"origin":{
"location": {
"latLng":{
"latitude": -37.8167,
"longitude": 144.9619
}
}
},
"destination":{
"location": {
"latLng":{
"latitude":-37.8155,
"longitude": 144.9663
}
}
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
Quando effettui la chiamata, assicurati di includere il campo "encodedPolyline" nella maschera dei campi degli intestazioni.
headers = {
"Content-Type": "application/json",
"X-Goog-FieldMask": "routes.distanceMeters,routes.duration,routes.legs,routes.polyline.encodedPolyline"
}
La documentazione completa con esempi su come ottenere un percorso e ottenere polilinee del percorso.
Una volta fornite queste informazioni nella richiesta, l'API Routes restituirà un oggetto Route. L'oggetto route conterrà le seguenti informazioni:
- La distanza totale del percorso
- La durata totale del percorso
- Le tappe e i passaggi del percorso
- La polilinea codificata del percorso, delle tappe e dei passaggi.
{
"routes": [
{
"legs": [
{
"distanceMeters": 321799,
"duration": "15401s",
"staticDuration": "14518s",
"polyline": {
"encodedPolyline": "y_kyH`_XOr@q@xKGnBBZ|AlGPj@Y^k@^MEqAfAQLK?eI … <rest of content removed for readability>"
},
"startLocation": {
"latLng": {
"latitude": 51.507334500000006,
"longitude": -0.1280107
}
},
"endLocation": {
"latLng": {
"latitude": 53.4808513,
"longitude": -2.2425864
}
},
"steps": [
{
"distanceMeters": 320,
"staticDuration": "82s",
"polyline": {
"encodedPolyline": "y_kyH`_XOr@q@xKGnBBZ|AlG"
},
"startLocation": {
"latLng": {
"latitude": 51.507334500000006,
"longitude": -0.1280107
}
},
"endLocation": {
"latLng": {
"latitude": 51.507207,
"longitude": -0.1323681
}
},
"navigationInstruction": {
"maneuver": "DEPART",
"instructions": "Head northwest on Trafalgar Sq/A4 toward Spring Gardens\nContinue to follow A4\nLeaving toll zone\nEntering toll zone\nLeaving toll zone in 210m at Haymarket"
},
"localizedValues": {
"distance": {
"text": "0.3 km"
},
"staticDuration": {
"text": "1 min"
}
},
# rest of the response removed for readability
Passaggio 2: richiesta di ricerca lungo il percorso
La ricerca di testo dell'API Places ha una richiesta di ricerca lungo il percorso che ti consente di cercare luoghi lungo un percorso. Per effettuare una richiesta di ricerca lungo il percorso, dovrai fornire le seguenti informazioni minime:
- Maschera dei campi restituiti nella risposta
- Una chiave API valida per l'API abilitata nella console Google Cloud
- Stringa di testo di ricerca che indica i luoghi che stai cercando, ad esempio "ristorante vegetariano piccante"
- La polilinea codificata del percorso, recuperata dalla chiamata precedente all'API Routes
- URL per l'endpoint dell'API Places Text Search
import requests
url = 'https://places.googleapis.com/v1/places:searchText'
api_key = 'YOUR_API_KEY' # Replace with your actual API key
route_polyline = 'YOUR_ROUTE_POLYLINE' # Replace with your encoded route polyline
headers = {
'Content-Type': 'application/json',
'X-Goog-Api-Key': api_key,
'X-Goog-FieldMask': 'places.displayName,places.formattedAddress,places.priceLevel'
}
data = {
"textQuery":
"Spicy Vegetarian Food",
"searchAlongRouteParameters": {
"polyline": {
"encodedPolyline": route_polyline
}
}
}
response = requests.post(url, headers=headers, json=data)
Dati di richiesta di esempio
La richiesta di ricerca lungo il percorso restituirà un elenco di luoghi situati lungo il percorso. Ecco una breve parte dei dati di esempio. La lunghezza della risposta può essere limitata impostando il numero massimo di parametri dei risultati e aggiungendo altri campi, ovviamente, aumenta la quantità di dati ricevuti. Per ulteriori dettagli sulla risposta dell'API Places, consulta la documentazione.
{
"places": [
{
"formattedAddress": "33 Haymarket, London SW1Y 4HA, UK",
"displayName": {
"text": "xxx",
"languageCode": "en"
}
},
{
"formattedAddress": "224 Piccadilly, London W1J 9HP, UK",
"priceLevel": "PRICE_LEVEL_MODERATE",
"displayName": {
"text": "yyy",
"languageCode": "en"
}
},
{
"formattedAddress": "63 Neal St, London WC2H 9PJ, UK",
"displayName": {
"text": "zzz",
"languageCode": "en"
}
},
Dati di risposta di esempio
Riepilogo del percorso e tempi di deviazione
Trovare solo le sedi è un ottimo punto di partenza, ma sarà utile aggiungere le informazioni sul tempo necessario per raggiungerle. La ricerca di testo dell'API Places può anche restituire un campo routing summary che contiene sia la durata che la distanza da percorrere. Il campo di dati Riepiloghi route è un elemento secondario della radice della risposta, pertanto non devi includere il prefisso "places." nella maschera del campo.
'X-Goog-FieldMask': 'places.displayName,places.formattedAddress,places.priceLevel,routingSummaries'
Per ottenere i riepiloghi, devi anche fornire il parametro della località di partenza per la ricerca, che viene utilizzato per i calcoli.
"routingParameters": {
"origin": {
"latitude": -37.8167,
"longitude": 144.9619
}
}
Quando ricevi la risposta, è presente una nuova sezione con il riepilogo del percorso contenente tratte con durata e distanza in metri.
"routingSummaries": [
{
"legs": [
{
"duration": "662s",
"distanceMeters": 3093
}
]
},
Vediamo ora come definire dove avviare la ricerca lungo il percorso.
Passaggio 3: ottieni la posizione a 2 ore di distanza lungo il percorso
Prendiamo in considerazione un caso d'uso normale in cui il conducente vuole trovare ristoranti non all'inizio del percorso, ma più avanti lungo la strada. Nel nostro esempio, il tragitto da Londra a Manchester dura circa 4 ore. Il conducente vuole trovare un ristorante a 2 ore di distanza lungo il percorso. Questa richiesta ci fornisce la durata di 120 minuti * 60 secondi = 7200 secondi.
Nella risposta dell'API Routes abbiamo la durata di ogni tratto del percorso e di ogni passaggio di un tratto. Assicurati di includere il campo "legs" nella maschera di campi della richiesta. Esegui il ciclo delle frazioni e dei passaggi finché la durata accumulata non raggiunge il limite di 2 ore o 7200 secondi. Poi abbiamo trovato la tratta e il passaggio da impostare come origine della richiesta SAR
Per velocizzare il lavoro, ti consigliamo di provare la libreria polyline per Python. Puoi usarlo per ottenere le coordinate dal campo dati "polyline.endodedPolyline".
Esegui i seguenti comandi nel terminale dell'ambiente.
> pip install polyline
import requests
import polyline
# We've covered getting a Routes API response earlier,
data = response.json()
# Extract the first route and its encoded polyline
route = data["routes"][0]
polyline_points = polyline.decode(route["polyline"]["encodedPolyline"])
# Calculate total duration of the route in seconds
total_duration_seconds = route["duration"]
# Calculate the desired time offset in seconds, 2h = 120 minutes * 60
desired_time_offset_seconds = time_offset_minutes * 60
# Iterate through the legs and steps to find the point at the desired time offset
elapsed_time_seconds = 0
for leg in route["legs"]:
for step in leg["steps"]:
step_duration_seconds = step["staticDuration"]
# Check if the desired time offset falls within this step, remove last "s" from string and convert to int
second_value = int(step_duration_seconds[:-1])
if elapsed_time_seconds + second_value >= desired_time_offset_seconds:
# Interpolate to find the exact point within the step
fraction_of_step = (desired_time_offset_seconds - elapsed_time_seconds) / second_value
step_polyline_points = polyline.decode(step["polyline"]["encodedPolyline"])
index = int(len(step_polyline_points) * fraction_of_step)
return step_polyline_points[index]
elapsed_time_seconds += second_value
# If the point is not found (e.g., time offset exceeds route duration)
return None
Ora che abbiamo trovato la posizione sul percorso a 2 ore dall'inizio del viaggio, possiamo utilizzarla nella richiesta. Basta aggiungere la latitudine e la longitudine nel parametro "origin", che a sua volta fa parte del parametro "routingParameters". È consigliabile utilizzare il campo dati "routingSummaries" che abbiamo trattato in precedenza. Se vuoi, puoi anche aggiungere parametri aggiuntivi come la modalità di viaggio e le istruzioni per evitare i pedaggi.
"routingParameters": {
"origin": {
"latitude": xx.xxxx,
"longitude": yy.yyyy
},
"travelMode":"DRIVE",
"routeModifiers": {
"avoidTolls": true
}
}
Esempi di risultati (icona dell'auto aggiunta per mostrare l'origine della ricerca).
Come puoi vedere nell'immagine, l'API restituisce luoghi che sono orientati alla fine del percorso, con risultati che iniziano circa a metà viaggio. La ricerca continua a essere basata sugli stessi dati di Google Maps Platform, che prendono in considerazione la pertinenza e la distanza dei luoghi, tra gli altri fattori.
Conclusione
In questo tutorial abbiamo imparato a combinare due API di Google Maps Platform, Routes e Places, per pianificare un viaggio e trovare posti dove mangiare dopo 2 ore di viaggio. I passaggi da seguire sono ottenere una polilinea codificata contenente le coordinate di latitudine e longitudine per ogni tratto del percorso e impostare l'origine della richiesta di ricerca lungo il percorso per ottenere i risultati migliori.
Questa funzionalità aggiunge un nuovo strumento potente alla ricerca di testo e alla ricerca nelle vicinanze già esistenti nell'API Places. Il passaggio successivo logico sarebbe aggiungere i servizi di geolocalizzazione in modo da poter utilizzare la posizione del conducente come punto di partenza per trovare l'origine di ricerca ottimale. Inoltre, questa funzionalità funzionerebbe perfettamente con un assistente vocale in auto a cui potresti comunicare le tue opzioni di ristorazione preferite.
Passaggi successivi
- Prova gli esempi nella documentazione.
- Lascia un feedback.
Letture consigliate:
Collaboratori
Google gestisce questo documento. È stato scritto originariamente dal seguente collaboratore.
Autore principale: Mikko Toivanen | Google Maps Platform Solutions Engineer