הגדרות GBFS

לפני שממשיכים לקטע הזה, אם עדיין לא עשיתם את זה, צריך לאמת את מערכות המיקרו-מוביליטי הנתמכות שעבורן אתם יוצרים את הפיד.

בקטעים הבאים, כל כותרת היא בפורמט הבא: Required|Optional|Conditionally required: Feed name (System supported). המערכות הבאות נתמכות:

  • מערכת עגינה
  • מערכת ללא תחנות עגינה
  • מערכת עם עמדת עגינה ומערכת ללא עמדת עגינה

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

כותרת חובה בפידים של כלי תחבורה זעירים

פידים של מיקרו-ניידות הם פידים שמכילים נתונים מובְנים של מיקרו-ניידות עם עגינה או ללא עגינה, כפי שמוגדר במאמר הזה.

בכל הפידים צריך תמיד לציין את השדות שמופיעים בטבלה הבאה ברמה העליונה של אובייקט ה-JSON, שנקראים ביחד הכותרת המשותפת של GBFS.

שם השדה סוג דרישה תיאור
last_updated חותמת זמן חובה חותמת זמן של POSIX, שמציינת את מספר השניות מאז 1 בינואר 1970 בשעה 00:00:00 UTC.

התאריך והשעה שבהם עודכנו הנתונים בפיד לאחרונה.
ttl מספר שלם לא שלילי חובה מספר שלם לא שלילי שמייצג את מספר השניות שנותרו עד שהגיע הזמן לעדכן את הפיד.

אם צריך לעדכן את הנתונים בקצב קבוע, מגדירים את הערך הזה ל-0.
data JSON חובה קובץ JSON שמכיל את שדות הנתונים של הפיד הספציפי.

לדוגמה, פיד מצטבר free_bike_status.json עם כותרת GBFS משותפת יכול להיראות כך:

{
    "ttl": 30,
    "last_updated": 1576123774,
    "data": {
        "bikes": [ ... ]  // GBFS free bike status objects.
    }
}

נדרש: system_information.json (מערכת עם עגינה ומערכת ללא עגינה)

אפשר לעיין במפרט GBFS לפי הצורך.

הפיד הזה מספק פרטים לגבי מפעיל המערכת.

שם השדה סוג דרישה תיאור
system_id מזהה חובה מזהה ייחודי גלובלי של מערכת שיתוף כלי רכב. הערך הזה אמור להישאר זהה לאורך חיי המערכת. לכל מערכת נפרדת או אזור גיאוגרפי שבו כלי הרכב פועלים צריך להיות מזהה מערכת משלהם (system_id). מזהי המערכות צריכים להיות ניתנים לזיהוי כשייכים למערכת מסוימת, ולא כמחרוזות אקראיות – לדוגמה, bcycle_austin או biketown_pdx.
name מחרוזת חובה שם המערכת שמוצג ללקוחות.
rental_apps אובייקט חובה אובייקט JSON שמכיל את פרטי אפליקציית ההשכרה ל-Android ול-iOS בשדות המתאימים.
rental_apps.android אובייקט חובה להזין ערך באופן מותנה השדות store_uri ו-discovery_uri מכילים מידע על הורדת אפליקציות להשכרה ועל גילוי אפליקציות בפלטפורמת Android. אם לספק המערכת יש אפליקציה להשכרת מכשירים ל-Android, חובה למלא את השדה הזה.
rental_apps.android.store_uri URI חובה ‫URI שממנו אפשר להוריד את אפליקציית Android להשכרה. בדרך כלל זו כתובת URI לחנות אפליקציות כמו Google Play. אם ה-URI מצביע על חנות אפליקציות כמו Google Play, מומלץ שה-URI יפעל לפי השיטות המומלצות של Android, כדי שאפליקציית הצפייה תוכל לפתוח ישירות את ה-URI לאפליקציית חנות האפליקציות המקורית במקום לאתר.
rental_apps.android.discovery_uri URI חובה מזהה ה-URI בפורמט your_custom_scheme://your/path/here. אפשר להשתמש ב-URI של הסשן כדי לגלות אם אפליקציית Android להשכרה מותקנת במכשיר.PackageManager.queryIntentActivities()
rental_apps.ios אובייקט חובה להזין ערך באופן מותנה השדות store_uri ו-discovery_uri מכילים מידע על הורדת אפליקציות להשכרה ועל גילוי אפליקציות בפלטפורמת iOS. אם לספק המערכת יש אפליקציה להשכרת תוכן ל-iOS, חובה למלא את השדה הזה.
rental_apps.ios.store_uri URI חובה כתובת ה-URI שממנה אפשר להוריד את אפליקציית ההשכרה ל-iOS. בדרך כלל זהו מזהה URI לחנות אפליקציות כמו Apple App Store. אם ה-URI מפנה לחנות אפליקציות כמו חנות האפליקציות של Apple, מומלץ שה-URI יפעל בהתאם לשיטות המומלצות ל-iOS, כדי שאפליקציית הצפייה תוכל לפתוח ישירות את ה-URI לאפליקציית חנות האפליקציות המקורית במקום לאתר.
rental_apps.ios.discovery_uri URI חובה מזהה ה-URI בפורמט your_custom_scheme://. UIApplication canOpenURL: יכולה להשתמש ב-URI כדי לגלות אם אפליקציית ההשכרה ל-iOS מותקנת במכשיר.

