BikePoint API Clarifications

Hi folks, thank you for providing this data! I’ve read the Swagger, and have a few follow-ups:

  • Is the freshness of data returned by GET /BikePoint/{id} and GET /BikePoint identical, or could the latter return older data?
  • Is modified when any property last changed, or when the values are current as-of? I ask as 112 is currently showing as modified nearly 8 hours ago. I’m not sure whether this was when someone last used the station, or indicating the data is stale. If the former, is there a minimum interval at which data for a given station refreshes?
  • Can you confirm NbStandardBikes is the number of non-broken, non-e-bikes available for hire?
  • Can you confirm NbEmptyDocks is the number of non-broken docks in which a bike can be placed?

Many thanks!

Hello and welcome to this forum! :slight_smile:

  • GET /BikePoint/{id} and GET /BikePoint should return the same freshness of data, except that the former returns data for a specific BikePoint, and the latter returns data for all of them.
  • modified is more of a technical property from the Unified API’s database, so I’d be hesitant to ascribe too much meaning to it.
  • I can confirm that NbStandardBikes is the number of non-e-bikes available for hire.
  • I can confirm that NbEmptyDocks is the number of docks to which a bike can be returned.
  • If our system determines that a given dock is not in service, then it will not be included in the NbBikes/NbEmptyDocks/NbStandardBikes/NbEBikes counts.

Thanks for the swift reply! Although not Unified API, is the lastUpdate attribute in livecyclehireupdates.xml similarly fraught? It seems to reliably tick every minute, in contrast to the modified fields. I’ll use whatever provides the most up-to-date data, however it would be handy to have an indication of how fresh that data is.

livecyclehireupdates.xml is actually the source feed that we consume into the Unified API. In that sense, it is inherently more up-to-date than the Unified API, but it shouldn’t be a big difference. I’m not familiar with the system that generates that XML file, but the lastUpdate attribute seems to be the timestamp for when the file was generated.

I should note, however, that I don’t think we promote the livecyclehireupdates.xml feed as open data. We generally recommend using the Unified API or other feeds listed on the our open data page. Therefore, although the feed is currently publicly available, please be aware of the possibility that it may be withdrawn from public consumption in the future.

Thanks for that. Last question for the time being: if the XML feed is the source, do you know where the per-station, per-property updated timestamps come from in the Unified API response? Intuitively I’d expect every updated timestamp from /BikePoint to be the same in that case, however they differ by station. I’m yet to find a case where different properties within the same station were updated independently.

Enjoy your weekend!

It’s difficult for me to give a definitive answer to that, but having poked around the Unified API’s code a bit, it seems to me that the modified timestamp is generated by the Unified API when it notices a change to any of the properties. In other words, if someone hires a bike and the number of empty docks changes, then the modified timestamp for every property on that docking station would be updated to the current time.

You might assume it then means that the modified timestamp is the last time someone hired or returned a bike from that docking station. However, if one person were to hire a bike and someone else were to return a bike in quick succession, then the Unified API wouldn’t observe any change to the numbers and (I assume) wouldn’t generate a new timestamp.

I should disclose that I haven’t directly worked on this part of the Unified API, so I may be incorrect on some of these details, but having spent a few minutes looking at the code, this is what seems to be happening.

I hope you have a good weekend, too! :slight_smile: