free_bike_status feed lacks region_id

[nbdh]

What is the issue and why is it an issue?

I noticed that the bikes listed in free_bike_status can't be associated with a certain system region. That means, consumers can only know to which region of a system a bike belongs as long as it is present at a station (and thus has a station_id). For all free-floating bikes the region is essentially unknown.

This is an issue because e.g. a consumer wants to tell how many free floating bikes are available in each of the systems regions.

Probably (without having looked at many feeds) only very few producers are using the option to fragment a system further into into regions and are publishing the optional system_regions feed and are putting the region_id into station_information. Does anybody have insights on how both publishers and consumers are currently using this? We at nextbike have a "brand (system) -> city (region) -> place (station) -> bike" hierarchy and even if it became more and more common to have only one city (region) per brand (system) we publish this feed and have at least one region per system.

In my opinion it would be more consistent to allow specifying the region_id of each bike.

I see this issue being slightly related to https://github.com/NABSA/gbfs/issues/286 where the system_id was added.

Please describe some potential solutions you have considered (even if they aren’t related to GBFS).

I propose adding the region_id as a property of the vehicle objects listed in the bikes array of the free_bike_status feed and making it conditionally required, if the system_regions feed is published. Eventually it could also be left out if station_id is given (thus the region could be derived from the station_information).

I furthermore propose changing the currently optional region_id in station_information feed to Conditionally REQUIRED, as it seems unusual to specify (publish) system regions without telling which station belongs to which region.

Alternatively region_id of the free_bike_status should just added and made optional. I suppose this would make the change non-breaking and thus is the preferable option?

Or are we rather encouraged to leave alone the regions and put each city into an individual system? Thus we'd probably rather comply with

Each distinct system or geographic area in which vehicles are operated should have its own system_id

Perhaps

and I've been planning to open a PR to move this from a recommendation (should) to a requirement (must) under 3.0.

