חיפוש לאורך המסלול באמצעות Places API

במאמר הזה מוסבר איך לחפש מלון, מסעדה או תחנת דלק לאורך מסלול מתוכנן. תלמדו איך להשתמש ב-Routes API כדי לקבל קו פוליגון של מסלול, ואיך להשתמש בו עם Places API כדי לשלוח בקשת חיפוש לאורך מסלול (SAR). בנוסף, תלמדו איך להגדיר את נקודת המוצא של החיפוש לאורך המסלול כדי לקבל את התוצאות הטובות ביותר, למשל שעתיים אחרי תחילת הנסיעה.

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 Text Search יש בקשה מסוג Search Along Route שמאפשרת לחפש מקומות לאורך מסלול. כדי לשלוח בקשה לחיפוש לאורך מסלול, צריך לספק לפחות את הפרטים הבאים:

• אנונימיזציה של השדות שמוחזרים בתשובה
• מפתח API תקין עבור ממשק ה-API שהופעל במסוף Google Cloud
• מחפשים מחרוזת טקסט שמציינת את המקומות שאתם מחפשים, למשל: 'מסעדה צמחונית עם אוכל חריף'
• קו הפוליגון המקודד של המסלול, שאוחזר מהקריאה הקודמת ל-Routes API
• כתובת URL של נקודת הקצה של 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)

נתונים לדוגמה של בקשה

הבקשה 'חיפוש לאורך המסלול' תחזיר רשימה של מקומות שנמצאים לאורך המסלול. זוהי דוגמה קצרה של הנתונים. אפשר להגביל את אורך התגובה על ידי הגדרת הפרמטרים של המספר המקסימלי של התוצאות. הוספה של עוד שדות כמובן מגדילה את כמות הנתונים שמתקבלים. מידע נוסף על התגובה של 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 יכול להחזיר שדה routing_summaries שמכיל את משך הנסיעה ואת המרחק. שדה הנתונים של סיכומי הניתוב הוא צאצא של שורש התגובה, ולכן אסור לכלול את הקידומת 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: קבלת מיקום שעתיים לאורך המסלול

נניח שתרצו להשתמש בתרחיש רגיל שבו הנהג רוצה למצוא מסעדות שלא נמצאות בתחילת המסלול, אלא בהמשך הדרך. בדוגמה שלנו, הנסיעה מלונדון למנצ'סטר אורכת כ-4 שעות. הנהג רוצה למצוא מסעדה שעתיים אחרי תחילת הנסיעה. הבקשה הזו מחזירה את משך הזמן של 120 דקות * 60 שניות = 7,200 שניות.

בתגובה של Routes API, יש את משך הזמן של כל חלק במסלול ושל כל שלב בחלק. חשוב לכלול את השדה legs במסכת השדות בבקשה. חוזרים על השלבים עד שהמשך המצטבר מגיע למגבלה של שעתיים או 7,200 שניות. אז מצאנו את הרגל ואת השלב שצריך להגדיר כמקור של בקשת ה-SAR

כדי לזרז את העבודה, כדאי לנסות את ספריית הקו המרובה ל-Python. אפשר להשתמש בו כדי לקבל את הקואורדינטות משדה הנתונים 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

אחרי שמצאנו את המיקום במסלול שנמצא שעתיים אחרי תחילת הנסיעה, אפשר להשתמש בו בבקשה. פשוט מוסיפים את קו הרוחב וקו האורך בפרמטר origin, שהוא חלק מהפרמטר routingParameters. מומלץ להשתמש בשדה הנתונים routingSummaries שתיארנו קודם. אם רוצים, אפשר להוסיף פרמטרים נוספים כמו אמצעי תחבורה והוראות להימנעות מתשלום אגרה.

"routingParameters": {
    "origin": {
      "latitude": xx.xxxx,
      "longitude": yy.yyyy
    },
    "travelMode":"DRIVE",
    "routeModifiers": {
      "avoidTolls": true
    }
  }

תוצאות לדוגמה (סמל המכונית נוסף כדי להראות את מקור החיפוש).

כמו שאפשר לראות בתמונה, ה-API מחזיר מקומות שמוטים לסוף המסלול, והתוצאות מתחילות בערך באמצע הנסיעה. החיפוש עדיין מבוסס על נתונים מהפלטפורמה של מפות Google, שכוללים בין היתר את הרלוונטיות של המקום והמרחק.

סיכום

במדריך הזה למדנו איך לשלב בין שני ממשקי API של Google Maps Platform, ‏ Routes ו-Places, כדי לתכנן טיול ולמצוא מקומות לאכול בהם אחרי שעתיים של נסיעה. כדי לקבל את התוצאות הטובות ביותר, צריך לקבל קו פוליגוני מקודד שמכיל את קואורדינטות קו הרוחב וקו האורך של כל שלב בדרך, ולהגדיר את מקור הבקשה Search Along Route.

התכונה הזו מוסיפה כלי חדש ומתקדם לחיפוש טקסט ולחיפוש בסביבה הקרובה, שכבר זמינים ב-Places API. השלב הבא הוא להוסיף שירותי מיקום כדי להשתמש במיקום הנהג כנקודת התחלה למציאת מקור החיפוש האופטימלי. בנוסף, התכונה הזו תפעל בצורה מושלמת עם עוזר דיגיטלי ברכב, שאליו תוכלו להכתיב את האפשרויות המועדפות עליכם לארוחה.

הפעולות הבאות

• כדאי לנסות את הדוגמאות בתיעוד.
• שליחת משוב.

הצעות לקריאה נוספת:

• כלי עזר לפענוח של קו פוליגוני מקודד
• Routes API

שותפים ביצירת התוכן

‫Google היא זו שמעדכנת את המסמך הזה. הכותב המקורי של המאמר הזה הוא:

הכותב הראשי: Mikko Toivanen | מהנדס פתרונות בפלטפורמה של מפות Google