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

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

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

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

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

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

في الطلب التالي، يمكنك حساب مدة الرحلة والمسافة إلى كل مكان في الردّ من Text Search (New):

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