(from https://github.com/NABSA/gbfs/issues/286) even forces us to do so in the future?

But then, what are the regions actually meant for?

Describe regions for a system that is broken up by geographic or political region.

Not sure how "geographic areas" (system) shall be broken up. I'd appreciate some examples of how this is intended.

Is your potential solution a breaking change?

• [ ] Yes
• [ ] No
• [x] Unsure - probably depending on whether the new field becomes Conditionally REQUIRED or optional.

[mplsmitch]

Hello @nbdh, You have wonderful timing with your question. I'm just finishing up a PR that addresses some of these issues. It will remove system_id from free_bike_status and require that each distinct system or geographic area in which vehicles are operated MUST have its own unique system_id.

The lack of a region_id in free_bike_status is a known issue that needs to be fixed. It should get added to the free_bike_status bikes array and should be conditionally required of systems publishing system_regions.json

I'd be happy to put together a PR covering that next week.

On the question about how system_regions is intended to be used:

Or are we rather encouraged to leave alone the regions and put each city into an individual system? Thus we'd probably rather comply with

Each distinct system or geographic area in which vehicles are operated should have its own system_id

Each city or geographic area should have its own system_id. The reason this has been described as a geographic area as opposed to a city is because many systems span multiple cities.

The system_regions file is used to divide a system (geographic area) into multiple regions. An example of this is Boston Blue Bikes - the system covers the city of Boston as well as the surrounding cities of Brookline, Cambridge, Somerville and more, each of which is assigned a region_id. https://gbfs.bluebikes.com/gbfs/en/system_regions.json

This has primarily been used by operators and cities for management and regulatory purposes. For example if there were differing requirements for the number of bikes deployed in Boston and Cambridge, you could query station_status.num_bikes_available on region_id to determine the number of bikes currently in the Boston and Cambridge regions.

Not sure how "geographic areas" (system) shall be broken up. I'd appreciate some examples of how this is intended.

What constitutes a region is up to the publisher, it doesn't have to be a city or municipal boundary. For example you could have a region that covers a downtown business district or a university campus.

As I understand it, I think this mostly fits with your NextBike hierarchy:

"brand (system) -> city (region) -> place (station) -> bike"

Since many of the operators use the same brand across all the cities in which they operate I would describe it as: "geographic area(system) -> (region) -> place (station) -> bike"

Lastly, if you haven't seen it, take a look at #306 , which is somewhat related to this issue.

[nbdh]

Hello @mplsmitch,

thanks for your reply and extensive explanation regarding the definition of area/region including examples.

It seems we really should start publishing one feed per city, which means a major change for us. It also means we will probably stop publishing system_regions (as cities are not further broken up in our system), making this issue less relevant for consumers of our feeds.

The lack of a region_id in free_bike_status is a known issue that needs to be fixed.

Is there an actual open issue here? If so I would close this one, if not, perhaps you want to link the MR you mentioned with this issue and keep it open until the fix is got merged?

[mplsmitch]

Hi @nbdh,

I'm not familiar will all of of the NextBike systems but looking at a few I don't think you need to split your feeds by city in every case. Here's an example: https://gbfs.nextbike.net/maps/gbfs/v2/nextbike_tq/gbfs.json

from systems_regions: { "region_id": "681", "name": "Mladá Boleslav" }, { "region_id": "704", "name": "Mnichovo Hradiště" }, { "region_id": "718", "name": "Bakov nad Jizerou" }

It appears that this feed spans the cities of Mladá Boleslav, Mnichovo Hradiště and Bakov nad Jizerou. If a user can rent a bike in Mladá Boleslav, and return it in one of the other two cities, or pay a tariff one city and have access to bikes in another, that's a single system.

[mplsmitch]

Question: If we add region_id to free_bike_status, how would the region be determined for free floating vehicles? In the case of stations, the region can be determined by the operator and assigned to the station but with free floating vehicles the region would need to be dynamic and system_regions.json doesn't contain any geographic information.

[nbdh]

Hi @mplsmitch,

thanks for taking the time to look through our feeds ;-). I must agree, nextbike_tq is an excellent example where the regions would not belong into individual systems. So what I said ("we should start publishing one feed per city") obviously is not correct for all our systems defining of multiple regions.

Regarding your question: At nextbike the region (city) of our free floating vehicles is always determined upon return, and every free floating vehicle must be associated with one region. But I understand your concerns that other providers might are not able to provide this, though I'm not sure how to address those. Do you have any proposal?

[mplsmitch]

Hi @nbdh, You say that

the region (city) of our free floating vehicles is always determined upon return

but the regions file only defines the region name and region_id so how do you determine what region a free floating vehicle is returned to? I think a way to do this would be to extend the regions file to include GeoJSON to define the geography of each region. Something like:

{
  "last_updated": 1604332380,
  "ttl": 86400,
  "version": "3.0",
  "data": {
    "regions": [
      {
        "name": "North",
        "region_id": "3",
        "region_geography" : {
            "type": "MulitPolygon",
            "coordinates": [
                [
                    [-73.957957, 40.800621],
                    [-73.981738, 40.768257],
                    [-73.973496, 40.764681],
                    [-73.973067, 40.765331],
                    [-73.972552, 40.765136],
                    [-73.9492, 40.796788],
                    [-73.957957, 40.800621]
                ]
            ]
        },
 {
        "name": "South",
        "region_id": "4",
         "region_geography" : {
            "type": "MulitPolygon",
            "coordinates": [
                [

...

Then when the vehicle is returned you could determine if it's reported location is within the coordinates for one of the regions and assign the correct region_id to the vehicle in free_bike_status. What should happen if the vehicle is returned outside of the defined regions? Would free_bike_status_#region_id be set to null?

[stale[bot]]

This discussion has been automatically marked as stale because it has not had recent activity. It will be closed in 60 days if no further activity occurs. Thank you for your contributions.

[mobilitydataio]

This discussion has been closed due to inactivity. Discussions can always be reopened after they have been closed.