חובה: free_bike_status.json (מערכת ללא תחנות עגינה)

אפשר לעיין במפרט GBFS לפי הצורך.

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

שם השדה סוג דרישה תיאור
bikes מערך חובה מערך של אופניים זמינים כרגע שהושבתו, כשכל אופניים הם אובייקט.
bikes[].bike_id מזהה חובה המזהה של האופניים.

כדי להגן על הפרטיות, אפשר לשנות את המזהה למחרוזת רנדומלית אחרי כל נסיעה.
bikes[].lat קו רוחב חובה קו הרוחב של האופניים לפי תקן WGS 84, בפורמט מעלות עשרוני.
bikes[].lon קו אורך חובה קו האורך של האופניים בפורמט מעלות עשרוני WGS 84.
bikes[].is_reserved בוליאני חובה האם האופניים מוזמנים כרגע, באופן הבא:
  • אם האופניים מוזמנים כרגע, מגדירים את הערך true.
  • אם האופניים לא מוזמנים כרגע, מגדירים את הערך false.
bikes[].is_disabled בוליאני חובה האם האופניים מושבתים או מקולקלים כרגע, באופן הבא:
  • אם האופניים מושבתים כרגע, מגדירים את הערך true.
  • אם האופניים לא מושבתים כרגע, מגדירים את הערך false.
bikes[].rental_uris אובייקט חובה אובייקט JSON שמכיל מזהי URI להשכרה ל-Android, ל-iOS ולאינטרנט בשדות המתאימים.
bikes[].rental_uris.android URI חובה להזין ערך באופן מותנה ‫URI שאפשר להעביר לאפליקציה ל-Android באמצעות android.intent.action.VIEW Android intent כדי לתמוך ב קישורי עומק ל-Android. כתובת ה-URL rental_uris שסיפקתם צריכה להיות Android App Links כדי שאפליקציית הצפייה לא תצטרך לנהל באופן ידני את ההפניה של המשתמש לחנות האפליקציות במקרה שהאפליקציה של הספק לא מותקנת אצל המשתמש.

כתובת ה-URI הזו חייבת להיות קישור עמוק שספציפי לאופניים מסוימים, ולא דף השכרה כללי שכולל מידע על יותר מאופניים אחדים. קישור העומק חייב להפנות את המשתמש ישירות לאופניים, בלי להציג לו הנחיות, דפי ביניים או דפי התחברות. צריך לוודא שהמשתמשים יכולים לראות את האופניים גם אם הם אף פעם לא פתחו את האפליקציה.

לא בהכרח צריך לכלול את ה-URI של האופניים bike_id אם לשותף יש אמצעים אחרים לזיהוי האופניים. לדוגמה, אפליקציית השכרת האופניים יכולה להשתמש במזהים אחרים ב-URI כדי לזהות את האופניים באופן ייחודי.

אם לשותף יש אפליקציה להשכרת תוכן ל-Android, חובה למלא את השדה הזה.

.

דוגמה לקישור לאפליקציה ל-Android:

https://www.example.com/app?sid=1234567890&platform=android
bikes[].rental_uris.ios URI חובה להזין ערך באופן מותנה ‫URI שאפשר להשתמש בו ב-iOS כדי להפעיל את אפליקציית השכרת האופניים. מידע נוסף על הנושא הזה זמין במאמר של Apple בנושא סכימות של כתובות URL מותאמות אישית ב-iOS. כתובת ה-URL שציינתם צריכה להיות rental_uris קישורים אוניברסליים ל-iOS, כדי שאפליקציית הצפייה לא תצטרך לנהל באופן ידני את ההפניה של המשתמש לחנות האפליקציות במקרה שהאפליקציה של הספק לא מותקנת אצל המשתמש.

כתובת ה-URI הזו חייבת להיות קישור עמוק שספציפי לאופניים מסוימים, ולא דף השכרה כללי שכולל מידע על יותר מאופניים אחדים. קישור העומק חייב להפנות את המשתמש ישירות לאופניים, בלי להציג לו הנחיות, דפי ביניים או דפי התחברות. צריך לוודא שהמשתמשים יכולים לראות את האופניים גם אם הם אף פעם לא פתחו את האפליקציה.

לא בהכרח צריך לכלול את מזהה האופניים (bike_id) בכתובות ה-URI של האופניים, כל עוד לשותף יש אמצעים אחרים לזיהוי האופניים הרלוונטיים. לדוגמה, אפליקציית השכרת האופניים יכולה להשתמש במזהים אחרים ב-URI כדי לזהות את האופניים באופן ייחודי.

