احتساب ملخّص المسار

لاستخدام البحث النصي (الجديد) أو البحث في الجوار (الجديد) لحساب مدة الرحلة والمسافة إلى كل مكان في الردّ:

1. مرِّر المَعلمة routingParameters.origin في الطلب لتحديد إحداثيات خطوط العرض والطول لنقطة انطلاق المسار. هذه المَعلمة مطلوبة لحساب المدة والمسافة لكل مكان في الاستجابة.

2. يجب تضمين routingSummaries في قناع الحقل لكي يتضمّن الردّ مصفوفة routingSummaries. تحتوي هذه المصفوفة على المدة والمسافة من نقطة انطلاق المسار إلى كل مكان في الردّ.

تتيح لك أداة "مستكشف واجهات برمجة التطبيقات" إرسال طلبات مباشرة لتتعرّف على واجهة برمجة التطبيقات وخياراتها:

استخدام خدمة البحث النصي (جديد)

في الطلب التالي، يمكنك احتساب مدة الرحلة والمسافة إلى كل مكان في استجابة "البحث النصي (الجديد)":

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "routingParameters": {
    "origin": {
      "latitude": -33.8688,
      "longitude": 151.1957362
    }
  }
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel,routingSummaries' \
'https://places.googleapis.com/v1/places:searchText'

تحتوي الاستجابة على مصفوفتَي JSON: تحتوي المصفوفة places على الأماكن المطابقة، وتحتوي المصفوفة routingSummaries على المدة والمسافة للانتقال إلى كل مكان:

{
  "places": [
    {
      object (Place)
    }
  ]
  "routingSummaries": [
    {
      object (RoutingSummary)
    }
}

يكون كل عنصر في مصفوفة routingSummaries في موضع المصفوفة المقابل للمكان في مصفوفة places. أي أنّ العنصر في routingSummaries[0] يتجاوب مع المكان في places[0].

طول مصفوفة routingSummaries هو نفسه طول مصفوفة places. في حال عدم توفّر routingSummary لمكان معيّن، يكون إدخال الصفيف فارغًا.

بما أنّ هذا المثال يحسب المدة والمسافة من نقطة انطلاق المسار إلى كل مكان، يحتوي الحقل routingSummaries.legs في الردّ على عنصر Leg واحد يتضمّن duration وdistanceMeters من نقطة انطلاق المسار إلى المكان.

{
  "places": [
    {
      "formattedAddress": "1, Westfield Sydney Central Plaza, 450 George St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Gözleme King Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    …
  ]
  "routingSummaries": [
    {
      "legs": [
        {
          "duration": "597s",
          "distanceMeters": 2607
        }
      ],
      "directionsUri": "https://www.google.com/maps/dir/-33.8688,151.1957362/''/data=!4m6!4m5!1m0!1m2!1m1!1s0x6b12ae3fa97cd745:0x6aecf365bf497c08!3e0"
    },
    {
      "legs": [
        {
          "duration": "562s",
          "distanceMeters": 2345
        }
      ],
      "directionsUri": "https://www.google.com/maps/dir/-33.8688,151.1957362/''/data=!4m6!4m5!1m0!1m2!1m1!1s0x6b12ae3da97f60c1:0x845f3273bd764f6c!3e0"
    },
   …
  ]
}

من هذا المثال، يمكنك أن ترى أن المدة والمسافة من نقطة انطلاق المسار إلى المكان الأول في النتائج هي 597 ثانية و2607 متر.

استخدام ميزة "بحث في الجوار"

في هذا المثال، يمكنك حساب مدة الرحلة والمسافة إلى كل مكان في استجابة "البحث في الجوار". يبحث هذا المثال عن مطاعم في سيدني، أستراليا، ويضبط قيود الموقع الجغرافي ونقطة انطلاق المسار على إحداثيات خطوط العرض والطول نفسها:

  curl -X POST -d '{
    "includedTypes": ["restaurant"],
    "maxResultCount": 10,
    "locationRestriction": {
      "circle": {
        "center": {
          "latitude": -33.8688,
          "longitude": 151.1957362},
        "radius": 500.0
      }
    },
    "routingParameters": {
      "origin": {
        "latitude": -33.8688,
        "longitude": 151.1957362
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key:API_KEY" \
  -H "X-Goog-FieldMask: places.displayName,routingSummaries" \
  https://places.googleapis.com/v1/places:searchNearby

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

تحديد خيارات السفر

يتم تلقائيًا احتساب المدة والمسافة لسيارة. ومع ذلك، يمكنك التحكم في نوع السيارة، بالإضافة إلى خيارات أخرى، في البحث.

• استخدِم المَعلمة routingParameters.travelMode لضبط وسيلة النقل على DRIVE أو BICYCLE أو WALK أو TWO_WHEELER. لمزيد من المعلومات حول هذه الخيارات، يُرجى الاطّلاع على أنواع المركبات المتاحة للمسارات.

• استخدِم السمة routingParameters.routingPreference لضبط خيار الإعداد المفضّل للتوجيه على TRAFFIC_UNAWARE (الإعداد التلقائي) أو TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL. يوفّر كل خيار مستويات مختلفة من جودة البيانات ووقت الاستجابة. لمزيد من المعلومات، يُرجى الاطّلاع على تحديد كيفية تضمين بيانات حركة المرور وما إذا كان يجب تضمينها.

  تؤثر السمة routingParameters.routingPreference في الاتجاهات الواردة في حقل directionsUri في النسخة الحصرية (ما قبل التوفر للجمهور العام) لأنّ "خرائط Google" تعرض خيارات حركة المرور عند فتح الرابط.

• استخدِم السمة routingParameters.routeModifiers لتحديد avoidTolls وavoidHighways وavoidFerries وavoidIndoor. للحصول على مزيد من المعلومات حول هذه الخيارات، انظر تحديد ميزات المسار المراد تجنبها.

في المثال التالي، يمكنك تحديد وضع السفر على أنّه DRIVE وتجنُّب الطرق السريعة:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "routingParameters": {
    "origin": {
      "latitude": -33.8688,
      "longitude": 151.1957362
    },
    "travelMode":"DRIVE",
    "routeModifiers": {
      "avoidHighways": true
    }
  }
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel,routingSummaries' \
'https://places.googleapis.com/v1/places:searchText'

جرِّبها الآن.

يتيح لك "مستكشف واجهات برمجة التطبيقات" إرسال نماذج طلبات لكي تتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها.

1. انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.

2. يمكنك تعديل مَعلمات الطلب إذا أردت.

3. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

4. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة ملء الشاشة لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".