חיפוש רכבים

כחלק משירות הנסיעות לפי דרישה, אתם יכולים למצוא כלי רכב בקרבת מקום באמצעות השיטה SearchVehicles.

השיטה SearchVehicles מאפשרת לכם למצוא כלי רכב זמינים בקרבת מקום באפליקציה לנייד לצרכנים, שהכי מתאימים לנסיעה ספציפית או לבקשת משלוח. ‫SearchVehicles API מחזיר רשימה מדורגת של כלי רכב שהמאפיינים שלהם תואמים למאפייני הנסיעה המבוקשים. הדירוג מוצג לפי הבחירה שלכם: זמן הגעה משוער, מרחק או מרחק בקו ישר מנקודת האיסוף.

מאפייני חיפוש מאפייני הרכב
  • נקודות איסוף והורדה
  • סוגי כלי רכב ונסיעות שנדרשים
  • הקיבולת הנדרשת
  • מאפייני התאמה נדרשים אחרים
  • המיקום הידוע האחרון של רכב
  • מצב הרכב, הסוג או הקיבולת
  • מאפיינים מותאמים אישית אחרים

שימוש בשיטת SearchVehicles

כדי להשתמש ב-SearchVehicles, פועלים לפי התהליך הכללי הזה:

  1. יוצרים SearchVehiclesRequest על סמך הנסיעה שרוצים להקצות.
  2. קוראים ל-API‏ SearchVehicles (vehicleService.searchVehicles) עם הבקשה שנוצרה.
  3. מעבדים את SearchVehicleResponse שמוחזר מה-API.

שדות בבקשה SearchVehiclesRequest

כדי ליצור SearchVehiclesRequest, צריך להשתמש בשדות החובה הבאים של המאפיינים:

שדה תיאור
הורה נדרש. חייב להיות בפורמט providers/{provider}. הספק צריך להיות מזהה הפרויקט של פרויקט Google Cloud שחשבון השירות שמבצע את הקריאה הזו הוא חבר בו.
vehicle_types נדרש. סוגי כלי הרכב המבוקשים: AUTO,‏ TWO_WHEELER,‏ TAXI,‏ TRUCK,‏ BICYCLE או PEDESTRIAN.
trip_types נדרש. אפשרות EXCLUSIVE (נסיעה פעילה אחת בכל פעם לכל נהג) או SHARED (נסיעה אחת או יותר בכל פעם לכל נהג).
minimum_capacity נדרש. הקיבולת המינימלית שנותרה ברכב לנסיעה חדשה, לנוסעים או למשלוחים.
pickup_point נדרש. מיקום האיסוף של הנסיעה בקואורדינטות של קו רוחב/אורך.
dropoff_point אופציונלי. מיקום ההורדה של הנסיעה בקואורדינטות של קו רוחב/אורך. השדה נדרש אם הערך של trip_types מכיל TripType.SHARED.
pickup_radius_meters נדרש. רדיוס אזור החיפוש של הרכב במטרים מנקודת האיסוף.
order_by נדרש. ממיינים את כלי הרכב לפי אחת מהאפשרויות הבאות:
  • PICKUP_POINT_ETA, זמן ההגעה המשוער של הרכב לנקודת האיסוף.
  • ‫PICKUP_POINT_DISTANCE, המרחק בין הרכב לנקודת האיסוף.
  • ‫DROPOFF_POINT_ETA, זמן ההגעה המשוער של הרכב לסיום הנסיעה בנקודת ההורדה.
  • ‫PICKUP_POINT_STRAIGHT_DISTANCE, המרחק בקו ישר (לא במסלול) בין הרכב לנקודת האיסוף.
ספירה נדרש. מספר כלי הרכב המקסימלי שיוחזר, מ-1 עד 50.
סינון אופציונלי. שאילתת סינון להחלה כשמחפשים כלי רכב.
maximum_staleness אופציונלי. החיפוש מוגבל רק לכלי רכב ששלחו עדכוני מיקום ל-Fleet Engine בפרק הזמן שצוין. אם השדה הזה לא מוגדר, השרת משתמש בערך ברירת המחדל של חמש דקות.

במאמרי העזרה בנושא SearchVehicleRequest מפורטים כל השדות.

