Mobile App Design Considerations - Hillsborough-Transit-Authority/onebusaway-application-modules GitHub Wiki

Interested in creating a mobile app that uses OneBusAway for real-time transit data? You're in the right place.

Before you start your own app, check out the existing open-source OneBusAway (OBA) apps to get ideas, and make sure you're not duplicating features that already exist:

You may want to contact the developers to see if you can pitch in to add new features to the existing apps. Or, create a new OBA app for a new platform!

Using the existing OBA Mobile Apps with your OBA Server

For the existing OBA mobile apps to work with your OneBusAway server, you must add the following keys to the data-sources.xml file for the opentripplanner-api-webapp:

  • Android: v1_BktoDJ2gJlu6nLM6LsT9H8IUbWc=cGF1bGN3YXR0c0BnbWFpbC5jb20=
  • iPhone: org.onebusaway.iphone
  • Windows Phone: v1_C5+aiesgg8DxpmG1yS2F/pj2zHk=c3BoZW5yeUBnbWFpbC5jb20==

NOTE: If you're testing the Windows Phone key with your OBA API from a browser, note that the key contains two reserved characters ("+" and "/") that need to be encoded to form a valid URL. Here's the encoded key - v1_C5%2Baiesgg8DxpmG1yS2F%2Fpj2zHk%3Dc3BoZW5yeUBnbWFpbC5jb20%3D= - so a sample URL would be: http://api.tampa.onebusaway.org/api/api/where/agencies-with-coverage.json?key=v1_C5%2Baiesgg8DxpmG1yS2F%2Fpj2zHk%3Dc3BoZW5yeUBnbWFpbC5jb20%3D=

The existing iPhone and Android apps both have settings where you can update the OBA server that the app is pointing at. So, for testing you can download the existing apps from the iPhone App Store or Google Play store and change the URL to point to your server.

NOTE: There is currently an issue that affects configuring the OBA iPhone app to point at your OBA server. The current workaround - DON'T hide the keyboard after entering the API endpoint for your server in the Settings screen. Instead, after you've typed in the address for your server, just tap the "More" button in the upper-left corner to go back to the previous screen. If you hide the keyboard, the app may crash and may not properly save your server API address.

To be clear, the above keys should NOT be used in your own mobile app, these keys are reserved for the exiting OBA native open-source mobile apps listed at the top of this section.

We're currently working on a way to make the existing mobile apps "regionalized" to support multiple OBA server instances.

The Anatomy of OBA-related Transit APIs

Like many open-source projects, OneBusAway is changing quickly. Check out the [OBA RESTful API Roadmap] (https://github.com/OneBusAway/onebusaway-application-modules/wiki/RESTful-API-Roadmap) for a list of APIs that are currently supported in OneBusAway, as well as the plan for what APIs will be supported in the future.

Also check out the SIRI Element to UI Mappings for a description of the SIRI element fields and how they should be shown to transit riders.

Design Considerations

Overview

In general, we suggest using the JSON interfaces for OneBusAway. JSON is a more compact representation of data than XML, and therefore more efficient. This means less data sent over the wireless network and better battery life for a mobile phone.

Format of OBA REST API requests and responses

See OBA REST API documentation.

Format of SIRI responses

To conform with the SIRI standard, XML and JSON element labels are in PascalCase (i.e., not camelCase, where the first letter is lower-case).

XML:

<RecordedAtTime>2012-09-12T09:27:52.867-04:00</RecordedAtTime>

JSON:

"RecordedAtTime":"2012-08-21T12:07:21.485-04:00"

Java-based JSON and XML data binding parsers such as Jackson can typically be configured to handle PascalCase, even though they typically expect camelCase, since the Java POJOs used in data binding typically define fields in camelCase.

However this presents a problem for certain attributes. Consider the following XML:

<Summary xml:lang="EN">b/d 1:00pm until f/n. local and express buses run w/delays & detours. POTUS visit in MANH. Allow additional travel time Details at www.mta.info</Summary>

The xml:lang attribute must remain lower-case because of XML language attribute definition defined by W3C. Therefore, if you configure your JSON or XML parser to use PascalCase for elements, be aware that you will need to configure it to make an exception for attributes such as xml:lang.

TODO - add how to handle xml:lang in Jackson, also add this to SiriRestClient pages.

Platform-specific information

Below are some pointers for developing OneBusAway apps on various mobile platforms.

Android
Real-time mobile SIRI API - JSON and XML parsing

We've created Siri Rest Client, an open-source reference implementation Android app that shows how to access and parse SIRI data in both JSON and XML format. Feel free to use this project as a basis for your app, as the source code is licensed under Apache 2.0.

We've developed several tutorials based on what we've learned implementing the SiriRestClient, especially in the area of JSON and XML parsing on Android:

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️