Clarification system_pricing_plans.json

[sven4all]

For me the current explanation of plans[].per_min_pricing in system_pricing_plans.json is not very clear at this moment for some specific scenarios where the fare is not calculated per minute but per x minutes.

This is what is currently defined in the standard.

Field Name	REQUIRED	Type	Defines
plans[].per_min_pricing (added in v2.2)	OPTIONAL	Array<Object>	Array of segments when the price is a function of time traveled, displayed in minutes. Total cost is the addition of price and all segments in per_km_pricing and per_min_pricing. If this array is not provided, there are no variable costs based on time.
plans[].per_min_pricing[].start (added in v2.2)	REQUIRED	Non-Negative Integer	The minute at which this segment rate starts being charged (inclusive).
plans[].per_min_pricing[].rate (added in v2.2)	REQUIRED	Float	Rate that is charged for each minute interval after the start. Can be a negative number, which indicates that the traveler will receive a discount.
plans[].per_min_pricing[].interval (added in v2.2)	REQUIRED	Non-Negative Integer	Interval in minutes at which the rate of this segment is either reapplied indefinitely, or up until (but not including) the end minute, if end is defined. An interval of 0 indicates the rate is only charged once.
plans[].per_min_pricing[].end (added in v2.2)	OPTIONAL	Non-Negative Integer	The minute at which the rate will no longer apply (exclusive) for example, if end is 20 the rate no longer applies after 19:59. If this field is empty, the price issued for this segment is charged until the trip ends, in addition to the cost of any subsequent segments.

The fare that I would like to model is:

• 3 euro for the first 20 minutes
• 4 euro for the first 30 minutes
• 0.10 euro for every minute afterwards.

I made the following interpretation but I'm not sure which one is right (altough the first option makes most sense to me):

{
  "last_updated": 1783492244,
  "ttl": 60,
  "version": "2.2",
  "data": {
    "plans": [
      {
        "plan_id": "2XIXWUW562Z2K",
        "currency": "EUR",
        "is_taxable": true,
        "per_min_pricing": [
          {
            "start": 0,
            "end": 20,
            "rate": 3.00,
            "interval": 0
          },
          {
            "start": 20,
            "end": 30,
            "rate": 1.00,
            "interval": 0
          },
          {
            "start": 30,
            "rate": 0.10,
            "interval": 1
          }
        ],
        "name": "",
        "description": ""
      }
    ]
  }
}

{
  "last_updated": 1783492244,
  "ttl": 60,
  "version": "2.2",
  "data": {
    "plans": [
      {
        "plan_id": "2XIXWUW562Z2K",
        "currency": "EUR",
        "is_taxable": true,
        "per_min_pricing": [
          {
            "start": 0,
            "end": 20,
            "rate": 3.00,
            "interval": 20
          },
          {
            "start": 20,
            "end": 30,
            "rate": 1.00,
            "interval": 10
          },
          {
            "start": 30,
            "rate": 0.10,
            "interval": 1
          }
        ],
        "name": "",
        "description": ""
      }
    ]
  }
}

{
  "last_updated": 1783492244,
  "ttl": 60,
  "version": "2.2",
  "data": {
    "plans": [
      {
        "plan_id": "2XIXWUW562Z2K",
        "currency": "EUR",
        "is_taxable": true,
        "per_min_pricing": [
          {
            "start": 0,
            "end": 20,
            "rate": 0.15,
            "interval": 20
          },
          {
            "start": 20,
            "end": 30,
            "rate": 0.10,
            "interval": 10
          },
          {
            "start": 30,
            "rate": 0.10,
            "interval": 1
          }
        ],
        "name": "",
        "description": ""
      }
    ]
  }
}

Can we try to make this documentation more unambiguous with at least adding more examples, but maybe also some improvements in the text.

[richfab]

Hi @sven4all,

Thank you for your question. I agree that the examples can be improved. I will work on them.

To follow the spec, use your first interpretation and move the base price of 3€ in the price field:

{
  "last_updated": 1783492244,
  "ttl": 60,
  "version": "2.2",
  "data": {
    "plans": [
      {
        "plan_id": "2XIXWUW562Z2K",
        "currency": "EUR",
        "price": 3.00,
        "is_taxable": true,
        "per_min_pricing": [
          {
            "start": 20,
            "end": 30,
            "rate": 1.00,
            "interval": 0
          },
          {
            "start": 30,
            "rate": 0.10,
            "interval": 1
          }
        ],
        "name": "",
        "description": ""
      }
    ]
  }
}

Please let me know if you have any questions.

Best regards,
Fabien (MobilityData)