Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Carsharing extension #350

Merged
merged 44 commits into from
Dec 27, 2021
Merged

Carsharing extension #350

merged 44 commits into from
Dec 27, 2021

Conversation

fchabouis
Copy link
Contributor

Who we are

Transport.data.gouv.fr is the French national access point for mobility data.

We are opening this PR on our behalf and on behalf of a working group involving the “Association des Acteurs de l’Autopartage” (AAA), a French National Association for carsharing grouping 20+ operators, and Iodines.

What problem does your proposal solve?

This PR aims to extend the current GBFS specification to allow car sharing support.
More details can be found in the issue #338.

Proposal overview

We would like to propose an evolution of the GBFS which allows to model car-sharing data by extending the following files. This evolution is based on the addition of new fields and the modification of existing fields.

  • vehicle_types.json
    New optional fields:
    - rider capacity
    - trunk size
    - C02 emission
    - environmental classification
    - accessories
    - ...
    Field that has been modified:

  • addition of new allowed values in propulsion_type

  • station_information.json
    New optional fields:
    - parking_type
    - parking_hoop
    - contact_phone
    Field that has been modified:

  • description of the field is_virtual_station

  • free_bike_status.json
    New optional fields:
    - available_until, a datetime specifying how much time the vehicle is available (for round trip carsharing)
    - vehicle_equipment, accessories present in the vehicle (such as child seats)
    Field that has been modified:

  • modification of the description of current_range_meters

Is this a breaking change?

  • Yes
  • No
  • Unsure

Which files are affected by this change?

  • vehicle_types.json
  • station_information.json
  • free_bike_status.json

@fchabouis
Copy link
Contributor Author

In this PR, we have added the Phone number field definition, similarly to the proposal made in #351. As this field type is already referenced in the file_system.json file, but with a description different from the one we give, it could be confusing.

To keep the proposal non breaking, we could remove the new field definition and let #351 add it afterward.

Concerning contact_phone, the field we added in station_information.json, we could specify in its description that it should follow the E.164 standard. Then, when #351 is merged, we could revert the field description as it wouldn't be useful anymore.

gbfs.md Outdated Show resolved Hide resolved
@mplsmitch
Copy link
Collaborator

@fchabouis I don't see current_range_percent as a suitable substitute for current_range_meters. If the intention is that a vehicle with current_range_percent of 0.75 has a range of 75% of max_range_meters, then that calculation is already possible using existing fields: current_range_meters / max_range_meters = current_range_percent. If current_range_percent is intended as a measure of vehicle range, and the producer is able to provide current_range_percent then there's no reason they can't calculate and provide current_range_meters. If that's the case then it would be better if this range calculation were done by the data producer so that consuming applications wouldn't have to look at multiple fields for the data, making the calculation more prone to error.

I understand that an end user would find current_range_percent useful, for example they may prefer to choose the vehicle that is 85% full versus the one that is 25% full, but as it's name implies that this is the percentage vehicle range, not it's fuel or charge level. The current_range_percent definition doesn't mention range, only fuel or charge level. I suggest renaming the field to something like fuel_charge_percent and either making it OPTIONAL or conditionally Required if the vehicle has a motor.

@fchabouis
Copy link
Contributor Author

Hello @mplsmitch , thank you for your feddback !
We had an interesting conversation with a carsharing operator, whose fleet is only composed of electrical vehicles. I think it was Iodines. Their point was : they didn't want to give users a range in meters because an electrical car range heavily depends on the driving style and type of roads used. Highways at 130km/h and cities would yield very different ranges. They felt that giving users a range in meters could therefore be problematic, if they say the car has a current range of 300km and the driver finds himself with an empty battery after a 200km drive. That's why they felt more comfortable giving a percentage of charge of the battery. But for a e-scooter company operating in a city, giving ranges as a distance makes more sense, as the driving conditions are more homogeneous, and the consequences of an empty battery are not the same (no baby crying on the back seat!).
What do you think ?

