Discovery endpoint for GBFS urls per geography/region

[dirkdk]

About me

I'm senior engineering manager at Spin for all Partner integrations including compliance. In that role I have been on the OMF Technology council since its inception.

What is the issue and why is it an issue?

Consumer apps, partners and cities need to guess urls for GBFS feeds per geography (or region). Sometimes these urls are listed in https://github.com/NABSA/gbfs/blob/master/systems.csv, but this is hard to maintain and providers rarely update it themselves.

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

Every mobility provider with a GBFS feed would have a discovery endpoint like gbfs_geographies.json

Data could be formatted like this:

{
  "last_updated": 1434054678,
  "ttl": 0,
  "version": "1.1",
  "data": {
    "countries": [
      {
        "name" : "United States",
        "iso_alpha_3": "USA", 
        "geographies": [
          {
            "name": "San Francisco",
            "url": "https://www.mobility_provider.com/gbfs/1/san_francisco/gbfs"
          },
          {
            "name":"Denver",
            "url":"https://www.mobility_provider.com/gbfs/1/denver/gbfs"
          }
        ]
      }
    ]
  }
}

Because GBFS urls in general contain a version, I'm wondering if we should list each individual version per geography. For Spin we don't have geographies with different versions than others. All our GBFS versions are supported for all published geographies. So I'm inclined to say no and just have 1 url per geography. If the community feels we should, then the format could be like this:

{
  "last_updated": 1434054678,
  "ttl": 0,
  "version": "1.1",
  "data": {
    "countries": [
      {
        "name" : "United States",
        "iso_alpha_3": "USA", 
        "geographies": [
          {
            "name": "San Francisco",
            "urls": [
              {
                "version": "2.1",
                "url":"https://www.mobility_provider.com/gbfs/2.1/san_francisco/gbfs"
              },
              {
                "version": "2.2",
                "url":"https://www.mobility_provider.com/gbfs/2.2/san_francisco/gbfs"
              }
            ]
          },
          {
            "name": "Denver",
            "urls": [
              {
                "version": "2.1",
                "url":"https://www.mobility_provider.com/gbfs/2.1/denver/gbfs"
              },
              {
                "version": "2.2",
                "url":"https://www.mobility_provider.com/gbfs/2.2/denver/gbfs"
              }
            ]
          }
        ]
      }
    ]
  }
}

Is your potential solution a breaking change?

• [ ] Yes
• [x] No
• [ ] Unsure

[mplsmitch]

I like this idea because it would make discovery easier for feed consumers.

To simplify implementation I think this could be a single endpoint per provider, in other words instead of having an instance for each version or each city, there could be a single file that would point to the gbfs.json files for the most recent version available. If there are multiple version available that's already handled by gbfs_versions.json.

It's true that URLs typically contain the version but it would be better if the version and city were dropped in favor of a single stable URL for the provider that wouldn't change with new versions or if a city went offline.

For example: https://gbfs.spin.pm/api/gbfs/gbfs_geographies.json vs https://gbfs.spin.pm/api/gbfs/vX/city/gbfs

This all makes sense for a company like Spin that is both owner and operator but I'm curious how it would work for companies that support lots of independent operators that aren't necessarily related to each other? Examples would be Bcycle or Social Bicycles.

