Extend system_pricing_plans.json

gbfs.md

@@ -127,6 +127,7 @@ Example: `41.890169` for the Colosseum in Rome.
 Example: `12.492269` for the Colosseum in Rome.
 * Non-negative Integer - An integer greater than or equal to 0.
 * Non-negative Float - A floating point number greater than or equal to 0.
+* Float - A floating point number.
 * Timezone - TZ timezone from the https://www.iana.org/time-zones. Timezone names never contain the space character but may contain an underscore. Refer to http://en.wikipedia.org/wiki/List_of_tz_zones for a list of valid values.
 Example: `Asia/Tokyo`, `America/Los_Angeles` or `Africa/Cairo`.
 * URI *(added in v1.1)* - A fully qualified URI that includes the scheme (e.g., `com.abcrental.android://`), and any special characters in the URI must be correctly escaped. See the following http://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URI values. Note that URIs may be URLs.
@@ -571,15 +572,89 @@ Describes pricing for the system.
 
 Field Name | Required | Type | Defines
 ---|---|---|---
-`plans` | Yes | Array | Array of objects as defined below.
+`plans` | Yes | Array | Array of objects as defined below.<br /><br /> In the event of colliding plans, the earlier plan (ir order of the JSON file) takes precedence.
 \-&nbsp;`plan_id` | Yes | ID | Identifier for a pricing plan in the system.
+\-&nbsp;`vehicle_type_id` | Optional | Array | `vehicle_type_id` of the vehicle eligible for this pricing plan as described in [vehicle_types.json](#vehicle_typesjson-added-in-v21-rc).<br /><br />If this field is empty, the plan applies to all vehicle types defined in the dataset.<br /><br />In the case of a vehicle type being attributed to different plans, all plans associated with the vehicle type are valid.   
 \-&nbsp;`url` | Optional | URL | URL where the customer can learn more about this pricing plan.
 \-&nbsp;`name` | Yes | String | Name of this pricing plan.
 \-&nbsp;`currency` | Yes | String | Currency used to pay the fare. <br /><br /> This pricing is in ISO 4217 code: http://en.wikipedia.org/wiki/ISO_4217 <br />(e.g. `CAD` for Canadian dollars, `EUR` for euros, or `JPY` for Japanese yen.)
-\-&nbsp;`price` | Yes | Non-negative float OR String | Fare price, in the unit specified by currency. If String, must be in decimal monetary value.
+\-&nbsp;`price` | Yes | Non-negative float OR String | Fare price, in the unit specified by currency. If String, must be in decimal monetary value.<br /><br />In case of non-variable price, this field is the total price. In case of variable price, this field is the base price that is charged only once per trip (e.g., price for unlocking). See `variable_price` for details.
 \-&nbsp;`is_taxable` | Yes | Boolean | Will additional tax be added to the base price?<br /><br />`true` - Yes.<br />  `false` - No.  <br /><br />`false` may be used to indicate that tax is not charged or that tax is included in the base price.
 \-&nbsp;`description` | Yes | String | Customer-readable description of the pricing plan. This should include the duration, price, conditions, etc. that the publisher would like users to see.
+\-&nbsp;`per_km_pricing` | Optional | Array | Array of segments when the price is a function of distance travelled, displayed in kilometers.<br /><br />If this array is not provided, there are no variable prices based on distance.
+&emsp;&emsp;\-&nbsp;`start` | Yes | Non-Negative Integer | Number of kilometers that have to elapse before this segment starts applying.
+&emsp;&emsp;\-&nbsp;`rate` | Yes | Float | Rate that is charged after the `start`. Can be a negative number, which indicates that the traveller will receive a discount.
+&emsp;&emsp;\-&nbsp;`interval` | Yes | Non-Negative Integer | Interval in kilometers at which the `rate` of this segment is reapplied indefinitely, unless defined by `end`.<br /><br />An interval of 0 indicates the rate is only charged once.
+&emsp;&emsp;\-&nbsp; `end` | Optional | Non-Negative Integer | Number of kilometers that have to elapse after this segment has started before this segment stops applying.<br /><br /> If this field is empty, the price issued form this segment is charged until the trip ends, in addition to following segments.
+\-&nbsp;`per_min_pricing` | Optional | Array | Array of segments when the price is a function of time travelled, displayed in minutes.<br /><br />If this array is not provided, there are no variable prices based on time.
+&emsp;&emsp;\-&nbsp;`start` | Yes | Non-Negative Integer | Number of minutes that have to elapse before this segment starts applying.
+&emsp;&emsp;\-&nbsp;`rate` | Yes | Float | Rate that is charged after the `start`. Can be a negative number, which indicates that the traveller will receive a discount.
+&emsp;&emsp;\-&nbsp;`interval` | Yes | Non-Negative Integer | Interval in minutes at which the `rate` of this segment is reapplied indefinitely, unless defined by `end`.<br /><br />An interval of 0 indicates the rate is only charged once.
+&emsp;&emsp;\-&nbsp; `end` | Yes | Non-Negative Integer | Number of minutes that have to elapse after this segment has started, before this segment stops applying.<br /><br />If this field is empty, the price issued from this segment is charged until the trip ends, in addition to following segments. 
+\-&nbsp;`surge_pricing` | Optional | Boolean | Is there currently an increase in price in response to increased demand in this pricing plan? If this field is empty, it means these is no surge pricing in effect.<br /><br />`true` - Surge pricing is in effect.<br />  `false` - Surge pricing is not in effect. 
 
+
+Example:
+
+The user does not pay more than the base price for the first 10 km. After 10 km the user pays $1 per km. After 25 km the user pays $0.50 per km and an additional $3 every 5 km, the extension price, in addition to $0.50 per km. 
+
+```jsonc
+{
+  "plans": {
+    "plan_id": "plan2",
+    "vehicle_type_id": "bike1",
+    "name": "One-Way",
+    "currency": "USD",
+    "price": 2,
+    "is_taxable": false,
+    "description": "Includes 10km, overage fees apply after 10km.",
+    "per_km_pricing": [
+      {
+        "start": 10,
+        "rate": 1,
+        "interval": 1,
+        "end": 25
+      }, 
+      {
+        "start": 25,
+        "rate": 0.5,
+        "interval": 1
+      },
+      {
+        "start": 25,
+        "rate": 3,
+        "interval": 5
+      }
+    ]
+  }
+}
+```
+Example:
+
+This example demonstrates a pricing scheme that has a rate both by minute and by km. The user is charged $0.25 per km as well as $0.50 per minute. Both of these rates happen concurrently and are not dependent on one another. 
+```jsonc
+{
+  "plans": {
+    "plan_id": "plan3",
+    "vehicle_type_id": "scooter1",
+    "name": "Simple Rate",
+    "currency": "CAD",
+    "price": 3,
+    "is_taxable": true,
+    "description": "$3 unlock fee, $0.25 per kilometer and 0.50 per minute.",
+    "per_km_pricing": {
+      "start": 0,
+      "rate": 0.25,
+      "interval": 1,
+    },
+    "per_min_pricing": {
+      "start": 0,
+      "rate": 0.50,
+      "interval": 1
+    }
+  }
+}
+```
 ### system_alerts.json
 This feed is intended to inform customers about changes to the system that do not fall within the normal system operations. For example, system closures due to weather would be listed here, but a system that only operated for part of the year would have that schedule listed in the system_calendar.json feed.<br />
 Obsolete alerts should be removed so the client application can safely present to the end user everything present in the feed.