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

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

1. نقْل المَعلمة RoutingParameters في الطلب، باستخدام setOrigin() لتحديد إحداثيات خط العرض وخط الطول لنقطة بدء مسار التوجيه هذه المَعلمة مطلوبة لاحتساب المدة والمسافة إلى كل مكان في الاستجابة.

2. عند إنشاء عنصر الطلب، أضِف .setRoutingSummariesIncluded(true).

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

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the routing parameters object and pass the routing origin.
RoutingParameters routingParameters = RoutingParameters.builder()
    .setOrigin(toLatLng("-33.8688, 151.1957362"))
    .build();

// Use the builder to create a SearchByTextRequest object and pass the routing parameters.
// Set setRoutingSummariesIncluded to true.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food in Sydney, Australia", placeFields)
    .setMaxResultCount(10)
    .setRoutingParameters(routingParameters)
    .setRoutingSummariesIncluded(true)
    .build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned Lists of Place objects, RoutingSummary objects, and Leg objects.
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
      List<RoutingSummary> routingSummaries = response.getRoutingSummaries();
      List<Leg> legs = routingSummaries.get(0).getLegs();
      Duration duration = legs.get(0).getDuration();
    });

تمثّل فئة SearchByTextResponse الاستجابة من طلب بحث. يمكنك الاتصال بالرقم SearchByTextResponse.getRoutingSummaries() لعرض قائمة ملخّصات التوجيه. يحتوي عنصر SearchByTextResponse أيضًا على:

• قائمة بعناصر Place التي تمثّل جميع الأماكن المطابقة، مع عنصر Place واحد لكل مكان مطابق
• لا يحتوي كل عنصر Place إلا على الحقول التي تحدّدها قائمة الحقول التي تم تمريرها في الطلب.

ملاحظة: لا يحتوي الردّ إلا على duration و distanceMeters لكل مكان. ولا يحتوي على المسار الفعلي نفسه. لحساب المسار، استخدِم Routes API، التي تشير إلى نقطة انطلاق مكان الوجهة وموقعه الجغرافي.

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

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 500 meter diameter circle in Sydney, Australia.
LatLng center = new LatLng(-33.8688, 151.1957362);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 500);

// Define the routing parameters object and pass the routing origin.
RoutingParameters routingParameters = RoutingParameters.builder()
    .setOrigin(toLatLng("-33.8688, 151.1957362"))
    .build();

// Use the builder to create a SearchNearbyRequest object and pass the routing parameters.
// Set setRoutingSummariesIncluded to true.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setMaxResultCount(10)
    .setRoutingParameters(routingParameters)
    .setRoutingSummariesIncluded(true)
    .build();

// Call PlacesClient.searchNearby() to perform the search.
// Define a response handler to process the returned Lists of Place objects, RoutingSummary objects, and Leg objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
      List<RoutingSummary> routingSummaries = response.getRoutingSummaries();
      List<Leg> legs = routingSummaries.get(0).getLegs();
      Duration duration = legs.get(0).getDuration();
    });

تمثّل الفئة SearchNearbyResponse الردّ الوارد من طلب بحث. يمكنك الاتصال بـ SearchNearbyResponse.getRoutingSummaries() لعرض قائمة ملخصات التوجيه. يحتوي عنصر SearchNearbyResponse أيضًا على:

• قائمة بكائن Place تمثّل جميع الأماكن المطابقة، مع كائن Place واحد لكل مكان مطابق
• لا يحتوي كل عنصر Place إلا على الحقول التي تحدّدها قائمة الحقول التي تم تمريرها في الطلب.

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

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

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

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

  ملاحظة: تتيح واجهة برمجة التطبيقات Routes API أيضًا وضع TRANSIT، ولكن لا تتيح واجهة برمجة التطبيقات Places API هذا الوضع.
  ملاحظة: لا يتوفّر خيار TWO_WHEELER إلا في البلدان المدرَجة في البلدان والمناطق التي تتوفّر فيها المركبات المزوّدة بالدراجتين.
• استخدِم routingParameters.setRoutingPreference() لضبط خيار توجيه المحتوى على TRAFFIC_UNAWARE (الإعداد التلقائي) أو TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL. يختلف كل خيار في مستويات جودة البيانات ووقت الاستجابة. لمزيد من المعلومات، اطّلِع على تحديد كيفية تضمين بيانات عدد الزيارات وما إذا كان سيتم تضمينها.
• استخدِم routingParameters.setRouteModifiers() لتحديد avoidTolls وavoidHighways وavoidFerries وavoidIndoor. لمزيد من المعلومات حول هذه الخيارات، يُرجى الاطّلاع على القسم تحديد ميزات المسارات التي يجب تجنُّبها.

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the routing modifiers object.
RouteModifiers routeModifiers = RouteModifiers.builder()
    .setAvoidHighways(true)
    .build();

// Define the routing parameters object and pass the routing origin.
RoutingParameters routingParameters = RoutingParameters.builder()
    .setOrigin(toLatLng("-33.8688, 151.1957362"))
    .setTravelMode(DRIVE)
    .setRouteModifiers(routeModifiers)
    .build();

// Use the builder to create a SearchByTextRequest object and pass the routing parameters.
// Set setRoutingSummariesIncluded to true.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food in Sydney, Australia", placeFields)
    .setMaxResultCount(10)
    .setRoutingParameters(routingParameters)
    .setRoutingSummariesIncluded(true)
    .build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned Lists of Place objects, RoutingSummary objects, and Leg objects.
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
      List<RoutingSummary> routingSummaries = result.getRoutingSummaries();
      List<Leg> legs = routingSummaries.get(0).getLegs();
      Duration duration = legs.get(0).getDuration();
    });