@NicolasFrasie
Copy link

NicolasFrasie commented Aug 27, 2021

Hello @mplsmitch , there is another reason than the one mentionned by @fchabouis. It is generally not possible to know directly from the vehicle which range the vehicle displays on the dashboard unlike the % of charge of battery. Now, if the range in km is calculated as you propose, the end user may feel deceived if the range actually displayed is very different from the range previously given (for the reasons mentionned previsouly).

This being said, this is technical constraint isn't ideal for the users and I hope in the future operators will be able to provide a precise range in km, maybe depending on each user, geography, local temperature, etc.

@mplsmitch
Copy link
Collaborator

@fchabouis I think it's important to remember that the consumers of these data are journey planning and MaaS applications, not end users. For the journey planner it's impossible to match an appropriate vehicle with a user without knowing the estimated vehicle range.

I agree that the carshare use case is significantly different from escooters and ebikes but I think the need for range data to support these applications is still there. If the fuel or charge lever is substituted for current_range_meters , journey planners will have to calculate the vehicle range in order to do their work. The operator of the vehicle is much better equipped to make this calculation than the journey planner. Since there are many variables affecting range, calculation of current_range_meters must be very conservative. Where I live, the range of electric vehicles is far less in winter than in summer depending on the temperature. A vehicle who's battery has been through 50 charge cycles may have a range that is close to 100% of its maximum whereas the same vehicle with 700 charge cycles would have much less range. For these reasons you would not say that a vehicle with 50% charge can travel 50% of its maximum range.

It is generally not possible to know directly from the vehicle which range the vehicle displays on the dashboard unlike the % of charge of battery. Now, if the range in km is calculated as you propose, the end user may feel deceived if the range actually displayed is very different from the range previously given (for the reasons mentionned previsouly).

There's a lot of data contained in the specification that's used to facilitate journey planning but is never shown to end users. While a journey planner may use current_range_meters to match a user with a vehicle, they don't need to display that data to the user. Many of them prefer to display the % charge level which is currently being calculated as current_range_meters / max_range_meters.

@NicolasFrasie
Copy link

NicolasFrasie commented Aug 27, 2021

The operator of the vehicle is much better equipped to make this calculation than the journey planner.

I disagree. Yes, the range of a vehicle (in km) can vary along the lifespan of the battery, but - for what I understand - this should be modelled by udpating the max_range_meter field (provided that the operator knows how to measure this drop in capacity).

Moreover, as mentionned earlier, it is generally impossible for carsharers to provide the current_range_meters (unless calculating current_range_percent * max_range_meters).

@evansiroky
Copy link
Contributor

I remember discussing this topic of including range as meters or range as percent a lot in the initial work to add vehicle type definitions. See a comment in the middle of the thread here: #136 (comment).

As far as the proposed modifications proposed in this PR, I like that the current_range_* fields are still defined as numeric values. However, it does seem somewhat unnecessary since either percent or absolute range can be naïvely derived from the other. It seems the primary concern and motivation for including the percentage field is not wanting to mislead users on range estimates. However, from a trip planning perspective, trip planners must know the range or pretend they know it by making speculative calculations about how the vehicle itself, the environment the vehicle travels through and certain user behaviors all interact to result in how far a vehicle can be expected to travel before it runs out of energy. And I would say this applies even within cities although more so in those with lots of hills.

Maybe one differentiating factor about the car use case, in particular, is that it is likely more common for someone to rent a car and refill the gas tank. This is opposed to the e-scooters and e-bikes short-term rental use case where a vehicle may not have as long of a rental time period and users, therefore, may not recharge/refill the vehicle or even have the ability to do so. And on the trip planner side, lots if not most trip planners provide driving directions without built-in calculations of where to stop to refill/recharge a car. It is assumed that people have a common knowledge that refilling/recharging a vehicle will be required at least a few times if one were to attempt to drive across the US for example.

