Questo documento descrive come trovare un hotel, un ristorante o una stazione di servizio lungo un percorso pianificato. Scoprirai come utilizzare l'API Routes per ottenere una polilinea di un percorso e utilizzarla con la richiesta API Places Cerca lungo il percorso (SAR). Inoltre, imparerai a ottenere i risultati migliori impostando l'origine della ricerca lungo il percorso, ad esempio dopo 2 ore di viaggio.
API Routes
Per cercare luoghi lungo il percorso, utilizzeremo l'API Routes. I dati dell'itinerario dalla risposta dell'API Routes sono una serie di coordinate LatLong dall'origine alla destinazione. I dati del percorso contengono segmenti e passaggi che seguono la rete stradale.
I percorsi vengono restituiti anche come polilinea codificata, che viene passata come parametro di input alla richiesta SAR. La codifica polilineare è un algoritmo di compressione con perdita che consente di memorizzare una serie di coordinate come una singola stringa. Ottenere la 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 itinerario dall'API Routes
Per ottenere un itinerario dall'API Routes, devi fornire le seguenti informazioni:
- Le posizioni di partenza e di destinazione
- La modalità di trasporto (auto, a piedi e così via)
- (Facoltativo) Eventuali waypoint
- 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ù pesante dal punto di vista computazionale e quindi 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 delle 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 le polilinee del percorso.
Una volta fornite queste informazioni nella richiesta, l'API Routes restituirà un oggetto percorso. L'oggetto percorso conterrà le seguenti informazioni:
- La distanza totale del percorso
- La durata totale del percorso
- Le tappe e i passaggi del percorso
- La polilinea codificata dell'itinerario, 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: cerca la richiesta Lungo il percorso
Il servizio Text Search dell'API Places include una richiesta di ricerca lungo il percorso che ti consente di cercare luoghi lungo un percorso. Per eseguire una richiesta di ricerca lungo il percorso, devi fornire le seguenti informazioni minime:
- Maschera del campo che indica quali campi vengono 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 dell'itinerario, recuperata dalla chiamata precedente dell'API Routes
- URL dell'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 Cerca lungo il percorso restituirà un elenco di luoghi che si trovano 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 l'aggiunta di altri campi aumenta la quantità di dati ricevuti. Per maggiori 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"
}
},
Esempio di dati di risposta
Riepilogo del percorso e tempi di deviazione
Trovare solo le posizioni è ottimo, ma sarebbe utile aggiungere le informazioni su quanto tempo ci vuole per raggiungere queste posizioni. La ricerca di testo dell'API Places può restituire anche un campo riepiloghi itinerari che contiene sia la durata che la distanza da percorrere. Il campo di dati Riepiloghi itinerari è 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 origine per la ricerca, che viene utilizzato per i calcoli.
"routingParameters": {
"origin": {
"latitude": -37.8167,
"longitude": 144.9619
}
}
Quando ricevi la risposta, questa contiene una nuova sezione con il riepilogo del percorso che include tratte con durata e distanza in metri.
"routingSummaries": [
{
"legs": [
{
"duration": "662s",
"distanceMeters": 3093
}
]
},
Successivamente, vedremo come definire il punto del percorso da cui iniziare la ricerca.
Passaggio 3: ottieni la posizione 2 ore dopo l'inizio del percorso
Considera un caso d'uso normale in cui il conducente vuole trovare ristoranti non all'inizio del percorso, ma più avanti. Nel nostro esempio, il viaggio 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 segmento del percorso e di ogni passaggio di un segmento. Assicurati di includere il campo "legs" nella maschera del campo nella tua richiesta. Ripeti i passaggi fino a quando la durata accumulata non raggiunge il limite di 2 ore o 7200 secondi. Abbiamo trovato la gamba e il passo da impostare come origine della richiesta SAR
Per velocizzare il lavoro, ti consigliamo di provare la libreria polilinee per Python. Puoi utilizzarlo per ottenere le coordinate dal campo dati "polyline.endodedPolyline".
Esegui questi 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. Puoi anche aggiungere parametri aggiuntivi come la modalità di viaggio e le indicazioni per evitare i pedaggi, se vuoi.
"routingParameters": {
"origin": {
"latitude": xx.xxxx,
"longitude": yy.yyyy
},
"travelMode":"DRIVE",
"routeModifiers": {
"avoidTolls": true
}
}
Esempio di risultati (icona dell'auto aggiunta per mostrare l'origine della ricerca).
Come puoi vedere nell'immagine, l'API restituisce luoghi che sono orientati verso la fine del percorso, con risultati che iniziano a circa metà del viaggio. La ricerca si basa ancora sugli stessi dati di Google Maps Platform, che tengono conto della pertinenza del luogo e della distanza, tra gli altri fattori.
Conclusione
In questo tutorial abbiamo imparato a combinare due API Google Maps Platform, Routes e Places, per pianificare un viaggio e trovare posti dove mangiare dopo 2 ore di viaggio. I passaggi necessari sono ottenere una polilinea codificata contenente le coordinate di latitudine e longitudine per ogni tappa del percorso e impostare l'origine della richiesta Cerca lungo il percorso per ottenere i risultati migliori.
Questa funzionalità aggiunge un nuovo e potente strumento alla ricerca di testo e alla ricerca nelle vicinanze già esistenti nell'API Places. Il passo successivo logico sarebbe aggiungere i servizi di localizzazione 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 insieme a un assistente vocale in auto a cui potresti comunicare le tue opzioni di ristorazione preferite.
Azioni successive
- Prova gli esempi nella documentazione.
- Lascia un feedback.
Letture consigliate:
Collaboratori
Google gestisce questo documento. Il seguente collaboratore l'ha scritto originariamente.
Autore principale: Mikko Toivanen | Solutions Engineer di Google Maps Platform