البحث على طول المسار باستخدام Places API

يوضّح هذا المستند كيفية العثور على فندق أو مطعم أو محطة وقود على طول مسار مخطَّط له. ستتعرّف على كيفية استخدام Routes API للحصول على خط متعدد الأضلاع للمسار واستخدامه مع طلب البحث على طول المسار (SAR) في Places API. ستتعرّف أيضًا على كيفية الحصول على أفضل النتائج من خلال ضبط نقطة بداية البحث على طول المسار، مثلاً بعد ساعتين من بدء الرحلة.

Routes API

للبحث عن أماكن على طول المسار، سنستخدم واجهة Routes API. بيانات Route من الردّ الذي تقدّمه 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 ميزة "البحث على طول المسار" التي تتيح لك البحث عن أماكن على طول مسار معيّن. لإجراء طلب "بحث على طول الطريق"، عليك تقديم الحد الأدنى من المعلومات التالية:

• قناع الحقل الذي يتم عرض الحقول فيه في الردّ
• مفتاح صالح لواجهة برمجة التطبيقات التي تم تفعيلها في Google Cloud Console
• نص البحث الذي يحدّد الأماكن التي تبحث عنها، مثل "مطعم نباتي يقدم أطباقًا حارة"
• الخط المتعدد الأضلاع المرمّز للمسار، والذي تم استرداده من طلب سابق إلى 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 أيضًا الحقل ملخّصات التوجيه الذي يتضمّن كلاً من المدة والمسافة المطلوب قطعهما. حقل بيانات ملخّصات التوجيه هو عنصر فرعي من جذر الاستجابة، لذا يجب عدم تضمين البادئة "places." في قناع الحقل.

'X-Goog-FieldMask': 'places.displayName,places.formattedAddress,places.priceLevel,routingSummaries'

للحصول على الملخّصات، يجب أيضًا تقديم المَعلمة origin_location الخاصة بعملية البحث، والتي تُستخدم في العمليات الحسابية.

"routingParameters": {
      "origin": {
        "latitude":  -37.8167,
        "longitude": 144.9619
      }
    }

عند تلقّي الردّ، ستظهر فيه فقرة جديدة تتضمّن ملخّص التوجيه يحتوي على مقاطع تتضمّن المدة والمسافة بالأمتار.

"routingSummaries": [
    {
      "legs": [
        {
          "duration": "662s",
          "distanceMeters": 3093
        }
      ]
    },

بعد ذلك، سنلقي نظرة على كيفية تحديد المكان الذي ستبدأ منه البحث على طول المسار.

الخطوة 3: الحصول على الموقع الجغرافي بعد ساعتين من بدء الرحلة

لنفترض حالة استخدام عادية يريد فيها السائق العثور على مطاعم ليست في بداية الطريق، بل في مكان أبعد. في مثالنا، تستغرق الرحلة من لندن إلى مانشستر حوالي 4 ساعات. يريد السائق العثور على مطعم على بعد ساعتين من المسار. يمنحنا هذا الطلب مدة 120 دقيقة * 60 ثانية = 7200 ثانية.

في استجابة 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
    }
  }

أمثلة على النتائج (تمت إضافة رمز السيارة للإشارة إلى مصدر البحث)

كما هو موضّح في الصورة، تعرض واجهة برمجة التطبيقات أماكن منحازة إلى نهاية المسار، أي نتائج تبدأ في منتصف الرحلة تقريبًا. يستند البحث إلى بيانات Google Maps Platform نفسها التي تأخذ في الاعتبار مدى صلة المكان بطلب البحث والمسافة بين الأماكن، بالإضافة إلى عوامل أخرى.

الخاتمة

في هذا البرنامج التعليمي، تعلّمنا كيفية الجمع بين واجهتَي برمجة التطبيقات Routes وPlaces من "منصة خرائط Google" للتخطيط لرحلة والعثور على أماكن لتناول الطعام بعد ساعتين من بدء الرحلة. تتضمّن الخطوات اللازمة الحصول على خطوط متعدّدة مشفّرة تحتوي على إحداثيات خطوط الطول والعرض لكل خطوة من الرحلة، وتحديد مصدر طلب "البحث أثناء التنقّل" للحصول على أفضل النتائج.

تضيف هذه الميزة أداة جديدة وفعّالة إلى ميزتَي البحث النصي والبحث في الأماكن القريبة المتوفّرتَين حاليًا في Places API. والخطوة المنطقية التالية هي إضافة خدمات الموقع الجغرافي حتى تتمكّن من استخدام موقع السائق كنقطة بداية للعثور على أفضل مصدر للبحث. بالإضافة إلى ذلك، ستعمل هذه الميزة بشكل مثالي مع مساعد صوتي داخل السيارة يمكنك من خلاله التعبير عن خياراتك المفضّلة لتناول الطعام.

الإجراءات التالية

• تجربة الأمثلة في المستندات
• تقديم ملاحظات:

محتوى إضافي للقراءة:

• أداة فك ترميز الخطوط المتعددة المشفّرة
• Routes API

المساهمون

تتولّى Google صيانة هذا المستند. كتب المساهم التالي هذا المحتوى في الأصل.

المؤلف الرئيسي: ميكو تويفانن | مهندس حلول في "منصة خرائط Google"