File description: specify endpoint timeout

[AntoineAugusti]

What problem does your proposal solve? Please begin with the relevant issue number. If there is no existing issue, please also describe alternative solutions you have considered.

Some GBFS feeds respond slowly to HTTP requests, making it difficult for consumers who must increase timeouts or adopt retry strategies.

What is the proposal?

Specify that HTTP responses SHOULD happen in under 1 second. Consumers should be able to set 1 second as a timeout for HTTP requests.

Is this a breaking change?

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

Which files are affected by this change?

All

[richfab]

Thank you @AntoineAugusti for raising this important issue 🙏 I've edited your description to reflect that your suggestion is to require a timeout of 5 seconds (MUST) and not to make a recommendation (SHOULD).

@AntoineAugusti and community, what is your opinion on these questions:

1. How long should the timeout be and why? It would be interesting to do a quick analysis of the current latency of the feeds in systems.csv for the realtime endpoints (vehicle_status and station_status). Is anyone from the community able/willing do this? If not, @davidgamez, does our team have the capacity to do this analysis?

2. Recommendation or requirement? In the interest of increasing GBFS open data and its reuse, is it more beneficial to make the timeout a requirement or a recommendation? In the case of a requirement, the GBFS validator would return feeds that exceed the timeout as invalid.

What do data consumers think (@cmonagle @futuretap @matt-wirtz @tdelmas @testower)? Just as an example: for Google Maps, the latency to retrieve the data is a requirement and the duration is 30 seconds (source).

[tdelmas]

If it's a MUST, then it's a breaking change.

As a consumer, this change is welcomed.

But maybe too strong for the producers and may drive them away from the specification? What about MUST in less than 30s, SHOULD in less than 5s ? And in a future version, reducing those values?

[richfab]

I'm reopening this issue. It's part of the MobilityData team's to-do list to analyze the current latency of existing GBFS feeds. cc @emmambd

[richfab]

Our team (MobilityData) has analyzed the latency of the feeds in systems.csv. Thanks @merjakaj for your contribution too!

The analysis is based on 1 daily pull of the largest endpoints (station_status and vehicle_status/free_bike_status) for about one week, and considers the maximum latency observed over these ~7 pulls.

percentile	max latency (in sec)
0.5	0.3
0.75	0.5
0.9	1.0
0.95	1.8
0.99	4.0
0.999	9.5

Interpretation:

• 90% of feeds in systems.csv return a response in 1 second or less.
• 99% of feeds return a response in 4 seconds or less.

@AntoineAugusti, @tdelmas, or anyone else, would you like to pursue the proposal to include a maximum latency recommendation (i.e., "HTTP responses SHOULD happen in less than 1 second") in v3.1-RC2, which will be released this month?

If so, the vote must be opened this week for adoption before the end of the month. I'd be happy to help with the voting process.

Thanks 🙏

[AntoineAugusti]

I have updated the PR with a different wording https://github.com/MobilityData/gbfs/pull/715/commits/b071385fff07c3401f7c179b59b09b52f3db3729

[richfab]

Thank you to @AntoineAugusti and @tdelmas who contributed to this proposal 🙏

I hereby call a vote on this proposal. Voting will be open for 10 full calendar days until 11:59PM UTC on Friday, May 23.

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.

Governance on the spec change process can be found here.

[tdelmas]

+1 from @Fluctuo

[futuretap]

+1 from Where To? / FutureTap

[keijipoon]

+1 from OpenStreet

[leonardehrenfried]

+1 OpenTripPlanner

[richfab]

This vote has now closed, and it passes!

Votes in favor:

• Fluctuo (consumer)
• Where To? / FutureTap (consumer)
• OpenStreet / Hello Cycling (producer)
• OpenTripPlanner (consumer)

There were no votes against.

~~This change will be part of the next MINOR Release Candidate, planned this month, as per the version release cycle in the governance.~~

Thank you all for your involvement in the GBFS spec 🙏

[richfab]

EDIT: This change will be included in v3.2-RC scheduled for November 2025. Indeed, the governance states that the voting deadline is April 30th for the MINOR Version Release of May. We apologize for this change.

[davidgamez]

Still relevant.