אם לשותף יש אפליקציה להשכרת רכבים ל-iOS, השדה הזה הוא חובה.

דוגמה לקישורים אוניברסליים ל-iOS:

https://www.example.com/app?sid=1234567890&platform=ios

bikes[].rental_uris.web כתובת URL אופציונלי

כתובת URL שאפשר להשתמש בה בדפדפן אינטרנט כדי להציג מידע נוסף על השכרת הרכב הזה.

כתובת ה-URL הזו צריכה להיות קישור עומק ספציפי לאופניים, ולא דף השכרה כללי שכולל מידע על יותר מאופניים אחדים. קישור העומק חייב להפנות את המשתמש ישירות לאופניים, בלי להציג לו הנחיות, דפי ביניים או דפי התחברות. צריך לוודא שהמשתמשים יכולים לראות את האופניים גם אם הם אף פעם לא פתחו את האפליקציה.

כתובות ה-URL לא חייבות לכלול את bike_id לגבי האופניים או לפעול לפי המוסכמות הסמנטיות של כתובות ה-URL להשכרת אופניים ל-Android או ל-iOS. אפשר להשתמש במזהים אחרים בכתובת ה-URL של אפליקציית ההשכרה כדי לזהות באופן ייחודי את האופניים.

אם השדה הזה לא מוגדר, המשמעות היא שדפדפן האינטרנט לא תומך בקישורים עמוקים.

ערך לדוגמה:

https://www.example.com/app?sid=1234567890
bikes[].vehicle_type_id מזהה חובה vehicle_type_id הרכב, כמו שמתואר בקטע vehicle_types.json.
bikes[].pricing_plan_id מזהה חובה מזהה של תוכנית התמחור שחלה כשמשכירים את סוג הרכב הזה, כפי שמתואר בקטע system_pricing_plans.json.
bikes[].current_range_meters מספר נקודה צפה לא שלילי חובה להזין ערך באופן מותנה אם בהגדרה vehicle_type שמתאימה לרכב יש מנוע, השדה הזה הוא חובה.

הערך שמוגדר הוא המרחק המקסימלי במטרים שהרכב יכול לעבור בלי צורך בטעינה או בתדלוק, בהתאם לרמת הטעינה או הדלק הנוכחית של הרכב.
bikes[].last_reported חותמת זמן אופציונלי הערך מוגדר לזמן האחרון שבו הרכב דיווח על הסטטוס שלו לשרת העורפי של המפעיל.

דוגמה ל-free_bike_status.json:

"bikes": [{
    "bike_id": "xyz123",
    "lat": 12.34,
    "lon": 56.78,
    "is_reserved": true,
    "is_disabled": false,
    "rental_uris":{
      "android": "https://www.example.com/app?sid=1234567890&platform=android",
      "ios": "https://www.example.com/app?sid=1234567890&platform=ios",
      "web": "https://www.example.com/app?sid=1234567890"
    },
    "vehicle_type_id": "scooter_electric",
    "pricing_plan_id": "sydneyPlan1",
    "current_range_meters": 4500,
    "last_reported": 1434054678
},
{
    "bike_id": "abc123",
    "lat": 1.34,
    "lon": 146.78,
    "is_reserved": false,
    "is_disabled": true,
    "rental_uris":{
      "android": "https://www.example.com/app?sid=1234567890&platform=android",
      "ios": "https://www.example.com/app?sid=1234567890&platform=ios",
      "web": "https://www.example.com/app?sid=1234567890"
    },
    "vehicle_type_id": "bike_manual",
    "pricing_plan_id": "sydneyPlan1",
    "last_reported": 1434054241
}
]

חובה: vehicle_types.json (מערכת עם עגינה ומערכת ללא עגינה)

אפשר לעיין במפרט GBFS לפי הצורך.

בפיד הזה מוגדרים הפרטים של סוגי רכב ספציפיים, כמו שמופיע בקטע free_bike_status.json.

שם השדה סוג דרישה תיאור
vehicle_types מערך חובה מערך של אובייקטים, שכל אחד מהם מגדיר סוג רכב נפרד בקטלוג של הספק. יכול להיות רק אובייקט אחד לכל סוג רכב.
vehicle_types[].vehicle_type_id מזהה חובה מזהה ייחודי של סוג רכב מסוים.
vehicle_types[].form_factor Enum חובה מספר שמאפיין את גורם הצורה הכללי של הרכב, מתוך רשימת הערכים התקפים הנוכחיים הבאה:
  • bicycle
  • scooter
  • other
