Z tego dokumentu dowiesz się, jak znaleźć hotel, restaurację lub stację paliw na zaplanowanej trasie. Dowiesz się, jak używać interfejsu Routes API do pobierania linii łamanej trasy i jak używać jej w żądaniu interfejsu Places API Search Along Route (SAR). Dowiesz się też, jak uzyskać najlepsze wyniki, ustawiając punkt początkowy wyszukiwania na trasie, np. 2 godziny od rozpoczęcia podróży.
Routes API
Aby wyszukiwać miejsca na trasie, użyjemy interfejsu Routes API. Dane trasy z odpowiedzi interfejsu API Trasy to seria współrzędnych LatLong od miejsca docelowego do miejsca docelowego. Dane trasy zawierają odcinki i kroki, które są zgodne z siecią dróg.
Trasy są też zwracane jako zakodowana linia łamana, którą przekazujesz jako parametr wejściowy do żądania SAR. Kodowanie linii łamanej to algorytm kompresji stratnej, który umożliwia przechowywanie serii współrzędnych w postaci jednego ciągu znaków. Pobieranie linii łamanej z interfejsu Routes API nie jest obowiązkowe. Możesz samodzielnie utworzyć dane, ale w tym przykładzie interfejs Routes API jest szybkim i pewnym sposobem na uzyskanie wymaganych danych.
W tym samouczku użyjemy trasy z Londynu (-37.8167,144.9619) do Manchesteru (-37.8155, 144.9663).
Trasa w przykładzie: Londyn–Manchester
Krok 1. Uzyskaj trasę z Routes API
Aby uzyskać trasę z interfejsu Routes API, musisz podać te informacje:
- lokalizacje początkową i docelową,
- środek transportu (samochód, pieszo itp.);
- Dowolne punkty pośrednie (opcjonalnie)
- wszelkie preferencje (unikanie opłat, autostrad itp.);
- Preferencja routingu uwzględniającego ruch zapewnia najdokładniejsze szacunki, ale jest bardziej wymagająca obliczeniowo i zwiększa opóźnienie odpowiedzi.
{"origin":{
"location": {
"latLng":{
"latitude": -37.8167,
"longitude": 144.9619
}
}
},
"destination":{
"location": {
"latLng":{
"latitude":-37.8155,
"longitude": 144.9663
}
}
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
Podczas wywoływania funkcji pamiętaj, aby w masce pola nagłówków uwzględnić pole „encodedPolyline”.
headers = {
"Content-Type": "application/json",
"X-Goog-FieldMask": "routes.distanceMeters,routes.duration,routes.legs,routes.polyline.encodedPolyline"
}
Pełna dokumentacja z przykładami pobierania trasy i pobierania polilinii trasy.
Gdy podasz te informacje w żądaniu, interfejs Routes API zwróci obiekt trasy. Obiekt trasy zawiera te informacje:
- całkowitą odległość trasy,
- Całkowity czas trwania trasy
- odcinki i etapy trasy,
- Zakodowana linia łamana trasy, odcinków i kroków.
{
"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
Krok 2. Wyszukaj prośbę o wyszukiwanie wzdłuż trasy
Interfejs Places API Text Search udostępnia żądanie Search Along Route, które umożliwia wyszukiwanie miejsc na trasie. Aby wysłać prośbę o wyszukiwanie wzdłuż trasy, musisz podać co najmniej te informacje:
- Maska pola określająca, które pola są zwracane w odpowiedzi.
- prawidłowy klucz interfejsu API dla interfejsu API włączonego w konsoli Google Cloud;
- Ciąg tekstowy wyszukiwania określający, jakich miejsc szukasz, np. „pikantna restauracja wegetariańska”.
- Zakodowana linia łamana trasy pobrana z poprzedniego wywołania interfejsu API Trasy.
- Adres URL punktu końcowego interfejsu Places Text Search API
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)
Przykładowe dane żądania
Żądanie wyszukiwania wzdłuż trasy zwróci listę miejsc znajdujących się wzdłuż trasy. Oto krótki fragment przykładowych danych. Długość odpowiedzi można ograniczyć, ustawiając maksymalną liczbę parametrów wyników. Dodanie większej liczby pól oczywiście zwiększa ilość otrzymywanych danych. Więcej informacji o odpowiedzi interfejsu Places API znajdziesz w dokumentacji.
{
"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"
}
},
Przykładowe dane odpowiedzi
Podsumowanie trasy i czas objazdu
Znalezienie samych lokalizacji jest przydatne, ale warto dodać informacje o tym, ile czasu zajmuje dotarcie do tych miejsc. Interfejs Places API Text Search może też zwracać pole routing_summaries, które zawiera czas i dystans podróży. Pole danych Routing summaries (Podsumowania tras) jest elementem podrzędnym głównego elementu odpowiedzi, więc w masce pola nie możesz umieszczać prefiksu „places.”.
'X-Goog-FieldMask': 'places.displayName,places.formattedAddress,places.priceLevel,routingSummaries'
Aby uzyskać podsumowania, musisz też podać parametr lokalizacji początkowej wyszukiwania, który jest używany do obliczeń.
"routingParameters": {
"origin": {
"latitude": -37.8167,
"longitude": 144.9619
}
}
Odpowiedź zawiera nową sekcję z podsumowaniem trasy, w której znajdują się odcinki z czasem trwania i odległością w metrach.
"routingSummaries": [
{
"legs": [
{
"duration": "662s",
"distanceMeters": 3093
}
]
},
Następnie przyjrzymy się, jak określić, w którym miejscu na trasie rozpocząć wyszukiwanie.
Krok 3. Uzyskaj lokalizację 2 godziny po rozpoczęciu trasy
Rozważmy typowy przypadek, w którym kierowca chce znaleźć restauracje nie na początku trasy, ale w dalszej jej części. W naszym przykładzie przejazd z Londynu do Manchesteru trwa około 4 godzin. Kierowca chce znaleźć restaurację oddaloną o 2 godziny jazdy od miejsca, w którym się znajduje. W tym przypadku otrzymamy czas trwania 120 minut * 60 sekund = 7200 sekund.
W odpowiedzi interfejsu Routes API podajemy czas trwania każdego odcinka trasy i każdego kroku odcinka. W masce pola w żądaniu uwzględnij pole „legs”. Powtarzaj kroki, aż łączny czas trwania osiągnie limit 2 godzin lub 7200 sekund. Następnie znaleźliśmy odcinek i krok, które należy ustawić jako początek prośby o SAR.
Aby przyspieszyć pracę, możesz wypróbować bibliotekę polilinii dla Pythona. Możesz go użyć, aby uzyskać współrzędne z pola danych polyline.endodedPolyline.
Uruchom w terminalu środowiska te polecenia.
> 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
Teraz, gdy znaleźliśmy na trasie lokalizację, która znajduje się 2 godziny od początku podróży, możemy użyć jej w żądaniu. Wystarczy dodać szerokość i długość geograficzną w parametrze „origin”, który z kolei jest częścią parametru „routingParameters”. Zalecane jest pole danych „routingSummaries”, o którym wspominaliśmy wcześniej. Możesz też dodać dodatkowe parametry, takie jak tryb podróży i instrukcje dotyczące unikania opłat.
"routingParameters": {
"origin": {
"latitude": xx.xxxx,
"longitude": yy.yyyy
},
"travelMode":"DRIVE",
"routeModifiers": {
"avoidTolls": true
}
}
Przykładowe wyniki (ikona samochodu została dodana, aby pokazać źródło wyszukiwania).
Jak widać na ilustracji, interfejs API zwraca miejsca, które są bardziej związane z końcem trasy. Wyniki zaczynają się mniej więcej w połowie podróży. Wyszukiwanie nadal wykorzystuje te same dane z Google Maps Platform, które uwzględniają m.in. trafność miejsca i odległość.
Podsumowanie
Z tego samouczka dowiesz się, jak połączyć 2 interfejsy API Google Maps Platform – Routes i Places – aby zaplanować podróż i znaleźć miejsca, w których można zjeść po 2 godzinach od rozpoczęcia podróży. Aby uzyskać najlepsze wyniki, musisz wykonać te czynności: pobrać zakodowaną linię łamaną zawierającą współrzędne geograficzne (szerokość i długość) każdego etapu trasy oraz ustawić punkt początkowy żądania wyszukiwania wzdłuż trasy.
Ta funkcja to nowe, zaawansowane narzędzie, które uzupełnia dostępne już w interfejsie Places API wyszukiwanie tekstowe i wyszukiwanie w pobliżu. Logiczne byłoby dodanie usług lokalizacyjnych, aby można było używać lokalizacji kierowcy jako punktu wyjścia do znalezienia optymalnego źródła wyszukiwania. Poza tym ta funkcja będzie doskonale współpracować z asystentem głosowym w samochodzie, któremu możesz podać preferowane opcje posiłków.
Dalsze działania
- Wypróbuj przykłady w dokumentacji.
- Prześlij opinię
Sugerowane materiały dodatkowe:
Twórcy
Ten dokument jest utrzymywany przez Google. Autorem tego artykułu jest:
Główny autor: Mikko Toivanen | Inżynier rozwiązań Google Maps Platform