Consistency explanation/Data quality: Value 9999, Real_time data vs capacity

[frankhommers]

Hi there,

We are trying to consume some data from the API, but we have some questions.
One main question is, what is the meaning of the value 9999? Is it NULL, or MAX, or how to interpret it?
Also, we see different issues, ways of calculating metrics per stop, so we can't process this in an consistent manner.

Would it be possible to add some kind of indication per stop of the calculation method?

Here is a short outline of a few random stops:

stop_id 288e3a84-11d8-11ef-9518-3ac61a369918

This one seems to have logical data.
E.g. capacity.bicycle = num_places_available.bicycle + num_vehicles_available.bicycle
and capacity.moped = num_places_available.moped + num_vehicles_available.moped

      "capacity": {
        "car": 0,
        "moped": 25,
        "other": 0,
        "bicycle": 25,
        "scooter": 0,
        "cargo_bicycle": 0
      },
      "realtime_data": {
        "last_reported": 1717055038540,
        "status": { "control_automatic": true, "is_returning": true },
        "num_vehicles_available": {
          "moped": 1,
          "cargo_bicycle": 0,
          "bicycle": 0,
          "car": 0,
          "other": 0
        },
        "num_vehicles_disabled": {},
        "num_places_available": {
          "moped": 24,
          "cargo_bicycle": 0,
          "bicycle": 25,
          "car": 0,
          "other": 0,
          "scooter": 0
        }

stop_id 008b622a-d0a4-11ee-8b0e-065810cc8d78

Unexpected:

• The num_places_available.capacity field has value 9999, and the existence of this property seems a little awkward
• The capacity.capacity field has value 10, but the type of vehicle properties are missing from the capacity object.

      "capacity": { "capacity": 10 },
      "realtime_data": {
        "last_reported": 1717055038524,
        "status": {
          "is_renting": false,
          "is_installed": false,
          "is_returning": true,
          "control_automatic": false
        },
        "num_vehicles_available": {
          "moped": 5,
          "cargo_bicycle": 0,
          "bicycle": 0,
          "car": 0,
          "other": 0
        },
        "num_vehicles_disabled": {},
        "num_places_available": {
          "moped": 0,
          "cargo_bicycle": 0,
          "bicycle": 0,
          "car": 0,
          "other": 0,
          "capacity": 9999
        }
      }

stop_id 9ade0308-d0a6-11ee-8b0e-065810cc8d78

I like the fact that capacity.moped and capacity.bicycle exist.
Unexpected:

• The 9999 value on num_places_available

      "capacity": { "moped": 25, "bicycle": 25 },
      "realtime_data": {
        "last_reported": 1717055038557,
        "status": {
          "is_renting": false,
          "is_installed": false,
          "is_returning": true,
          "control_automatic": false
        },
        "num_vehicles_available": {
          "moped": 3,
          "cargo_bicycle": 0,
          "bicycle": 0,
          "car": 0,
          "other": 0
        },
        "num_vehicles_disabled": {},
        "num_places_available": {
          "moped": 9999,
          "cargo_bicycle": 0,
          "bicycle": 9999,
          "car": 0,
          "other": 0
        }
      }

stop_id 1f4ff66c-bdb8-11ed-b1e6-fa4fb8e2990b

Unexpected:

• Now it's not capacity.capacity but it has changed to capacity.combined. And no vehicle types anymore.
• Value '9999'

      "capacity": { "combined": 10 },
      "realtime_data": {
        "last_reported": 1717055038643,
        "status": {
          "is_renting": false,
          "is_installed": false,
          "is_returning": true,
          "control_automatic": false
        },
        "num_vehicles_available": {
          "moped": 0,
          "cargo_bicycle": 5,
          "bicycle": 4,
          "car": 0,
          "other": 0
        },
        "num_vehicles_disabled": {},
        "num_places_available": {
          "moped": 9999,
          "cargo_bicycle": 9999,
          "bicycle": 9999,
          "car": 0,
          "other": 9999
        }

stop_id 32a4709c-0ec2-11ef-b0cd-d64069e30621

I would expect num_places_available.combined to be 10, not each vehicle type invidually.

      "capacity": { "combined": 10 },
      "realtime_data": {
        "last_reported": 1717055038788,
        "status": { "control_automatic": true, "is_returning": true },
        "num_vehicles_available": {
          "moped": 0,
          "cargo_bicycle": 0,
          "bicycle": 0,
          "car": 0,
          "other": 0
        },
        "num_vehicles_disabled": {},
        "num_places_available": {
          "moped": 10,
          "cargo_bicycle": 10,
          "bicycle": 10,
          "car": 0,
          "other": 10
        }

[sven4all]

Hi Frank,

Thanks for the questions, we try to follow the MDS /stops implementation as good as possible https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/data-types.md#stops. Therefor maybe some data is not returned as you expect.

The MDS standard defines capacity per modality, in the Netherlands we do have microhubs were we would like to have a 'combined' capacity (that doesn't exists officially in MDS). That means for example that in the case of your latest example that the combination of mopeds, cargo_bicycles, bicycles and cars can be 10, so 2 cargo_bicycles, 3, bicycles and 5 mopeds or any other combination. So if there is a a combined capacity of 10, you can 10 mopeds or 10 cargo_bicycles or 10 bicycles or 10 other vehicles.

9999 is filled depending on parameters that are set by the municipality. A municipality can decide to automatically open or close a hub (control_automatic = true), manually open it (control_automatic == false and is_returning == true) or manually close it (control_automatic == false and is_returning == false). When the microhub is manually opened by the governement the num_places_available will be set to 9999 as a sort of MAX value.

So to summarize:
capacity is defined by the municipality, and control automatic / open manually or close manually are set by the governement.

num_vehicles_available is just a count of the number of vehicles in a microhub
num_places_available is a derived value based on input for capacity, how the hub should be controlled (manually or automatically) and num_vehicles_available.

Best regards,

Sven

[frankhommers]

This doesn't lead to usable consistency I guess.

Why is it sometimes capacity.capacity, sometimes capacity.combined and sometimes capacity.{vehicletype}?
Why does num_places_available.capacity exist?

I feel like the capacity.capacity and num_places_available.capacity are just wrong. Since .capacity is not a vehicletype.

From the specs you mentioned:

Field	Type	Required/Optional	Description
capacity	{vehicle_type: number}	Required	Number of total places per vehicle_type
num_vehicles_available	{vehicle_type: number}	Required	How many vehicles are available per vehicle_type at this stop?
num_vehicles_disabled	{vehicle_type: number}	Required	How many vehicles are unavailable/reserved per vehicle_type at this

[sven4all]

Hi Frank,

The "capacity": "capacity" is indeed not correct. Will try to fix that.

[sven4all]

For now a temporary fix is done, but the root cause is not found yet.

[frankhommers]

Well, I get an internal server error now :-)
https://mds.dashboarddeelmobiliteit.nl/stops