このドキュメントでは、計画したルート沿いのホテル、レストラン、ガソリン スタンドを見つける方法について説明します。Routes API を使用してルート ポリラインを取得し、Places API の Search Along Route（SAR）リクエストで使用する方法を学びます。また、ルート沿いの検索元（たとえば、ルートの 2 時間後）を設定して最良の結果を得る方法についても学びます。
Routes API
ルート沿いの場所を検索するには、Routes API を使用します。Routes API レスポンスのルートデータは、出発地から目的地までの一連の LatLong 座標です。ルートデータには、道路網に沿った経路とステップが含まれています。
ルートは、エンコードされたポリラインとして返されます。これは、SAR リクエストに入力パラメータとして渡します。ポリラインのエンコードとは、一連の座標を単一文字列として保存できる非可逆圧縮アルゴリズムです。Routes API からポリラインを取得することは必須ではありません。データを自分で作成することもできますが、この例では、Routes API を使用して必要なデータをすばやく確実に取得します。
このチュートリアルでは、ロンドン（-37.8167,144.9619）からマンチェスター（-37.8155, 144.9663）までのルートを使用します。
例の経路: ロンドンからマンチェスター
ステップ 1: Routes API からルートを取得する
Routes API からルートを取得するには、次の情報を指定する必要があります。
- 出発地と目的地
- 移動手段（運転、徒歩など）
- 任意のウェイポイント（省略可）
- 設定（有料道路を避ける、高速道路を避けるなど）
- トラフィック認識ルーティングを使用すると、最も正確な推定値が得られます。ただし、計算負荷が大きいため、レスポンスのレイテンシが増加します。
{"origin":{
"location": {
"latLng":{
"latitude": -37.8167,
"longitude": 144.9619
}
}
},
"destination":{
"location": {
"latLng":{
"latitude":-37.8155,
"longitude": 144.9663
}
}
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
呼び出しを行う際は、ヘッダー フィールド マスクに「encodedPolyline」フィールドを含めてください。
headers = {
"Content-Type": "application/json",
"X-Goog-FieldMask": "routes.distanceMeters,routes.duration,routes.legs,routes.polyline.encodedPolyline"
}
ルートを取得する方法とルート ポリラインを取得する方法の例を含む完全なドキュメント。
リクエストでこれらの情報を指定すると、Routes API からルート オブジェクトが返されます。ルート オブジェクトには次の情報が含まれます。
- ルートの合計距離
- ルートの合計時間
- ルートの区間とステップ
- ルート、区間、ステップのエンコードされたポリライン。
{
"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
ステップ 2: ルート沿いの検索リクエスト
Places API のテキスト検索には、ルート沿いの場所を検索できる Search Along Route リクエストがあります。ルート沿いの検索リクエストを行うには、次の最小情報を指定する必要があります。
- レスポンスで返されるフィールドのフィールド マスク
- Google Cloud コンソールで有効になっている API の有効な API キー
- 検索対象の場所を示す検索テキスト文字列（「スパイシーなベジタリアン レストラン」など）
- 前の Routes API 呼び出しから取得した、ルートのエンコードされたポリライン
- Places Text Search API エンドポイントの URL
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)
リクエストデータの例
Search Along Route リクエストは、ルート沿いにある場所のリストを返します。以下に、サンプルデータの一部を示します。レスポンスの長さは、結果パラメータの最大数を設定することで制限できます。もちろん、フィールドを追加すると、受信するデータの量は増加します。Places API レスポンスの詳細については、ドキュメントをご覧ください。
{
"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"
}
},
レスポンス データの例
ルーティングの概要と迂回経路の所要時間
場所を特定するだけでも便利ですが、これらの場所までの所要時間の情報も追加すると便利です。Places API テキスト検索の SAR は、所要時間と移動距離の両方を含むルーティングの概要フィールドを返すこともできます。ルーティング サマリー データ フィールドはレスポンス ルートの子であるため、フィールド マスクに「places.」接頭辞を含めることはできません。
'X-Goog-FieldMask': 'places.displayName,places.formattedAddress,places.priceLevel,routingSummaries'
概要を取得するには、計算に使用する検索の開始地点パラメータも指定する必要があります。
"routingParameters": {
"origin": {
"latitude": -37.8167,
"longitude": 144.9619
}
}
レスポンスには、ルーティングの概要という新しいセクションが追加され、経路（所要時間と距離（メートル）を含む）が含まれます。
"routingSummaries": [
{
"legs": [
{
"duration": "662s",
"distanceMeters": 3093
}
]
},
次に、ルートのどの場所で検索を開始するかを定義する方法について説明します。
ステップ 3: ルートから 2 時間先の位置情報を取得する
ドライバーがルートの始点ではなく、さらに先のレストランを探すという一般的なユースケースについて考えてみましょう。この例では、ロンドンからマンチェスターまでの所要時間は約 4 時間です。ドライバーは、ルートから 2 時間ほど離れたレストランを探しています。このリクエストにより、120 分 * 60 秒 = 7,200 秒の時間が取得されます。
Routes API レスポンスには、ルートの各区間と区間の各ステップの所要時間が含まれます。リクエストのフィールド マスクに「legs」フィールドを含めるようにしてください。累積時間が 2 時間または 7,200 秒の制限に達するまで、レグとステップをループします。次に、SAR リクエストの送信元として設定する区間とステップを見つけます。
作業を効率化するには、Python 用の polyline ライブラリを試してみることをおすすめします。これを使用して、polyline.endodedPolyline データフィールドから座標を取得できます。
環境のターミナルで次のコマンドを実行します。
> 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
ルート上の 2 時間目の場所を見つけたので、それをリクエストで使用できます。緯度と経度は「origin」パラメータに追加します。このパラメータは「routingParameters」パラメータの一部です。前述の「routingSummaries」データフィールドを使用することをおすすめします。必要に応じて、移動モードや有料道路を回避する手順などの追加パラメータを追加することもできます。
"routingParameters": {
"origin": {
"latitude": xx.xxxx,
"longitude": yy.yyyy
},
"travelMode":"DRIVE",
"routeModifiers": {
"avoidTolls": true
}
}
検索結果の例（検索元を示す車のアイコンが追加されています）。
画像に示すように、API はルートの終点に偏った場所を返します。結果はルートの中間あたりから始まります。検索は、場所の関連性や距離などの要素を考慮した、同じ Google Maps Platform データに基づいて行われます。
まとめ
このチュートリアルでは、2 つの Google Maps Platform API（ルート API とプレイス API）を組み合わせて、ルートを計画し、2 時間の運転後に食事ができる場所を検索する方法を学習しました。必要な手順は、経路の各ステップの緯度と経度の座標を含むエンコードされたポリラインを取得し、最適な結果を得るためにルート検索リクエストの起点を設定することです。
この機能により、Places API で利用可能な既存のテキスト検索と周辺検索に、強力な新しいツールが追加されます。次に、位置情報サービスを追加して、最適な検索元を探す際の開始点としてドライバーの位置情報を使用できるようにします。また、この機能は、車載の音声アシスタントと連携して、希望する食事オプションを音声で伝えることができます。
次のアクション
- ドキュメントのサンプルをお試しください。
- フィードバックを送信します。
おすすめの参考書籍:
寄与者
このドキュメントは Google が管理します。以下のコントリビューターが最初に作成しました。
主な作成者: Mikko Toivanen | Google Maps Platform ソリューション エンジニア