vehicle_types[].propulsion_type Enum חובה סוג enum שמייצג את סוג ההנעה הראשי של הרכב, מתוך הרשימה הבאה של ערכים תקפים כרגע:
  • ‫human: הנעה באמצעות דוושה או רגל
  • electric_assist: מספק כוח רק לצד הנעה אנושית
  • ‫electric: מכיל מצב ויסות נתונים עם מנוע שמבוסס על סוללה
  • ‫combustion: מכיל מצב מצערת עם מנוע מופעל על ידי דלק
vehicle_types[].max_range_meters מספר נקודה צפה לא שלילי חובה להזין ערך באופן מותנה אם הערך של propulsion_type לא מוגדר כ-human, הרכב כולל מנוע ולכן השדה הזה הוא חובה.

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

דוגמה ל-vehicle_types.json:

"vehicle_types": [
  {
    "vehicle_type_id": "bike_manual",
    "form_factor": "bicycle",
    "propulsion_type": "human"
  },
  {
    "vehicle_type_id": "scooter_electric",
    "form_factor": "scooter",
    "propulsion_type": "electric",
    "max_range_meters": 10000
  }
]

חובה: system_pricing_plans.json (מערכת ללא תחנות עגינה)

אפשר לעיין במפרט GBFS לפי הצורך.

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

.
שם השדה סוג דרישה תיאור
plans מערך חובה מערך של אובייקטים שכל אחד מהם מגדיר תוכנית תמחור נתונה.
plans[].plan_id מזהה חובה מחרוזת שמייצגת מזהה ייחודי של תוכנית התמחור הנתונה שהספק מציע.
plans[].url כתובת URL אופציונלי כתובת ה-URL שאליה משתמשי הקצה יכולים להיכנס כדי לקבל מידע נוסף על תוכנית המחירים.
plans[].currency מחרוזת חובה תקן ISO 4217 של תוכנית התמחור.
plans[].price מספר נקודה צפה לא שלילי חובה

תוכנית התמחור צריכה להיות מוגדרת כתוכנית תמחור לא מדורגת או כתוכנית תמחור מדורגת:

תוכנית תמחור ללא דירוג

התוכנית הזו היא בתשלום קבוע וחד-פעמי.

מגדירים את השדה הבא:

  • ‫price: המחיר הקבוע של כל הנסיעה.
תוכנית תמחור מדורגת

המינוי הזה הוא בתמחור ליניארי לפי חלקים.

מגדירים את השדה הבא:

  • ‫price: המחיר הבסיסי, שמופיע בחשבון פעם אחת בדיוק לכל נסיעה.

מגדירים אחד מהשדות הבאים או את שניהם:

  • ‫per_km_pricing: מחיר הנסיעה שצוין כמחיר לקילומטר.
  • ‫per_min_pricing: מחיר הנסיעה שצוין בתעריף לדקה.
plans[].per_km_pricing מערך חובה להזין ערך באופן מותנה

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

מערך של אובייקטים שכל אחד מהם מגדיר קטע מסוים של מרחק. הערך start של כל פלח צריך להיות קטן או שווה לערך start של הפלח הבא.

כדי לקבוע את המחיר הכולל של התוכנית שצוינה, צריך להוסיף את הערך של plans[].price של התוכנית שצוינה למחירים המצטברים של הפלחים ב-plans[].per_km_pricing וב-plans[].per_min_pricing.

אם לא מגדירים את השדה הזה, לא יהיו מחירים משתנים לפי מרחק, ולכן הם לא ייכללו במחיר הכולל.
plans[].per_km_pricing[].start מספר שלם לא שלילי חובה מספר הקילומטרים שמעליו מתחילים לחייב את התעריף של הקטע. השדה הזה מוגדר לערך כולל שמתחיל את הטווח של הפלח. לכן, אחרי שעוברים את מספר הקילומטרים, מתבצע חיוב אחד של rate.
plans[].per_km_pricing[].rate מספר ממשי (float) חובה התעריף שבו מחויב כל interval, שמתחיל בstart של הפלח (כולל). אם השדה הזה מוגדר למספר שלילי, הנוסע מקבל הנחה.
plans[].per_km_pricing[].interval מספר שלם לא שלילי חובה

המרווח בקילומטרים שבו הערך rate של הפלח מוחל מחדש ללא הגבלה, אלא אם הערך end של הפלח מוגדר למספר שלם לא שלילי.

ההנחה rate מוחלת מחדש פעם אחת בתחילת כל interval, ולא מתבצע עיגול של המרחק.

אם הערך של end בפלח מוגדר כמספר שלם לא שלילי כלשהו, הערך של rate בפלח יוחל מחדש עד לערך של end בפלח, לא כולל.

אם השדה הזה מוגדר לערך 0, המערכת תחייב את rate בדיוק פעם אחת בstart של הקטע.
plans[].per_km_pricing[].end מספר שלם לא שלילי אופציונלי

מספר הקילומטרים שבהם rate לא חל יותר על הפלח. הערך בשדה הזה הוא הערך הבלעדי שמסיים את הטווח של הפלח. לדוגמה, אם הערך של end הוא 40, ההגדרה rate לא חלה יותר במרחק של 40 קילומטרים.