I'm not sure what the best user experience is in terms of having this current range communicated to users, but maybe a good start on that topic is to add a field (perhaps in this PR or elsewhere) that describes whether a vehicle can be recharged/refueled, how long that takes and where reenergizing can happen. Then trip planners would at least be able to better communicate whether journeys could occur that exceed a vehicle's maximum full-energy range. Also, it could help to communicate an expected "average" range per charge/full tank. Perhaps this topic is something that could eventually be in a best practices document for how to produce this value and for how client applications should communicate it to users.

@kanagy
Copy link

kanagy commented Sep 1, 2021

I agree with both Evan and Mitch points. My 2c for an alternative solution: As a trip planner, knowing maximum range is useful for picking the vehicle around you that can actually make the desired trip. However, for petrol vehicles that can be easily refueled this doesn't really matter and we wouldn't take it into account. Perhaps a simple solution is to make current_range_meters only required for electric propulsion, and optional for other use cases? From experience, many carsharing companies don't know in realtime how much petrol would be in a vehicle.

@NicolasFrasie
Copy link

I share your analysis of the difference between electric vehicle and ICE vehicles, and I understand your needs as a trip planner. However, operators generally don't know the current_range_meters of electric vehicle unless calculating current_range_percent (provided by the vehicle) / max_range_meters (theorical one, based on WLTP).

I have the understanding that a trip planner is much more equipped to make the calculation of the required range to realize a trip, based on km, elevation gain, speed (if highway, if congestion, etc.) and temperature. I speak here about a trip of tens of km, not just a few kilometers that should be better realized by bike, escooter, etc.

@fchabouis
Copy link
Contributor Author

