חיפוש רכבים

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

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

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

שימוש בשיטה 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 נדרש. 'בלעדית' (נסיעה פעילה אחת בכל רגע נתון לכל נהג) או 'משותפת' (נסיעה אחת או כמה נסיעות בכל רגע נתון לכל נהג).
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, המרחק בקו ישר (לא במסלול) בין הרכב לנקודת האיסוף.
count נדרש. המספר המקסימלי של כלי רכב להחזרה הוא 1 עד 50.
סינון אופציונלי. שאילתת סינון שחלה במהלך חיפוש כלי רכב.

כדי לראות את הקבוצה המלאה של השדות של 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

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

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.

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