אם השדה הזה לא מוגדר או שהוא ריק, מחויב rate עבור פלח הנסיעה עד לסיום הנסיעה, בנוסף לכל פלח נוסף שמוגדר אחריו.
plans[].per_min_pricing מערך חובה להזין ערך באופן מותנה

אם המחיר הוא פונקציה של הזמן שחלף, שמוצג בדקות, אז השדה הזה הוא שדה חובה.

מערך של אובייקטים שכל אחד מהם מגדיר פלח נתון שמחולק לפי זמן. הערך start של כל פלח צריך להיות קטן מהערך start של הפלח הבא או שווה לו.

כדי לקבוע את המחיר הכולל של התוכנית שצוינה, צריך להוסיף את הערך של plans[].price של התוכנית שצוינה למחירים המצטברים של הפלחים ב-plans[].per_km_pricing וב-plans[].per_min_pricing.

אם לא מגדירים את השדה הזה, לא יהיו מחירים משתנים על סמך זמן, ולכן לא ייכללו מחירים כאלה כחלק מהמחיר הכולל.
plans[].per_min_pricing[].start מספר ממשי (float) חובה מספר הדקות שמעבר לו מתחילים לחייב על השימוש בפלח. השדה הזה מוגדר לערך כולל שמתחיל את הטווח של הפלח. לכן, אחרי שיחלפו מספר הדקות שהוגדר, יחויב rate פעם אחת.
plans[].per_min_pricing[].rate מספר ממשי (float) חובה השיעור שבו מחויב כל interval. השיעור מתחיל ב-start של הפלח, כולל. אם השדה הזה מוגדר למספר שלילי, הנוסע מקבל הנחה.
plans[].per_min_pricing[].interval מספר שלם לא שלילי חובה

המרווח בדקות שבו rate של הפלח מוחל מחדש ללא הגבלה, אלא אם end של הפלח מוגדר למספר שלם לא שלילי כלשהו.

ההנחה rate מוחלת פעם אחת בתחילת כל interval, ולא מתבצע עיגול של זמן הנסיעה.

אם הערך של end בפלח מוגדר כמספר שלם לא שלילי כלשהו, הערך של rate בפלח יוחל מחדש עד לערך של end בפלח, לא כולל.

אם השדה הזה מוגדר לערך 0, המערכת תחייב את rate בדיוק פעם אחת בstart של הקטע.
plans[].per_min_pricing[].end מספר שלם לא שלילי אופציונלי

מספר הדקות שעד אליהן הפלח rate לא יחול. הערך בשדה הזה הוא הערך הבלעדי שמסיים את הטווח של הפלח. לדוגמה, אם end מוגדר ל-20, ההגדרה rate כבר לא חלה אחרי 20 דקות.

אם השדה הזה לא מוגדר או שהוא ריק, מחיר הפלח rate יחויב עד לסיום הנסיעה, בנוסף לכל פלח נוסף שיבוא אחריו.

דוגמאות לשימוש בקובץ system_pricing_plans.json

בקטע הזה מופיעות system_pricing_plans.json דוגמאות קוד שימושיות. בנוסף, מסופקים פרטים רלוונטיים ותוצאות של כל דוגמה.

דוגמה 1 לקובץ system_pricing_plans.json

בדוגמה הבאה של קוד תוכנית מחירים מוצגים חיובים על סמך משך הנסיעה במרווחי הזמן הבאים:

  • ‫[0,1): ‎2 USD
    • אם הנסיעה נמשכת פחות מדקה, המשתמש משלם 2$.
    • דוגמה: נסיעה של 59 שניות
  • ‫[1,2): $3 USD
    • אם הנסיעה נמשכת דקה אחת או יותר, אבל פחות משתי דקות, המשתמש משלם 2 $+ 1 $= 3$.
    • דוגמאות: נסיעה של דקה אחת, נסיעה של דקה ו-45 שניות
  • x מספר הדקות שבהן x גדול מ-2 או שווה לו: $3 + (($2 + $1) * (x - 2 + 1)) USD
    • אם הנסיעה נמשכת שתי דקות או יותר, המשתמש משלם 3 $על החלק של הנסיעה שנמשך פחות משתי דקות, ו-‎ ($1 [המשך מהפריט הראשון ברשימה per_min_pricing] + $2 [הפריט השני ברשימה per_min_pricing])‎ על כל דקה אחרי שתי הדקות כולל.
    • דוגמאות:
      • עלות הנסיעה למשך 2 דקות היא 3 $+ (2$ + 1$) = 6$
      • עלות הנסיעה של 2 דקות ו-30 שניות היא ‎ $3 + ($2 + $1) = $6 USD
      • עלות נסיעה של 3 דקות: 3 $+ ((2$ + 1$) * 2) = 9$
      • עלות נסיעה של 10 דקות: 3 $+ ‏ ((2$ + 1$) * 9) = 30$
{
  "plans": {
    "plan_id": "plan1",
    "currency": "USD",
    "price": 2,
    "per_min_pricing": [
      {
          "interval": 1,
          "rate": 1,
          "start": 1
      },
      {
          "interval": 1,
          "rate": 2,
          "start": 2
      }
    ],
  }
}

