We have released a data specification to enable the MaaS ecosystem in NSW. Learn more and provide your feedback now!

Colour Stripe
Mobile Colour Stripe

Tips and tricks

Some of the data not making sense? The data we provide as Open Data is often from an operational system. A lot of work happens in the background to cleanse and make the data better, but there are still a lot of quirks.

We have learned a lot from third party app developers' questions and have put together some tips and tricks that will help you troubleshoot.

HTTP standards

  • While we try our best to adhere to standards, sometimes this is not always possible
  • Some APIs return a Last-Modified header and timestamp in the HTTP response. If you send this timestamp in an If-Modified-Since header, you may not get back an HTTP status of 304 Not Modified. Instead, in some cases, you may use the HEAD HTTP method to retrieve the Last-Modified timestamp without retrieving the data

OAuth 2 authentication
The previous version of the gateway allowed a non-standard security protocol for obtaining OAuth bearer tokens. The gateway was allowing the grant type and scope to be passed in as a URL query string. The current version of the gateway has closed this loophole and now you need to ensure these parameters are in the post body.

Real-time Public Transport

  • The GTFS-Realtime data (real-time GTFS) does not include the scheduled services that are not realtime. Use the GTFS bundle or TXC bundle for all the scheduled services. The GTFS bundle and the TXC are not compatible with realtime
  • If you are developing a real-time app, use scheduled data (Timetables API) as a fall back
    Real-time data should be indicated in the app clearly. Real-time isn’t always accurate! GPS issues and reporting issues can affect things
  • PTIPS real time files are updated every 10 to 15 seconds. It is recommended that you update every 15 seconds
  • PTIPS (buses) feed special attributes:
    • 85th Anniversary Buses = 1
    • Free wi-fi = 2
  • Real-time datafeeds include:
    • Sydney Trains
    • Buses
    • Ferries. Does not include Manly Fast Ferries and Captain Cook Cruises. ie Sydney Ferries only
    • NSW Trains and Regional Services – Trains and Coaches
  • Future projections for data feeds might not necessarily match between GTFS and real-time since they come from different systems. Some systems require the feeds to have at least 100 days of data in the future while others have a set number of days. We recommend that you always use the latest available bundles and files to ensure that the data is up to date and reliable.

Service Alerts

  • Service alerts are available for Sydney Trains only.
  • Alerts for all modes can be found in our Public Transport - Realtime Alerts dataset, which we encourage you to use.
  • If you require alerts in GTFS-R format then we advise you to use the third party feed which is generated from the Transportnsw.info status pages and gets scraped and published.
  • Sydney Ferries has a service alerts feed but it provides limited information.
  • How to set up service alerts correctly: we recommend you use the Trip Planner API info endpoint to get service alerts. This will make your app more efficient and prevent the need to clean up duplicate alerts if using multiple feeds.

Sydney Trains

  • In the Sydney Trains real-time feed, RTTA_DEF and RTTA_REV should be excluded by app developers and not presented to customers, they are non-revenue services
  • Watch out when applying trip_headsign and stop_headsign correctly so “empty trains” do not appear
    For app developers who do not know the Sydney Trains network, there is a loop. Please check the GTFS Specifications and apply block_id to join services
  • NSW Trains and Sydney Trains need to have some services excluded to avoid duplication, see NSW Trains technical documentation for more info
  • There is a character limitation on headsigns so there needs to be a transformation
  • Extra stops are presented in the Sydney Trains operation as they include passing stops in trips that are flagged as no set down/no pick up, and should not be passed on to customers. The stops are not included at all in the Complete GTFS, as they effectively aren’t in use
  • Shapes do not always match trips 100%. There may be missing stops at the beginning of the shape or extra stops at the end of the shape
  • To determine the train delay information for scheduled services (ie. have a trip schedule_relationship of SCHEDULED), only a delay field is provided. You should obtain the scheduled arrival time and departure time from stop_times.txt (in the GTFS-static for realtime dataset) and add the delay seconds. Negative value denotes the vehicle is expected to arrive or depart ahead of schedule. Match each stop_time_update by the stop_id provided in the realtime and static feeds.
  • To determine the train delay information for replacement services (ie. have a trip schedule_replacement of REPLACEMENT), these include a timestamp for arrival and departure. Delay field is also provided for stops which were already part of the schedule (in stop_times.txt) and have not been skipped, added or replaced.
  • To figure out the amount of time needed for connections please have a look at the following document, Connections Guide RSDO 2017 Timetable.pdf

GTFS Update information

Sydney Trains / RTTA

  • GTFS updates daily around 01:30
  • will contain regular changes of trip/calendar keys
  • in most cases needs to be processed as soon as possible
  • shapes can change without the shape ID changing
  • The timetable ID and version ID of each weekday/weekend train plan is used as a component in GTFS service/trip IDs generated by RTTA. Any single change in a train plan will increment the version ID meaning all related trip/service IDs will change
  • The current behaviour in RTTA is that the startDate increments to be at minimum the current day, so for the current active daily working timetable will change daily. The GTFS bundle keying now changes daily at minimum of 5 days a week.
  • The calendar service_id's are constructed using the format {timetableId}.{timetableVersionId}.{dopRef}-{startDate}
  • The trip_id's are constructed using the format {tripName}.{serviceId}.{setType}.{numberOfCars}.{tpsTripId}

GTFS-realtime Specification - Sydney Trains:

  • The current official GTFS-realtime specification is not compatible with the Sydney Trains GTFS-realtime feed. REPLACEMENT has been removed from the official GTFS-realtime specification more than two years ago but the Sydney Trains feed still contains it.
  • Vehicle Occupancy (for buses) is also now included
  • To download the file, right click on the following link and select "Save link as..." - GTFS realtime proto file

Buses / PTIPS

  • GTFS updates daily (typically around 21:30)
    has key consistency over time - the key of a trip appears to be linked to the definition of it, so if the route of a bus changes temporarily then a new trip ID will be assigned to it
  • will periodically have new sets of trips added/removed from it as operators upload new data - sometimes only 1-2 days before the added trips will commence operation (so updating regularly is important, but taking a few hours to process updates is fine)
  • TfNSW proto file - describes the tfnsw vehicle descriptor extension 1999 that includes aircond and wheelchair accessibility (***after downloading please change the file extension to ".proto", ie. remove "_.txt")
  • Proto File for NLR and Metro - download the proto file for Newcastle Light Rail and Metro

Sydney Light Rail

  • GTFS updates infrequently as it is a manual process
  • Has good key consistency over time
  • Blocking was added (since 26 July 2016)
  • Route_short name now populated as L1 (instead of previously being combined into the route_long name)
  • Platform_code is populated. Light Rail stops do not have platform number displayed on the ground, but these have been added to indicate a direction for each. 1 = Toward central, 2 = towards Dulwich hill

Sydney Ferries/HCF

  • GTFS updates daily around 05:15
  • trip IDs seem mostly consistent over time
  • calendars can change on a daily basis (particularly around public holidays due to limitations of FOCIS timetabling)

NSW TrainLink/4Trak

  • GTFS updates daily around 00:30
  • bundle covers the next 35 days of daily working timetable
  • each trip is defined with a unique ID for each day it will operate on, so there is long term key consistency 34 days in advance

Third Party supplied data which may help:

Live Traffic data feed

  • There are no set intervals for updates, the data feed is updated whenever something changes

Need more help?

Back to top