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

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

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 في موضع الصفيف الم corresponding قابل للمكان في صفيف 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'