Multi Region

Sean Barbeau edited this page Oct 21, 2015 · 103 revisions

Want to launch the OneBusAway mobile apps for iPhone, Android, Windows Phone, Windows 8) in your city? You're in the right place!

Creating a new OneBusAway region

TL;DR - Here are the high-level steps you'll need to take to launch the OneBusAway mobile apps in your area:

  1. Get your transit data in the GTFS format
  2. Have an AVL system that produces arrival estimates (Note: there is some work going on to remove this requirement - contact us if you're interested, and also check out the TransiTime project, which can be used to generate arrival times from GPS data)
  3. Implement a GTFS-realtime or SIRI real-time data feed (We also support other formats)
  4. Set up a OneBusAway server, and add the API keys for the mobile apps (see this page for the API keys and details).
  5. Do some quality-control testing of arrival times
  6. Request to be added as a OneBusAway region - you can send an email to the OBA Developers Group requesting to be added as an experimental region (see the next section). You'll need to provide us with some basic information about your OneBusAway server/region - see the "Instructions" tab on this Google Doc spreadsheet for details. Or, just email the developers group with any questions.

Experimental vs. production regions

Experimental regions

We support experimental regions in the OneBusAway iOS and Android applications. These are regions that may not yet be ready for prime-time, but are in some stage of development. For users to see experimental regions in the app, they need to go to the Settings and enable "Experimental regions". This feature makes it easier for users to test a new region without needing to enter a custom API URL into the apps.

To be added as an experimental region, the server maintainer needs to email a request to the onebusaway-developers mailing list. If there are no objections, then the region is added as experimental.

Production regions

We have a higher bar for on-boarding "production" regions, which are available in all the OneBusAway apps by default (iOS, Android, Windows Phone, Windows 8), and featured on http://onebusaway.org. This is to help protect the OneBusAway brand, especially related to user reviews in app stores online.

To be added as a production region, a region must first be added as an experimental region following the above process. If everything works well, the server maintainer can submit a request to the onebusaway-developers list to be added as a production region. The request will be granted at the discretion of the board if the following conditions are met:

  • OneBusAway server has been operational for 1 month (30 days) with server available for 99.5% of the time (not necessarily real-time data, but at least schedule data must have been provided).
  • Sufficient real-time information is provided for major portions of the region. We've left this up to the discretion of the OneBusAway Board, since there are situations where an OneBusAway region may have real-time information for the major agency in the region, but may also want to include schedule data for connected agencies (who may not have real-time info) for the convenience of riders. In other words, we don't want to discourage adding new agencies to a region simply because real-time info isn't available for that agency.
  • On-the-ground tests of real-time arrival accuracies must be performed, to ensure quality data will be provided to users. We're leaving the exact parameters to the OneBusAway server maintainer, on the honor system.
  • OneBusAway apps must be pre-verified to function with the server URL (this should happen as part of being an experimental region). OneBusAway server must accept the original Android, iOS, Windows Phone, and Windows 8 app API keys (as defined here.
  • OneBusAway server must support the original OneBusAway real-time and discovery APIs (as exist in the current onebusaway-api-webapp project). (The OneBusAway apps may be modified to support SIRI in the future, at which point the SIRI API would also be acceptable for real-time info.)
  • OneBusAway server maintainer must commit to maintaining the GTFS schedule data (including building and deploying a new bundle for schedules changes) while the region is in production.

We also strongly suggest that OneBusAway server maintainers notify users of planned maintenance and service outages via service alerts (from within the OneBusAway admin console - see this page for instructions) and social media (including the Twitter feed shown in the app), if available, and that OneBusAway server maintainers update their server software within 3 months following the release of a new version.

For removing production and experimental regions from the apps - after a complaint is lodged, the OneBusAway Board would contact the maintainers of that region and give them one week to respond. After considering the situation, removing the region would be at the discretion of the board. We don't envision this happening, as long as OneBusAway servers are actively maintained.

Implementation details of OneBusAway Multi-region

If you're interested in the nitty-gritty, below are the technical details of how the OneBusAway Multi-region project works.

Note - if you're interested in how multiple areas of Puget Sound (e.g., King County Metro, Sound Transit) are supported within the Puget Sound OneBusAway instance, see the OBA Puget Sound Architecture page

Prior to August 2013, the official OneBusAway (OBA) Android, iPhone, and Windows Phone mobile apps only functioned in Puget Sound.

New OBA server instances had started to emerge in cities such as Tampa and Atlanta, and we wanted to make the apps available in cities outside of Puget Sound.

To extend the existing official OBA mobile apps to new cities, the apps were modified to support multiple “regions” - using this design Puget Sound is one region, while Tampa another, etc.

The OneBusAway Multi-region initiative with full support for multiple regions on the Android, iPhone, Windows Phone, and Windows 8 apps officially launched in September 2013!

To support “multi-region” apps, we are using a centralized OBA Server Directory to hold a list of OBA servers. The contents of this directory is made available to mobile apps via the "Regions API".

Here is a high-level view of the architecture, including the mobile app, Regions API, and OneBusAway regional servers:

OBA Multiregion Architecture

Google Doc Drawing for above image is here.

This architecture allows apps to get a list of all available OBA servers from a centralized resource, but then interact with each regional OBA server directly in a de-centralized manner.

The below diagram shows the detailed protocol that takes place for a mobile device to discover and retrieve information from regional servers:

OBA Multiregion Protocol

Google Doc Drawing for above image is here.

This document is intended to outline the expected roles of two groups:

  • OBA Server Admins - More information on how OBA Server Admins are expected to use this directory, and configure their OBA instances, can be found in the “OBA Server Admins - Setting up a new OneBusAway region” section in this document.
  • App Developers - More information on how mobile apps are expected to use this directory can be found in the “Regions REST API" and "Existing Apps - Expected Changes” sections in this document.

OBA Region Admins - Setting up a new OneBusAway region

At this point, you should have a OneBusAway server up and running. If you don't, see the Developer Guide for how to do this. If you don't know what a OneBusAway server is, checkout our "Getting Started" guide.

We are using a Google Doc spreadsheet as the OBA Server Directory so that we can easily add new servers to the mobile apps. This data is then exported to JSON and XML so it can be retrieved by the mobile apps from the Regions API. See Tab 2 - "Instructions" for a description of the data you'll need to provide for your region (including required formatting of the data for each field). See Tab 1 - "OBA Directory" for examples of the data provided by other OBA regions.

Please contact the OneBusAway Developers group (onebusaway-developers@googlegroups.com) with the required information so we can add your server to the directory. You'll first be added as an "experimental" (i.e., beta) region, and then if all goes well you can move to production (more details on this process here).

As an OBA Server Admin, you will need to give the existing official OBA apps access to your server by adding their API keys. Additionally, you will likely want to distribute API keys to new apps that are being developed in your region. Instructions for these two processes are found on the API Webapp Configuration Guide.

We have designed this architecture to direct most user feedback to OBA Server Admins, since reported issues are typically data-related. If you receive user feedback that is related to the mobile app itself (e.g., it crashes on certain devices) you should forward this information to the respective mobile app developer:

It should be noted that updates to the OBA Server Directory are NOT immediately reflected in the Regions REST API response. It may take up to one week for mobile applications to be updated with new regional server information, and therefore we strongly suggest that OBA Server Admins have contingency plans in place for major changes to the server (e.g., actively maintain the original server address as long as possible if the URL changes to a new server name). If there is an emergency and you require an change that must be immediately reflected in the mobile apps, please email the OneBusAway Developers list (onebusaway-developers@googlegroups.com) with this request.

Regions REST API

The Regions REST API serving up multi-region data is hosted at the server regions.onebusaway.org.

The contents of the OBA Server Directory is served in both JSON and XML format at the URLs:

No API keys are required to access the OBA Server Directory REST API.

Release notes

  • v3 - (.../regions-v3.json, .../regions-v3.xml) - Dec. 5, 2013 - Added experimental servers. To use this API, apps must screen out regions with experimental set to true by default, and provide the user a setting to "opt-in" to using experimental regions.
  • v2 - (.../regions.json, .../regions.xml) - April 3, 2013 - Initial release of the Regions API. Apps that do not screen out experimental regions should continue to use this API until they support a user option to opt-in to support experimental servers.

Sample Request (JSON)

http://regions.onebusaway.org/regions-v3.json

Sample Response(JSON)

{
    code: 200,
    text: "OK",
    version: 3,
    data: {
           list: [
                  {
                      siriBaseUrl: null,
                      obaVersionInfo: "1.0.8-SNAPSHOT|1|0|8|SNAPSHOT|677fd69e95aa20551bfa5e13c11bd02a2558ffe3",
                      supportsSiriRealtimeApis: false,
                      language: "en_US",
                      twitterUrl: "http://mobile.twitter.com/OBA_tampa",
                      supportsObaRealtimeApis: true,
                      bounds: [
                               {
                                   lat: 27.976910500000002,
                                   latSpan: 0.5424609999999994,
                                   lon: 82.445851,
                                   lonSpan: 0.576357999999999
                               }
                              ],
                      supportsObaDiscoveryApis: true,
                      contactEmail: "onebusaway@gohart.org",
                      stopInfoUrl: null,
                      active: true,
                      facebookUrl: "",
                      obaBaseUrl: "http://api.tampa.onebusaway.org/api",
                      id: 0,
                      experimental: false,
                      regionName: "Tampa"
                  },
                  {
                      siriBaseUrl: null,
                      obaVersionInfo: "",
                      supportsSiriRealtimeApis: false,
                      language: "en_US",
                      twitterUrl: "http://mobile.twitter.com/oba_pugetsound",
                      supportsObaRealtimeApis: true,
                      bounds: [
                               {
                                   lat: 47.221315,
                                   latSpan: 0.33704,
                                   lon: -122.4051325,
                                   lonSpan: 0.440483
                                },
                                {
                                   lat: 47.5607395,
                                   latSpan: 0.743251,
                                   lon: -122.1462785,
                                   lonSpan: 0.720901
                                },
                                {
                                   lat: 47.556288,
                                   latSpan: 0.090694,
                                   lon: -122.4013255,
                                   lonSpan: 0.126793
                                },
                                {
                                   lat: 47.093563,
                                   latSpan: 0.320892,
                                   lon: -122.701637,
                                   lonSpan: 0.55098
                                },
                                {
                                   lat: 47.5346090123,
                                   latSpan: 0.889378024643,
                                   lon: -122.3294835,
                                   lonSpan: 0.621109
                                },
                                {
                                   lat: 47.9747595,
                                   latSpan: 1.336481,
                                   lon: -122.8512,
                                   lonSpan: 1.0904
                                },
                                {
                                   lat: 47.6204755,
                                   latSpan: 0.014397,
                                   lon: -122.335392,
                                   lonSpan: 0.00635600000001
                                },
                                {
                                   lat: 47.64585,
                                   latSpan: 0.0669,
                                   lon: -122.2963,
                                   lonSpan: 0.0802
                                },
                                {
                                   lat: 47.9347358907,
                                   latSpan: 0.68796117128,
                                   lon: -121.993246104,
                                   lonSpan: 0.784555996061
                                }
                              ],
                      supportsObaDiscoveryApis: true,
                      contactEmail: "onebusaway@soundtransit.org",
                      stopInfoUrl: "http://stopinfo.pugetsound.onebusaway.org",
                      active: true,
                      facebookUrl: "https://www.facebook.com/pages/OneBusAway/216091804930",
                      obaBaseUrl: "http://api.pugetsound.onebusaway.org/",
                      id: 1,
                      experimental: false,
                      regionName: "Puget Sound"
                   },
                   {
                      siriBaseUrl: "http://bustime.mta.info/api/",
                      obaVersionInfo: "",
                      supportsSiriRealtimeApis: true,
                      language: "en_US",
                      twitterUrl: "http://mobile.twitter.com/nyctbusstop",
                      supportsObaRealtimeApis: false,
                      bounds: [
                                {
                                   lat: 40.707678,
                                   latSpan: 0.4093900000000019,
                                   lon: -74.01768100000001,
                                   lonSpan: 0.4686659999999989
                                },
                                {
                                   lat: 40.8192825,
                                   latSpan: 0.228707,
                                   lon: -73.89908199999999,
                                   lonSpan: 0.23146799999999246
                                } 
                              ],
                      supportsObaDiscoveryApis: true,
                      contactEmail: "MTABusTime@mtahq.org",
                      stopInfoUrl: null,
                      active: true,
                      facebookUrl: "https://www.facebook.com/pages/MTA-New-York-City-Transit/232635164606",
                      obaBaseUrl: "http://bustime.mta.info/",
                      id: 2,
                      experimental: false,
                      regionName: "MTA New York"
                   },
                  {
                      siriBaseUrl: http://oba.mobilitylab.org/nextgen/api/,
                      obaVersionInfo: "1.1.11-SNAPSHOT|1|1|11|SNAPSHOT|70fe470458e6b54078e567e0f008a161938a7468",
                      supportsSiriRealtimeApis: true,
                      language: "en_US",
                      twitterUrl: "https://mobile.twitter.com/mobilitylabteam",
                      supportsObaRealtimeApis: true,
                      bounds: [
                               {
                                   lat: 39.1922654372773,
                                   latSpan: 0.19698666650759833,
                                   lon: -76.7851586402455,
                                   lonSpan: 0.23177524413500805
                                },
                                {
                                   lat: 37.187614999999994,
                                   latSpan: 0.13692999999999955,
                                   lon: -80.41169,
                                   lonSpan: 0.08337999999999113
                                },
                                {
                                   lat: 38.8941925,
                                   latSpan: 0.06883300000000503,
                                   lon: -77.0180425,
                                   lonSpan: 0.10683699999999874
                                },
                                {
                                   lat: 39.0963510360948,
                                   latSpan: 0.23640594282640137,
                                   lon: -76.7502984250321,
                                   lonSpan: 0.35456249746140145
                                }
                              ],
                      supportsObaDiscoveryApis: true,
                      contactEmail: "paul.mackie@mobilitylab.org",
                      stopInfoUrl: null,
                      active: true,
                      facebookUrl: "https://www.facebook.com/218056428212495",
                      obaBaseUrl: "http://oba.mobilitylab.org/",
                      id: 4,
                      experimental: true,
                      regionName: "Washington, D.C. (beta)"
                   }
                 ]
          }
}

Sample Request (XML)

http://regions.onebusaway.org/regions-v3.xml

Sample Response (XML)

<response>
    <version>3</version>
    <code>200</code>
    <text>OK</text>
    <data>
        <list>
            <region>
                <siriBaseUrl></siriBaseUrl>
                <obaVersionInfo>1.0.8-SNAPSHOT|1|0|8|SNAPSHOT|677fd69e95aa20551bfa5e13c11bd02a2558ffe3</obaVersionInfo>
                <supportsSiriRealtimeApis>false</supportsSiriRealtimeApis>
                <language>en_US</language>
                <twitterUrl>http://mobile.twitter.com/OBA_tampa</twitterUrl>
                <supportsObaRealtimeApis>true</supportsObaRealtimeApis>
                <bounds>
                    <bound>
                        <lat>27.9769105</lat>
                        <latSpan>0.542461</latSpan>
                        <lon>82.445851</lon>
                        <lonSpan>0.576358</lonSpan>
                    </bound>
                </bounds>
                <supportsObaDiscoveryApis>true</supportsObaDiscoveryApis>
                <contactEmail>onebusaway@gohart.org</contactEmail>
                <stopInfoUrl></stopInfoUrl>
                <active>true</active>
                <facebookUrl></facebookUrl>
                <obaBaseUrl>http://api.tampa.onebusaway.org/api/</obaBaseUrl>
                <id>0</id>
                <regionName>Tampa</regionName>
            </region>
            <region>
                <siriBaseUrl></siriBaseUrl>
                <obaVersionInfo>1.1.7|1|1|7||c8ee3d4906dd55ecafdd124f31f39c0f54a37b52</obaVersionInfo>
                <supportsSiriRealtimeApis>false</supportsSiriRealtimeApis>
                <language>en_US</language>
                <twitterUrl>http://mobile.twitter.com/oba_pugetsound</twitterUrl>
                <supportsObaRealtimeApis>true</supportsObaRealtimeApis>
                <bounds>
                    <bound>
                        <lat>47.221315</lat>
                        <latSpan>0.33704</latSpan>
                        <lon>-122.4051325</lon>
                        <lonSpan>0.440483</lonSpan>
                    </bound>
                    <bound>
                        <lat>47.5607395</lat>
                        <latSpan>0.743251</latSpan>
                        <lon>-122.1462785</lon>
                        <lonSpan>0.720901</lonSpan>
                    </bound>
                    <bound>
                        <lat>47.556288</lat>
                        <latSpan>0.090694</latSpan>
                        <lon>-122.4013255</lon>
                        <lonSpan>0.126793</lonSpan>
                    </bound>
                    <bound>
                        <lat>47.093563</lat>
                        <latSpan>0.320892</latSpan>
                        <lon>-122.701637</lon>
                        <lonSpan>0.55098</lonSpan>
                    </bound>
                    <bound>
                        <lat>47.5346090123</lat>
                        <latSpan>0.889378024643</latSpan>
                        <lon>-122.3294835</lon>
                        <lonSpan>0.621109</lonSpan>
                    </bound>
                    <bound>
                        <lat>47.9747595</lat>
                        <latSpan>1.336481</latSpan>
                        <lon>-122.8512</lon>
                        <lonSpan>1.0904</lonSpan>
                    </bound>
                    <bound>
                        <lat>47.6204755</lat>
                        <latSpan>0.014397</latSpan>
                        <lon>-122.335392</lon>
                        <lonSpan>0.00635600000001</lonSpan>
                    </bound>
                    <bound>
                        <lat>47.64585</lat>
                        <latSpan>0.0669</latSpan>
                        <lon>-122.2963</lon>
                        <lonSpan>0.0802</lonSpan>
                    </bound>
                    <bound>
                        <lat>47.9347358907</lat>
                        <latSpan>0.68796117128</latSpan>
                        <lon>-121.993246104</lon>
                        <lonSpan>0.784555996061</lonSpan>
                    </bound>
                </bounds>
                <supportsObaDiscoveryApis>true</supportsObaDiscoveryApis>
                <contactEmail>onebusaway@soundtransit.org</contactEmail>
                <stopInfoUrl>http://stopinfo.pugetsound.onebusaway.org</stopInfoUrl>
                <active>true</active>
                <facebookUrl>https://www.facebook.com/pages/OneBusAway/216091804930</facebookUrl>
                <obaBaseUrl>http://api.pugetsound.onebusaway.org/</obaBaseUrl>
                <id>1</id>
                <experimental>false</experimental>
                <regionName>Puget Sound</regionName>
            </region>
            <region>
                <siriBaseUrl>http://bustime.mta.info/api/</siriBaseUrl>
                <obaVersionInfo/>
                <supportsSiriRealtimeApis>true</supportsSiriRealtimeApis>
                <language>en_US</language>
                <twitterUrl>http://mobile.twitter.com/nyctbusstop</twitterUrl>
                <supportsObaRealtimeApis>false</supportsObaRealtimeApis>
                <bounds>
                    <bound>
                        <lat>40.707678</lat>
                        <latSpan>0.40939</latSpan>
                        <lon>-74.017681</lon>
                        <lonSpan>0.468666</lonSpan>
                    </bound>
                    <bound>
                        <lat>40.8192825</lat>
                        <latSpan>0.228707</latSpan>
                        <lon>-73.899082</lon>
                        <lonSpan>0.231468</lonSpan>
                    </bound>
                </bounds>
                <stopInfoUrl></stopInfoUrl>
                <facebookUrl>https://www.facebook.com/pages/MTA-New-York-City-Transit/232635164606</facebookUrl>
                <supportsObaDiscoveryApis>true</supportsObaDiscoveryApis>
                <contactEmail>MTABusTime@mtahq.org</contactEmail>
                <active>true</active>
                <obaBaseUrl>http://bustime.mta.info/</obaBaseUrl>
                <id>2</id>
                <experimental>false</experimental>
                <regionName>MTA New York</regionName>
            </region>
            <region>
                <siriBaseUrl>http://oba.mobilitylab.org/nextgen/api/</siriBaseUrl>
                <obaVersionInfo>1.1.11-SNAPSHOT|1|1|11|SNAPSHOT|70fe470458e6b54078e567e0f008a161938a7468</obaVersionInfo>
                <supportsSiriRealtimeApis>true</supportsSiriRealtimeApis>
                <language>en_US</language>
                <twitterUrl>http://mobile.twitter.com/mobilitylabteam</twitterUrl>
                <supportsObaRealtimeApis>true</supportsObaRealtimeApis>
                <bounds>
                    <bound>
                        <lat>39.1922654373</lat>
                        <latSpan>0.196986666508</latSpan>
                        <lon>-76.7851586402</lon>
                        <lonSpan>0.231775244135</lonSpan>
                    </bound>
                    <bound>
                        <lat>37.187615</lat>
                        <latSpan>0.13693</latSpan>
                        <lon>-80.41169</lon>
                        <lonSpan>0.08338</lonSpan>
                    </bound>
                </bounds>
                <supportsObaDiscoveryApis>true</supportsObaDiscoveryApis>
                <contactEmail>paul.mackie@mobilitylab.org</contactEmail>
                <stopInfoUrl></stopInfoUrl>
                <active>true</active>
                <facebookUrl>https://www.facebook.com/218056428212495</facebookUrl>
                <obaBaseUrl>http://oba.mobilitylab.org/</obaBaseUrl>
                <id>4</id>
                <experimental>true</experimental>
                <regionName>Washington, D.C. (beta)</regionName>
            </region>
        </list>
    </data>
</response>

Multi-region Apps

The following sub-sections outline the expected general behavior of multi-region OneBusAway apps so the user experience is consistent over the multiple apps.

Expected behavior

On first startup, the mobile app will retrieve a list of currently available regions and their coverage areas from the Regions REST API. It should be noted that the server can potentially return a 5xx error instead of JSON or XML payload. As a result, the response code should be checked and verified to be equal to 200 before attempting to parse the contents of the payload. Once the payload is parsed successfully, the response code element formatted in either JSON or XML should also be verified to be equal to 200 before attempting to show any other payload information to the user.

Once the list of currently available regions and their coverage areas have successfully been retrieved from the Regions REST API, servers with the attribute of active = true should be compared to the user’s real-time location (from either cellular, WiFi, or GPS positioning systems). Servers with the attribute of active = false should NOT be used, since it is assumed that these servers are not currently operational. Additionally, the app should check which APIs are supported by the OBA server (based on the fields supportsObaDiscoveryApis, supportsObaRealtimeApis, and supportsSiriRealtimeApis), and should only use regions that provide the APIs required by the application to function. For example, if the OBA Android app requires the OBA Discovery APIs and the OBA Real-time APIs to interact with a server, and the MTA NY OBA instance does not support the OBA Real-time APIs, then the MTA NY OBA server should not be used when detecting the region.

Note that when using Regions API v3, the API response will automatically include "experimental" regions. These experimental regions are considered unstable and should not be shown to users by default. A setting should be included in the app that allows the user to "Enable experimental regions" (i.e., opt-in to using experimental regions). By default, this setting is not enabled, and only regions with "experimental" set to false are shown in the app. If the user chooses to enabled this option, a message is displayed "Experimental regions may be unstable and without real-time info. Are you sure?". If the user selects "Yes", then regions with "experimental" set to true AND "active" set to true are used in the app for both manual and automatic region selection. If the user deselects "Enabled experimental regions", or cancels out of the enabling dialog, then all regions with "experimental" set to true are again removed from consideration in the app (i.e., same as default setting). If an app does not filter out experimental servers, it should continue to use the original Regions API v2 (original release - ../regions.json, ../regions.xml) until it fully supports experimental servers.

If the user’s real-time location falls within the bounds of an existing region, then the map view will focus on that region and the API of that region will automatically be used, so that the multi-region feature of the app is completely transparent to the end user. If the user’s real-time location isn’t available, or if the user isn’t within any existing coverage areas, the user will be presented with a list of available active = true regions that provide all required APIs to choose from.

Mobile apps should cache the Regions REST API information after it is retrieved so they can fail gracefully and use cached information if the OBA Server Directory is unavailable (e.g., in case of server failure, lack of internet connection). The mobile app is expected to refresh the OBA Server Directory information at least once a week, in a background thread that does not affect the user experience of the app.

In a worst-case scenario, a user installs a new OBA mobile app and attempts to use it, but the Regions REST API is unreachable for some reason (e.g., server down) even though the local regional OBA server is fully operational. This would prevent the user from using the app, only because of a failure in the Regions REST API.

To handle this situation, the mobile app installation bundle is expected to include either a JSON or XML file that is the output of the Regions REST API at the most recent compile-time of the mobile application. On first startup, if the Regions REST API is not reachable, the mobile app should use this bundled file in place of the Regions REST API for knowledge of the OBA regional servers. The app is expected to try to query the Regions REST API again at the next startup to try and get the most recent directory information. After the app successfully receives a response from the Regions REST API, the app should use a cached version of the Regions REST API data in place of the file included in the installation bundle, as the Regions REST API information should post-date the bundled file.

To reduce the burden on mobile app developers and avoid spamming users with frequent app updates, this bundled file is not expected to be updated frequently (e.g., on every OBA Server Directory change). Instead, the bundled file should be updated on every production release of an update to the mobile application.

Error Handling

We do some validation server-side in an attempt to avoid outputting bad or incomplete region data via the Regions REST API. However, OBA clients are strongly encouraged to implement their own error handling when processing the Regions REST API response to avoid presenting bad information to the end-user. Suggested error handling includes graceful failures and user-readable error messages for empty region fields, bad latitudes or longitudes for Bounds, etc.

Contact Info

Note that this section refers to manual feedback typed out by the user in a “Contact Us” context - automated feedback generated via the “Report Problem” menu options for trips and routes will automatically be directed to the current regional OBA server.

In-app experience

When the user is inside the mobile app, only one set of contact information should be accessible to the user via a “Contact Us” button - the contactEmail field from the Regions REST API response. This design ensures that most casual user feedback is directly to the OBA server maintainer for the selected region, and not the app developer.

App Developer Contact Info

Contact information for the app developer should only be accessible to end users through the respective App stores, in the portal where the app is downloaded. Per the app store policies, a centralized contact email and website for each app must be listed here. The website listed for each app should be:

If the OBA server maintainer receives any feedback that is specific to the mobile app, they should forward this information to the respective mobile app developer:

Multi-Region Administration - Updating the Regions REST API response

Since a Google Doc spreadsheet is used for OBA Server Directory data entry, we need a defined process to update the Regions REST API response with changes to the OBA Server Directory content.

A Python "OBA Server Directory Serialization Script" is used to read the CSV output of the OBA Server Directory Google Doc and write it to separate JSON and XML files, which are the files that are retrieved by mobile apps from the Regions REST API request URLs.

The below diagram shows the process for updating the Regions REST API response:

OBA Admin Multi-Region Update Process

Google Doc Drawing for above image is here.

  1. A OBA Server admin updates the Google Doc with new information about their server
  2. The OBA Server Directory Serialization Script is executed
  3. The new JSON and XML files generated by the script are uploaded to the regions.onebusaway.org server
  4. The new JSON and XML files immediately become available as the output of the Regions API
  5. Mobile apps automatically pick up new information from the Regions API

Currently, steps #2 and #3 above are manually executed by one of the OneBusAway "multi-region admins". Multi-region admins are notified of modifications to the Google Doc via auto-generated email (set this up via the "Tools->Notifications" menu in the Google Doc).