תרחישים של SearchVehiclesRequest

בקטע הזה מוצגות דוגמאות לאופן שבו אפשר ליצור SearchVehiclesRequest.

לדוגמה, נניח שלקוח רוצה שיאספו אותו ממסעדה X, ויש לכם ארבעה כלי רכב:

  • רכב 1: במרחק 3,500 מטר ממסעדה X.
  • רכב 2: נמצא במרחק של 100 מטר ממסעדת X, בנסיעה פעילה עם איסוף והורדה במיקומים א' וב'.
  • רכב 3: נמצא במרחק 200 מטר ממסעדת X, ויש לו עוד עצירה אחת רחוקה מאוד.
  • רכב 4: נמצא במרחק של 1,000 מטר ממסעדת X.

בהמשך מוצגות בקשות שונות לפי הרכב שהן מחזירות.

החזרת רכב 4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA

מחזירה את רכבים 3 ו-4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled

הפונקציה מחזירה את הרכבים 2, 3 ו-4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL

שדות של SearchVehiclesResponse

‫SearchVehiclesResponse: רשימה של VehicleMatch ישויות, מדורגות לפי מאפיין order_by שצוין ב-SearchVehiclesRequest. לכל ישות VehicleMatch יש את השדות הבאים:

שדה תיאור
כלי רכב אובייקט Vehicle, כולל המאפיינים vehicle_id [מזהה_רכב] ו-Vehicle.
vehicle_pickup_eta הזמן המשוער להגעה של הרכב למיקום האיסוף, אם הנסיעה הזו תשויך לרכב כרגע.
vehicle_pickup_distance_meter המרחק במטרים בין הרכב לבין מיקום האיסוף של הנסיעה החדשה.
vehicle_pickup_straight_line_distance_meter המרחק בקו ישר במטרים בין הרכב לבין מיקום האיסוף של הנסיעה החדשה.
vehicle_dropoff_eta הזמן המשוער להגעה של הרכב למיקום המסירה, אם הנסיעה הזו תשויך לרכב כרגע.
vehicle_trips_waypoints רשימה של נקודות ציון שנותרו, כולל נקודות איסוף והורדה, לנסיעות הפעילות שמשויכות כרגע לרכב.
vehicle_match_type סוג הנסיעה של הרכב: EXCLUSIVE,‏ BACK_TO_BACK,‏ CARPOOL או CARPOOL_BACK_TO_BACK.

VehicleMatchלרשימה מלאה של שדות

שימוש בשאילתות סינון

ב-SearchVehicles וב-ListVehicles אפשר לסנן לפי מאפייני רכב באמצעות שאילתת סינון.

שאילתות סינון תומכות רק בסינון לפי מאפיינים מותאמים אישית של כלי רכב, ואי אפשר להשתמש בהן בשדות אחרים. כשמשתמשים בשאילתת הסינון בחיפוש שכולל קריטריונים אחרים של שדות, כמו minimum_capacity או vehicle_types, היא פועלת כתנאי AND.

לדוגמה, אם מחפשים רכב עם קיבולת מינימלית של 6 נוסעים ומסננים לפי קריטריון attributes כמו 'מתאים לחיות מחמד', יופיעו רק כלי רכב שמתאימים לחיות מחמד ויכולים להסיע לפחות 6 נוסעים.

דוגמאות לתחביר של שאילתות סינון מופיעות ב-AIP-160. פרטים על יצירת מאפייני רכב מופיעים במאמר שדה מאפייני רכב במדריך עדכון שדות של רכב.

דוגמה לשימוש בשיטה SearchVehicles

בדוגמה הבאה מוצג שימוש ב-SearchVehicles API באמצעות ספריית Java gRPC. רשימה מלאה של השפות הנתמכות מופיעה במאמר ספריות לקוח לשירותי נסיעות על פי דרישה.

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jkt Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(Category.AUTO).build())
    .setCurrentTripsPresent(CurrentTripsPresent.ANY)
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .build();

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

List<VehicleMatch> vehicleMatches =
    searchVehicleResponse.getMatchesList();

// Each VehicleMatch contains a Vehicle entity and information about the
// distance and ETA to the pickup point and drop-off point.

המאמרים הבאים