البحث على طول المسار باستخدام 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.

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"
      }
    },

مثال على بيانات الاستجابة

ملخّص المسار وأوقات الالتفاف

من الرائع العثور على المواقع الجغرافية فقط، ولكن سيكون من المفيد إضافة معلومات عن الوقت الذي يستغرقه الوصول إلى هذه المواقع الجغرافية. يمكن أن تؤدي ميزة SAR في واجهة برمجة التطبيقات Text Search في Places API إلى عرض حقل ملخّصات المسار الذي يحتوي على كل من المدة والمسافة التي يجب قطعها. حقل بيانات ملفّات تلخيص التوجيه هو حقل فرعي من جذر الاستجابة، لذا يجب عدم تضمين البادئة "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 ثانية = 7200 ثانية.

في ردّ Routes API، تتوفّر مدة كل مرحلة من المسار وكل خطوة من المرحلة. احرص على تضمين الحقل legs في قناع الحقل في طلبك. كرِّر الخطوات إلى أن تصل المدة التراكمية إلى الحد الأقصى الذي يبلغ ساعتَين أو 7200 ثانية. بعد ذلك، عثرنا على القسم و الخطوة المطلوب ضبطهما كمصدر طلب SAR.

لتسريع عملك، ننصحك بتجربة مكتبة polyline لأجل 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" نفسها التي تأخذ في الاعتبار مدى صلة المكان بالموضوع و المسافة بينه وبينك، بالإضافة إلى عوامل أخرى.

الخاتمة

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

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

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

• جرِّب الأمثلة في المستندات.
• تقديم ملاحظات وآراء

مراجع إضافية مقترَحة:

• أداة فك ترميز Polyline
• Routes API

المساهمون

تحتفظ Google بهذا المستند. كتب المساهم التالي هذه المقالة في الأصل.

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