[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.

[mplsmitch]

I've done some work on this and I'd like to get some feedback before moving to at PR for inclusion in v3.0. As @dirkdk said above, adding this endpoint would enable greater discovery of data sets and support cataloging of data sets in systems.csv.

In order for this to work, we need to clarify what constitutes a system (or data set) in GBFS. This has come up repeatedly in the past, most recently in #353. While many shared mobility services operate at a national or multinational scale, GBFS data sets describe shared mobility services as individual systems bounded by a local geography which can be further divided into regions. This nomenclature has not been clearly defined in the specification, causing confusion about what constitutes a “system” and “region”. Defining these terms in the specification would provide clarity to data set publishers.

Definitions to be Added to the Specification:

System: GBFS data sets represent individual shared mobility systems bounded by a local geography. Systems SHOULD be defined by the geographic area in which vehicles are permitted to operate. Each system as represented by a single GBFS data set MUST have a unique system_id. Systems may span municipal or political boundaries in cases where vehicles are permitted to operate across multiple jurisdictions. If a user could reasonably expect to be able to rent a vehicle in one jurisdiction and return it in another, those jurisdictions would be considered a single system.

Region: Regions as defined in system_regions.json are geographic areas defined within a shared mobility system. Regions may be defined for any purpose, for example political jurisdictions, neighborhoods or economic zones.

Proposal for New Discovery Endpoint: gbfs_systems.json

File Name	Required	Defines
gbfs_systems.json	YES	A list of all systems for which GBFS data sets are published by the provider. This file SHOULD be published at a single stable URL, for example: https://www.example.com/gbfs/gbfs_systems

gbfs_systems.json

Filed Name	Required	Type	Defines
countries	Yes	Array	An array of countries in which the feed publisher publishes feeds. Each element in the array is an object with the keys below.
countries[ ].country_name	Yes	String	Name of the country in which the system(s) are located.
countries[ ].country_code	Yes	String	ISO 3166-1 alpha-2 code designating the country where the system is located. For a list of valid codes see here.
countries[ ].systems	Yes	Array	An array of systems within the country where feeds are published. Each element in the array is an object with the keys below.
systems[ ].state_province	Conditionally REQUIRED	String	State or province the system is located in. This field is REQUIRED for countries that include states or provinces.
systems[ ].city	Yes	String	Principal city in which the system is located.
systems[ ].discovery_url	Yes	URL	A fully qualified URL for the system’s gbfs.json auto-discovery file for the most current implemented version of the specification.

Example gbfs_systems.json file

{
  "last_updated":1434054678,
  "ttl":0,
  "version":"2.3",
  "data":{
    "countries":[
      {
        "country_name":"United States",
        "country_code":"US",
        "systems":[
          {
            "state_province":"California",
            "city":"San Francisco",
            "discovery_url":"https://www.example.com/gbfs/2_3/san_francisco/gbfs"
          },
          {
            "state_province":"Colorado",
            "city":"Denver",
            "discovery_url":"https://www.example.com/gbfs/2_3/denver/gbfs"
          }
        ]
      },
      {
        "country_name":"France",
        "country_code":"FR",
        "systems":[
          {
            "city":"Paris",
            "discovery_url":"https://www.example.com/gbfs/2_3/paris/gbfs"
          },
          {
            "city":"Roubaix",
            "discovery_url":"https://www.example.com/gbfs/2_3/roubaix/gbfs"
          }
        ]
      }
    ]
  }
}

[testower]

I think this is very sensible. If the specification was lenient enough to also allow multiple systems per geography then this could even be used for aggregations across operators like we do at Entur. Would love for that "global" overview to be part of the spec rather than something custom that we do.

[josee-sabourin]

Hi all! We talked about this during the Developers' Workshop, see details here - we wanted to let you know that we are working on the issue and will provide an update soon.

[dirkdk]

Hi all! We talked about this during the Developers' Workshop, see details here - we wanted to let you know that we are working on the issue and will provide an update soon.

thanks! really exciting

[nighthawk]

This would be great to have!

From a consumer perspective, I encourage to add an unambiguous way of identifying cities, such as providing a polygon or a geo coordinate. If it's just a string, you might end up with ambiguous situations if there are multiple cities of that name in the country (e.g., "Neumarkt" or "Frankfurt" in Germany) and some cities that are referred to in multiple ways ("Minnesota" / "Minnesota-St. Paul") or multiple languages ("Biel", "Bienne", "Biel / Bienne").

[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.

[josee-sabourin]

Closing this to ensure all discussion stays in #462