What about giving a current_range_meters and an optional current_minimum_range_meters ?

  • current_range_meters could be used to give the estimated vehicle range, and battery capacity could be deduced from that value, dividing it by max_range_meters (that's the current situation).
  • for renting situation where the effective range can have important consequences, a minimum range in meters could be given, using conservative hypothesis. This value could be used by trip planners to ensure the vehicule can make the desired trip, or at least refuel on the way safely.

For example, with current_range_meters = 300 000 and current_minimum_range_meters = 100 000 :

  • a 50km trip is planned => no problem
  • a 150km trip is planned => vehicle is proposed for renting with a message "a refill may be necessary on the way"
  • a 350km trip is planned => vehicle is proposed for renting with a message "a refill will be necessary on the way"

This way data producers can avoid deceiving users with false promises, but still have to provide an information about the range of the vehicule they are renting. For vehicles where refueling is not a problem, like gas cars, the current_minimum_range_meters could be omitted.

@NicolasFrasie
Copy link

Communauto supports this proposal.

gbfs.md Outdated
\- `station_id` <br/>*(added in v2.1)* | Conditionally REQUIRED | ID | Identifier referencing the `station_id` field in [station_information.json](#station_informationjson). REQUIRED only if the vehicle is currently at a station and the [vehicle_types.json](#vehicle_typesjson) file has been defined.
\- `home_station_id` <br/>*(added in v2.3-RC)* | OPTIONAL | ID | The `station_id` of the station this vehicle must be returned to as defined in [station_information.json](#station_information.json).
\- `pricing_plan_id` <br/>*(added in v2.2)* | OPTIONAL | ID | The `plan_id` of the pricing plan this vehicle is eligible for as described in [system_pricing_plans.json](#system_pricing_plans.json). If this field is defined it supersedes `default_pricing_plan_id` in `vehicle_types.json`. This field SHOULD be used to override `default_pricing_plan_id` in `vehicle_types.json` to define pricing plans for individual vehicles when necessary.
\- `vehicle_equipment`<br/>*(added in vXXX)* | OPTIONAL | Array | Description of vehicle equipment that can be provided by the operator in addition to the accessories already provided in the vehicle (field `vehicle_accessories` of vehicle_type.json) but subject to more frequent updates.<br/><br/>Current valid values are:<ul><li>`child_seat_0` _(Baby seat ("0-10kg"))_</li><li>`child_seat_1` _(Seat or seat extension for small children ("9-18 kg"))_</li><li>`child_seat_4` _(Seat or seat extension for older children ("15-36 kg"))_</li><li>`winter_tires` _(Vehicle has tires for winter weather)_</li><li>`snow_chains`</li></ul>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a question about this. I do not believe it is a big change, so it should not impact the timing of the vote but should be addressed before the vote closes.

For the child seats, I believe it should be presented as an enum, not an array. For readability, the car seat enums should be 'a', 'b', 'c' so that they are not mistaken for the number of child seats in the car. Which raises the question - how would a producer represent if there are multiple child seats?

Copy link
Contributor Author

@fchabouis fchabouis Dec 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently vehicle_equipment is an array. So if there are 2 child_seat_0 in the vehicle, I guess you can put the item twice in the array.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fchabouis Would you be ok with changing the naming from child_seat_0, child_seat_1, etc to child_seat_a, child_seat_b, etc.? To address my concern about the names being mistaken for the number of child seats?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@heidiguenin The changes have been made, thank you

* URI *(added in v1.1)* - A fully qualified URI that includes the scheme (e.g., `com.example.android://`), and any special characters in the URI MUST be correctly escaped. See the following https://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.
* URL - A fully qualified URL that includes `http://` or `https://`, and any special characters in the URL MUST be correctly escaped. See the following https://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URL values.
* Phone number - Phone number in international formatting (specification [E.164](https://en.wikipedia.org/wiki/E.164)). In particular, the phone number MUST start with a "+". The characters after the "+" MUST be numbers and MUST NOT contain any hyphen, space or parenthesis.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With #351 open for a vote, I'd suggest removing this one to minimize merge conflicts. (They refer to the same standard.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, you can just merge #351 first and I will resolve the resulting conflict.

@testower
Copy link
Contributor

testower commented Dec 3, 2021

Entur supports this proposal

@MGidel
Copy link

MGidel commented Dec 3, 2021

+1 from the City of Paris (Direction de la Voirie et des Déplacements)

@heidiguenin
Copy link
Contributor

Voting on this PR closes in 2 calendar days. Please vote for or against the proposal, and include the organization for which you are voting in your comment. Please note if you can commit to implementing the proposal.

@iodines-team
Copy link

IODINES supports this proposal.

gbfs.md Outdated
\- `max_range_meters` | Conditionally REQUIRED | Non-negative float | If the vehicle has a motor (as indicated by having a value other than `human` in the `propulsion_type` field), this field is REQUIRED. This represents the furthest distance in meters that the vehicle can travel without recharging or refueling when it has the maximum amount of energy potential (for example, a full battery or full tank of gas).
\- `name` | OPTIONAL | String | The public name of this vehicle type.
\- `vehicle_accessories`<br/>*(added in vXXX)* | OPTIONAL | Array | Description of accessories available in the vehicle. These accessories are part of the vehicle and are not supposed to change frequently. Current valid values are:<ul><li>`air_conditioning` _(Vehicle has air condition)_</li><li>`automatic` _(Automatic gear switch)_</li><li>`manual` _(Manual gear switch)_</li><li>`convertible` _(Vehicle is convertible)_</li><li>`cruise_control` _(Vehicle has a cruise control system ("Tempomat"))_</li><li>`doors_2` _(Vehicle has 2 doors)_</li><li>`doors_3` _(Vehicle has 3 doors)_</li><li>`doors_4` _(Vehicle has 4 doors)_</li><li>`doors_5` _(Vehicle has 5 doors)_</li><li>`navigation` _(Vehicle has a built-in navigation system)_</li></ul>
\- `g_CO2_km`<br/>*(added in vXXX)* | OPTIONAL | Non-negative integer | Maximum quantity of CO2, in grams, emitted per kilometer, according to the [WLTP](https://en.wikipedia.org/wiki/Worldwide_Harmonised_Light_Vehicles_Test_Procedure).
\- `vehicle_image`<br/>*(added in vXXX)* | OPTIONAL | URL | URL to an image that would assist the user in identifying the vehicle (e.g. logo, image of vehicle).<br /> Allowed formats: JPEG, JPG, PNG. Minimum resolution of 300 pixels per inch (ppi).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Aren't JPG and JPEG the same format, just both file extensions are common?
  2. 300 ppi is not a resolution, as ppi describes the pixel density. Defining an aspect ratio (or multiple allowed) could also be considered.

Note that pixel density is not the same as resolution, where the former describes the amount of detail on a physical surface or device, the latter describes the amount of pixel information regardless of its scale.

https://en.wikipedia.org/wiki/Pixel_density

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. True. We can remove JPG wich is just a possible extension of the JPEG format.
  2. Would "Minimum density of 300 pixels per inch (ppi)" be correct then ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Sounds reasonable.
  2. That would imho make slightly more sense in a technical sense. However, the ppi are dependent from the viewing device... So stating an actual minimal resolution probably was not a bad idea, that's why I ended up thinking about aspect ratios, as you could only specify something like "The shorter edge SHOULD (or MUST?) have at least x pixels." However, the maximum pixels (of the longer edge?) might also is worth to be specified, otherwise huge files (with very high resolutions) would be allowed by the spec, but probably not desirable.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could remove the constraint on the image size / resolution for the moment and see if it's necessary to add such details afterwards.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fchabouis I believe that is the right approach for now. When we added vehicle icons and brand assets in v2.3-RC, we recognized that it was a first step, and other additions might be necessarily in the future, too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Details on the number of pixels have been removed

gbfs.md Outdated Show resolved Hide resolved
fchabouis and others added 2 commits December 8, 2021 14:21
Co-authored-by: Daniel <36266644+nbdh@users.noreply.github.com>
@ncancelliere
Copy link

+1 from Spin. We don't do car sharing but this is not backwards breaking so we're okay with this proposal.

@fredpetit
Copy link

+1 from Grenoble-Alpes Métropole (mobilités)

@veddan
Copy link

veddan commented Dec 9, 2021

+1 from Move About.

@heidiguenin
Copy link
Contributor

This vote has now closed, and it passes!

Votes in favor:
Colorado CarShare (producer)
Transit (consumer)
Communauto (producer)
Entur (consumer)
City of Paris (consumer)
IODINES (producer)
Spin (producer)
Grenoble-Alpes Métropole (mobilités) (consumer)
Move About (producer)

There were no votes against.
Thank you to everyone who took the time to review and to vote on this! We appreciate the careful review and compromise that went into the decision to add carsharing to GBFS.

We'll update the documentation as discussed, and then we will tag and merge this into v2.3-RC2 in the coming weeks.

@Miryad3108
Copy link
Contributor

Hello,

Thanks to all the people who contributed to the improvement of our initial proposal and all those who voted in favor of this Pull Request.

Are there any producers who can produce data on their carsharing offer in GBFS format in accordance with this proposal and reusers who will be able to integrate it into their services before april 2022 ?
This will allow to integrate this proposal into the GBFS and move it from the "Release candidate" status.
See. https://github.com/NABSA/gbfs#governance--overview-of-the-change-process

The transport.data.gouv.fr team will support potential producers and reusers if they have difficulties

Thank you in advance,

@testower @NicolasFrasie @iodines-team @veddan @fredpetit @ncancelliere @MGidel @cmonagle @PeterCOCarShare @kanagy @evansiroky @nbdh @mplsmitch

modification of :
the definition of electric propulsion
the name of the hydrogen propulsion
@mplsmitch mplsmitch merged commit 33f20a7 into MobilityData:master Dec 27, 2021
@fchabouis
Copy link
Contributor Author

@mplsmitch thanks for merging !
For info for the newly added fields, we put added in vXXX, and that will need to be replaced with the actual targeted version.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.