דוגמה 2 לקובץ system_pricing_plans.json

בדוגמה הזו מוצג קטע קוד של תוכנית תמחור שבה החיוב מתבצע לפי דקות וגם לפי קילומטרים:

  • באופן ספציפי, משתמש הקצה מחויב ב-0.25 דולר קנדי לכל ק"מ וגם ב-0.50 דולר קנדי לכל דקה.
  • שני שיעורי ההמרה האלה מתרחשים בו-זמנית ולא תלויים זה בזה.
  • לכן, נסיעה של קילומטר אחד שנמשכת 10 דקות עולה 9 דולר קנדי. פירוט העלות הוא כדלקמן:
    • ‫3$, מחיר בסיסי
    • ‫0.25$ * 2, החיוב מתבצע פעם אחת בתחילת הנסיעה ופעם אחת אחרי קילומטר אחד.
    • ‫0.5$ * 11, החיוב מתבצע פעם אחת בתחילת כל דקה. החיוב מתחיל אחרי 0 שניות, והמרווח האחרון שחויב הוא 10 דקות.
{
  "plans": {
    "plan_id": "plan2",
    "currency": "CAD",
    "price": 3,
    "per_km_pricing": [{
      "start": 0,
      "rate": 0.25,
      "interval": 1
    }],
    "per_min_pricing": [{
      "start": 0,
      "rate": 0.50,
      "interval": 1
    }]
  }
}

נדרש בתנאים מסוימים: geofencing_zones.json (מערכת עם תחנות עגינה ומערכת ללא תחנות עגינה)

אפשר לעיין במפרט GBFS לפי הצורך.

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

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

שם השדה סוג דרישה תיאור
geofencing_zones אובייקט חובה אובייקט FeatureCollection כפי שמתואר ב- IETF RFC 7946 הוא אובייקט שיש לו שדה בשם features. הערך של features הוא מערך JSON. כל רכיב במערך ה-JSON הוא אובייקט Feature.

כל אזור עם גדר וירטואלית, הכללים והמאפיינים שמשויכים אליו וההגדרות של FeatureCollection מצוינים כאן כחלק מהגדרות הפיד geofencing_zones.json.
geofencing_zones.type מחרוזת חובה הערך צריך להיות FeatureCollection כפי שמתואר ב- IETF RFC 7946.
geofencing_zones.features מערך חובה מערך JSON, שבו כל רכיב במערך ה-JSON הוא אובייקט Feature.
geofencing_zones.features[].type מחרוזת חובה הערך צריך להיות Feature כפי שמתואר ב- IETF RFC 7946.
geofencing_zones.features[].geometry GeoJSON Multipolygon חובה ‫Multipolygon בפורמט GeoJSON שמתאר איפה אי אפשר להתחיל נסיעות, לסיים נסיעות או לעבור דרך מקומות מסוימים, בנוסף למגבלות אחרות. סידור הנקודות בכיוון השעון מגדיר את האזור שמוקף בפוליגון, וסידור הנקודות נגד כיוון השעון מגדיר את האזור שמחוץ לפוליגון. מידע נוסף בנושא זמין במאמר בנושא כלל יד ימין.
geofencing_zones.features[].properties אובייקט חובה אובייקט שמגדיר את קצבאות הנסיעות וההגבלות.
geofencing_zones.features[].properties.rules מערך אופציונלי מערך של אובייקטים, שכל אחד מהם מגדיר כלל אחד בלבד. אם יש חפיפה בין שני כללים או יותר, או אם יש התנגשות או סתירה כלשהי בין הכללים, הכלל שהוגדר ראשון בסדר של קובץ ה-JSON מקבל עדיפות.
geofencing_zones.features[].properties.rules[].vehicle_type_id מערך אופציונלי מערך של מזהי סוגי כלי רכב, שבו כל אלמנט הוא vehicle_type_id, שעליו חלות מגבלות. אם לא מציינים vehicle_type_id, ההגבלות חלות על כל סוגי כלי הרכב.
geofencing_zones.features[].properties.rules[].ride_allowed בוליאני חובה האם אפשר להתחיל ולסיים את הנסיעה באופניים בתוך האזור, באופן הבא:
  • אם אפשר להתחיל ולסיים את הנסיעה באופניים לא מעוגנים באזור, צריך להגדיר את הערך true.
  • אם אי אפשר להתחיל ולסיים את הנסיעה באופניים לא מעוגנים באזור, צריך להגדיר את האזור ל-false.

דוגמה ל-geofencing_zones.json:

