احتساب ملخّص التوجيه

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

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. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".