Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Passenger Services Mode for new commuter shuttle fields #927

Open
wants to merge 4 commits into
base: dev
Choose a base branch
from
Open

Update Passenger Services Mode for new commuter shuttle fields #927

wants to merge 4 commits into from

Conversation

matthewmarwedel
Copy link

@matthewmarwedel matthewmarwedel commented Feb 3, 2025 •
edited
Loading

name: Matthew Marwedel, SFMTA @matthewmarwedel supported by @Mu-yi-Zhou, @monachiu, and @alexdemisch (SFMTA)
about: Suggest changes to MDS to support commuter shuttles within passenger services mode
title: Adding new fields to Passenger Services mode to support Commuter Shuttles

Explain pull request

SFMTA would like to update the passenger services mode in MDS to include support for commuter shuttles. Most fields in passenger services match the needs of commuter shuttle (such as stop_id, lat, long, etc.) We would like to add three additional fields for commuter shuttle use. These fields would be optional (required for commuter shuttle use case, but optional as an MDS field). When those fields are implemented, we would like to add support to integrate GTFS endpoints to passenger services mode to track shuttle routes.

Initial pull request includes:
adding service_id field to [Events, Trips, Telemetry]
adding route_id field to [Events, Trips, Telemetry]
adding stop_sequence field to [Events, Trips, Telemetry]

Once this is implemented we will build on the pull request for the following:
adding GTFS integration in MDS for route_id and service_id

Is this a breaking change

A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint).

  • No, not breaking

We would like to add some optional fields fields to passenger services mode along with an optional Schedule endpoint in the future to support commuter shuttles. Existing code will continue to function.

Impacted Spec

Which spec(s) will this pull request impact?

  • agency
  • provider
  • policy

Additional context

N/A

@matthewmarwedel
Update data-types.md for new commuter shuttle fields
7d1d14e 
adding route_id field to [Events, Trips, Telemetry]
adding stop_sequence field to [Events, Trips]

Signed-off-by: Matthew Marwedel <[email protected]>
@matthewmarwedel matthewmarwedel requested a review from a team as a code owner February 3, 2025 19:33
@CLAassistant
Copy link

CLAassistant commented Feb 3, 2025 •
edited
Loading

CLA assistant check
All committers have signed the CLA.

@schnuerle schnuerle added enhancement New feature or request Provider Specific to the Provider API Agency Specific to the Agency API Policy Specific to the Policy API labels Feb 4, 2025
@schnuerle
Copy link
Member

schnuerle commented Feb 7, 2025 •
edited
Loading

Some items to consider, based on OMF staff discussion with SFMTA staff.

  1. Should these fields be in the data types for all modes, or in just Passenger Service
  2. Potentially add a service_id to better describe the route id
  3. Could add another field route_name, or reference it only in external endpoint in Schedule
  4. Maybe add stop_sequence to telemetry too
  5. Policy and Geography may not need route and stop info, geographic policies should be sufficient
  6. A draft of what's in Schedule would be useful to see, like route info, stop sequence, calendar (days of week), calendar dates (month/day of operation), including exceptions
    • GTFS could be the solution here. Would need to make sure route_id, service_id is in GTFS Schedule format, and new GTFS URL (info) field in MDS Trips. GTFS_Stop_id may be needed in events too.
  7. stop sequence might not need to go in Trips
  8. Might need a gtfs_url in the providers.csv file to track new operator IDs
  9. Operators would generate a unique device_id UUID, but can also use VIN, license plate, USDOT id, etc fields.

@schnuerle schnuerle added this to the 2.1.0 milestone Feb 10, 2025
This was linked to issues Feb 10, 2025
Add fixed Route Identifier to trips endpoint, geography API and policy API #919
Open
Support for fixed-route services #922
Open
@schnuerle
Copy link
Member

We will be discussing this at this week's MDS Working Group meeting. Please review and leave your comments and use cases and questions ahead of time.

This was referenced Feb 10, 2025
Open
Open
@matthewmarwedel
Copy link
Author

matthewmarwedel commented Feb 12, 2025 •
edited
Loading

Hi all,

Replying to earlier discussion points with my thoughts

  1. Should these fields be in the data types for all modes, or in just Passenger Service
    I think there is a lot of potential for other modes and the new fields should be for all modes. I would love to hear thoughts from other OMF members
  2. Potentially add a service_id to better describe the route id
    service_id and route id will both be needed to show what the route is and what times it runs. These can reference routes.txt, calendar.txt, and calendar_dates.txt in GTFS.
  3. Could add another field route_name, or reference it only in external endpoint in Schedule
    Referencing routes.txt in GTFS may be the best option here, no route_name field needed
  4. Maybe add stop_sequence to telemetry too
    Yes, add stop_sequence to Telemetry
  5. Policy and Geography may not need route and stop info, geographic policies should be sufficient
    Policy and Geography endpoints don't need the new fields (stop_sequence, service_id and route id)
  6. A draft of what's in Schedule would be useful to see, like route info, stop sequence, calendar (days of week), calendar dates (month/day of operation), including exceptions
  • GTFS could be the solution here. Would need to make sure route_id, service_id is in GTFS Schedule format, and new GTFS URL (info) field in MDS Trips. GTFS_Stop_id may be needed in events too.
    Use routes.txt, calendar.txt, and calendar_dates.txt in GTFS as the schedule with route_id and service_id matching GTFS format. I'm not sure if that alone is enough to connect MDS to the GTFS spec, if not a gtfs_url field may be needed in [Trips, Events, Telemetry]. I'm also not sure if the gtfs_url field would be needed in all of them. Would love insight from OMF community on this.
  1. stop sequence might not need to go in Trips
    Not sure, depends if stops are in MDS or GTFS. For now, it seems like stop sequence will stay in MDS and GTFS stops won't be needed.
  2. Might need a gtfs_url in the providers.csv file to track new operator IDs
    Yes, add a gtfs_api_url field to the MDS provider list
  3. Operators would generate a unique device_id UUID, but can also use VIN, license plate, USDOT id, etc fields.
    This sounds good.

@matthewmarwedel
Update data-types.md
05b058f 
Added service id and GTFS integration for to events, trips, and telemetry.

Added stop_sequence to Telemetry.

Signed-off-by: Matthew Marwedel <[email protected]>
@matthewmarwedel
Update providers.csv with gtfs_api_url
3237019 
Added gtfs_api_url column with blank values for now.

Signed-off-by: Matthew Marwedel <[email protected]>
@matthewmarwedel
Update providers.csv
e829e60 
Corrected some comma errors

Signed-off-by: Matthew Marwedel <[email protected]>
@matthewmarwedel
Copy link
Author

I added a new commit to the pull request finalizing a few changes discussed above.

  • stop_sequence was added to Telemetry
  • service_id was added to Events, Trips, Telemetry
  • GTFS integration support was added to documentation in Events, Trips, Telemetry
  • gtfs_api_url was added to providers.csv

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
Agency Specific to the Agency API enhancement New feature or request Policy Specific to the Policy API Provider Specific to the Provider API
Projects
None yet
Milestone
2.1.0
Development

Successfully merging this pull request may close these issues.

Support for fixed-route services Add fixed Route Identifier to trips endpoint, geography API and policy API
3 participants
@matthewmarwedel @CLAassistant @schnuerle