"geofencing_zones":{
  "type":"FeatureCollection",
  "features":[{
    "type":"Feature",
    "properties":{
      "rules":[{
        "vehicle_type_id":"scooter",
        "ride_allowed": false
      }]
    },
    "geometry":{
      "type":"MultiPolygon",
      "coordinates":[[[
        [-122.66780376434326, 45.49896266763551],
        [-122.66810417175292, 45.49824825558575],
        [-122.66830801963805, 45.49632305799116],
        [-122.66780376434326, 45.49896266763551]
      ]]]
    }
  }]
}

נדרש: station_information.json (מערכת עגינה)

אפשר לעיין במפרט GBFS לפי הצורך.

הפיד הזה מגדיר את המידע הכללי על תחנות ציבוריות להשכרת אופניים.

שם השדה סוג דרישה תיאור
stations מערך חובה מערך של אובייקטים שכל אחד מהם מגדיר תחנה אחת בלבד.
stations[].station_id מחרוזת חובה המזהה של התחנה.
stations[].name מחרוזת חובה השם הציבורי של התחנה בשפה המקומית של העיר שבה התחנה נמצאת. הערך של name צריך להיות זהה לערך שמופיע בשילוט בתחנה, אם יש כזה, או לשקף את מיקום התחנה באמצעות רחוב חוצה או ציון של נקודת ציון מקומית. לא להשתמש בקיצורים כמו St.‎ במקום Street, אלא אם הקיצור הזה מופיע באופן מפורש בשילוט, וname צריך להיות באותיות רישיות וקטנות בהתאם למוסכמות המקומיות לשימוש באותיות רישיות בשמות מקומות, ולא באותיות רישיות בלבד.
stations[].lat קו רוחב חובה קו הרוחב של התחנה לפי תקן WGS 84, בפורמט מעלות עשרוניות.
stations[].lon קו אורך חובה קו האורך של התחנה לפי תקן WGS 84, בפורמט מעלות עשרוני.
stations[].capacity מספר שלם לא שלילי אופציונלי מספר שלם לא שלילי שמייצג את המספר הכולל של נקודות העגינה שהותקנו בתחנה, גם אלה שזמינות וגם אלה שלא זמינות.
stations[].rental_uris אובייקט חובה

אובייקט JSON שמכיל מזהי URI להשכרה ל-Android, ל-iOS ולאינטרנט בשדות המתאימים.

אם מציינים את כתובות ה-URI האלה, הן מבטלות את קישורי העומק שמוגדרים כברירת מחדל כשהספק מצטרף.
stations[].rental_uris.android URI חובה להזין ערך באופן מותנה

‫URI שאפשר להעביר לאפליקציה ל-Android באמצעות android.intent.action.VIEW Android intent כדי לתמוך בקישורי עומק ל-Android. כתובת ה-URL שצוינה rental_uris צריכה להיות קישור לאפליקציית Android, כדי שאפליקציית הצפייה לא תצטרך לנהל באופן ידני את ההפניה של המשתמש לחנות האפליקציות במקרה שאין למשתמש את אפליקציית הספק.

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

לא תמיד צריך לכלול את ה-URI של התחנה ב-station_id, כל עוד לשותף יש אמצעים אחרים לזיהוי התחנה הרלוונטית. לדוגמה, אפליקציית ההשכרה יכולה להשתמש במזהים אחרים ב-URI כדי לזהות את התחנה באופן ייחודי.

אם לשותף יש אפליקציה להשכרת תוכן ל-Android, חובה למלא את השדה הזה.

דוגמה לקישור לאפליקציה ל-Android:

https://www.example.com/app?sid=1234567890&platform=android
stations[].rental_uris.ios URI חובה להזין ערך באופן מותנה

‫URI שאפשר להשתמש בו ב-iOS כדי להפעיל את אפליקציית ההשכרה של התחנה. מידע נוסף על הנושא הזה זמין במאמר של Apple בנושא סכימות של כתובות URL מותאמות אישית ב-iOS. כתובת ה-URL שציינתם צריכה להיות rental_urisקישור אוניברסלי ל-iOSrental_uris, כדי שאפליקציית הצפייה לא תצטרך לנהל באופן ידני את ההפניה של המשתמש לחנות האפליקציות במקרה שהאפליקציה של הספק לא מותקנת אצל המשתמש.

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

לא בהכרח צריך לכלול את station_id במזהי ה-URI של התחנה. אפליקציית ההשכרה יכולה להשתמש במזהים אחרים ב-URI כדי לזהות את התחנה באופן ייחודי.

אם לשותף יש אפליקציה להשכרת רכבים ל-iOS, השדה הזה הוא חובה.

דוגמה לקישורים אוניברסליים ל-iOS:

https://www.example.com/app?sid=1234567890&platform=ios
stations[].rental_uris.web כתובת URL אופציונלי

כתובת URL שאפשר להשתמש בה בדפדפן אינטרנט כדי להציג מידע נוסף על השכרת רכב בתחנה הזו.

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

