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

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

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

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

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

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

// 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();
    });