כתובות ה-URL לא חייבות לכלול את station_id לתחנה או לפעול לפי המוסכמות הסמנטיות של כתובות ה-URL להשכרה ל-Android או ל-iOS. אפליקציית ההשכרה יכולה להשתמש במזהים אחרים בכתובת ה-URL כדי לזהות באופן ייחודי את התחנה.

אם השדה הזה לא מוגדר, המשמעות היא שדפדפן האינטרנט לא תומך בקישורים עמוקים.

ערך לדוגמה:

https://www.example.com/app?sid=1234567890

דוגמה ל-station_information.json:

"stations": [
  {
    "station_id": "597",
    "name": "Silverthorne Road, Battersea",
    "lat": 51.472865,
    "lon": -0.148059,
    "capacity": 10,
    "rental_uris": {
        "android": "https://www.example.com/app?sid=1234567890&platform=android",
        "ios": "https://www.exampleexample.com/app?sid=1234567890&platform=ios",
        "web": "https://www.example.com/app?sid=1234567890&platform=web"
    }
  },
]

חובה: station_status.json (מערכת עגינה)

אפשר לעיין במפרט GBFS לפי הצורך.

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

שם השדה סוג דרישה תיאור
stations מערך חובה מערך של אובייקטים, שכל אחד מהם מגדיר תחנה אחת בלבד.
stations[].station_id מחרוזת חובה המזהה של התחנה.
stations[].num_bikes_available מספר שלם לא שלילי חובה

מספר שלם לא שלילי שמייצג את מספר האופניים התקינים שנמצאים פיזית בתחנה ואפשר להציע אותם להשכרה.

כדי לדעת אם אפשר לשכור אופניים בתחנה מסוימת, צריך לבדוק את השדה is_renting של התחנה ולחפש ערך בוליאני true.
stations[].vehicle_types_available מערך אופציונלי

מערך של אובייקטים שמגדיר את המספר הכולל של כלי רכב, שמסווגים לפי סוג כלי הרכב הספציפי שזמין בתחנה. כל אובייקט מייצג את המספר הכולל של כלי רכב מסוג הרכב המשויך. הסכום הכולל של כלי הרכב מכל אחד מהאובייקטים האלה צריך להיות זהה לערך שצוין בשדה num_bikes_available.
stations[].vehicle_types_available[].vehicle_type_id מזהה חובה

ה-vehicle_type_id של כל סוג רכב שזמין בתחנה, כפי שמתואר בקובץ vehicle_types.json.
stations[].vehicle_types_available[].count מספר שלם לא שלילי חובה

המספר הכולל של כלי רכב זמינים עבור vehicle_type_id התואם בתחנה, כפי שמוגדר בקובץ vehicle_types.json.
stations[].num_docks_available מספר שלם לא שלילי חובה להזין ערך באופן מותנה

חובה למלא את השדה, אלא אם יש לתחנה קיבולת עגינה בלתי מוגבלת. לדוגמה, בתחנות וירטואליות יש קיבולת עגינה בלתי מוגבלת, ולכן השדה הזה לא נדרש.

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

כדי לדעת אם אפשר להחזיר אופניים לתחנה מסוימת, צריך לבדוק את השדה is_returning של התחנה ולחפש ערך בוליאני true.
stations[].is_installed בוליאני חובה

ערך בוליאני שמציין אם התחנה נמצאת כרגע ברחוב ומותקנת.

אם התחנה מותקנת ברחוב, מגדירים את הערך true.

אם התחנה לא מותקנת ברחוב, מגדירים את הערך false.
stations[].is_renting בוליאני חובה

ערך בוליאני שמציין אם התחנה משכירה אופניים כרגע.

אם בתחנה מושכרים אופניים, מגדירים את הערך true. גם אם התחנה ריקה, אם היא מוגדרת להשכרת רכבים, הערך של is_renting הוא true.

אם כרגע אי אפשר לשכור אופניים בתחנה, מגדירים את הערך false.
stations[].is_returning בוליאני חובה

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

אם התחנה מקבלת כרגע החזרות של אופניים, צריך להגדיר את הערך true. גם אם התחנה מלאה, אבל הייתה מאפשרת החזרה אם היא לא הייתה מלאה, הערך של is_returning הוא true.

אם התחנה לא מקבלת כרגע החזרות של אופניים, צריך להגדיר את הערך false.

דוגמה ל-station_status.json:

"stations": [
        {
          "station_id": "2",
          "num_bikes_available": 6,
          "vehicle_types_available": [
            {
              "vehicle_type_id" : "scooter_electric",
              "count" : 2
            },
            {
              "vehicle_type_id" : "bike_manual",
              "count" : 4
            }
          ],
          "num_docks_available": 30,
          "is_installed": true,
          "is_renting": true,
          "is_returning": true,
          "last_reported": 1576119631
        },
]