-
Notifications
You must be signed in to change notification settings - Fork 6
Home
SiriRestClient is an open-source reference implementation Android library for interacting with the RESTful SIRI (Service Interface for Real Time Information) interface for real-time transit data, such as that currently being used by the [MTA Bus Time API] (http://bustime.mta.info/wiki/Developers/SIRIIntro).
SIRI is a public transportation standard developed by the European standards organization CEN. More information about SIRI can be found at the main SIRI website.
The purpose of this project is to stimulate innovation in mobile apps for the SIRI real-time transit API by providing an easy-to-use Android library that makes interacting with the API simple for app developers, thus lowering the learning curve for developing new real-time transit apps.
See the SiriRestClientUI project for an example of how to use this library in an Android app.
All SiriRestClient source code is licensed under Apache 2.0.
To add this library to your project using Maven, add the following to your pom.xml file:
<dependencies>
<!-- SIRI POJOs -->
<dependency>
<groupId>edu.usf.cutr.siri</groupId>
<artifactId>onebusaway-siri-api-v13-pojos</artifactId>
<version>1.0.0</version>
</dependency>
<!-- SiriRestClient library -->
<dependency>
<groupId>edu.usf.cutr.siri</groupId>
<artifactId>sirirestclient</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
</dependencies>
<!-- CUTR SNAPSHOTs/RELEASES -->
<repositories>
<repository>
<id>cutr-snapshots</id>
<url>https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/snapshots</url>
</repository>
<repository>
<id>cutr-releases</id>
<url>https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/releases</url>
</repository>
</repositories>
The SIRI REST API has two primary interfaces that are currently supported in this library:
- vehicle monitoring - provides information for specific transit vehicles
- stop monitoring - provides information for estimated arrival information at specific stops
Here's some sample code for configuring the client:
//Client object from this library that will make the request to the server
SiriRestClient client;
// Setup server config
SiriRestClientConfig config = new SiriRestClientConfig(SiriRestClientConfig.RESPONSE_TYPE_JSON); //Request JSON response
config.setHttpConnectionType(SiriRestClientConfig.HTTP_CONNECTION_TYPE_ANDROID); //Request using Android HTTP connection object
config.setJacksonObjectType(SiriRestClientConfig.JACKSON_OBJECT_TYPE_READER); //Request using the Jackson ObjectReader, which is more efficient than ObjectMapper
// Instantiate client with URLs for server and config
client = new SiriRestClient(
"http://bustime.mta.info/api/siri/vehicle-monitoring",
"http://bustime.mta.info/api/siri/stop-monitoring", config);
Once you've configure the client, you can request information for either a vehicle or specific stop.
Here's an example of requesting stop info:
//Get the parameters that will be used to make the request - fill in these with your own info
String key = getDeveloperKey(); //Get the developer API key to use, perhaps from a config file
String operatorRef = getOperatorRef(); //Get the operator we're requesting info for
String monitoringRef = getStopId(); //Get the stop ID we're requesting info for, perhaps from UI field
String lineRef = getRouteId(); //Get the route ID filter, perhaps from UI field
int directionRefInt = getDirectionInt(); //Route direction filter (0 or 1)
String stopMonitoringDetailLevel = "normal"; //Get arrivals up to the specified stop ID (not after)
int maximumNumberOfCallsOnwardsInt = 3; //Get next 3 arrivals at this stop
//Make request to the server, and get response data in a SIRI object
Siri siri = client.makeStopMonRequest(key,
operatorRef,
monitoringRef,
lineRef,
directionRefInt,
stopMonitoringDetailLevel,
maximumNumberOfCallsOnwardsInt);
And here's an example of requesting vehicle info:
//Get the parameters that will be used to make the request - fill in these with your own info
String key = getDeveloperKey(); //Get the developer API key to use, perhaps from a config file
String operatorRef = getOperatorRef(); //Get the operator we're requesting info for
String vehicleRef= getVehicleId(); //Get the vehicle ID filter, perhaps from UI field
String lineRef= getRouteId(); //Get the route ID filter, perhaps from UI field
int directionRefInt = getDirectionInt(); //Route direction filter (0 or 1)
String vehicleMonitoringDetailLevel= "calls"; //Get arrival info for the vehicle, in addition to position information
int maximumNumberOfCallsOnwardsInt = 3; //Get next 3 arrivals for this vehicle
Siri siri = client.makeVehicleMonRequest(key,
operatorRef,
vehicleRef,
lineRef,
directionRefInt,
vehicleMonitoringDetailLevel,
maximumNumberOfCallsOnwardsInt);
See the SiriRestClientUI project for an example of how to use this library in an Android app.
This project was created in Eclipse using the Android SDK and Android Plugin for Eclipse. Libraries and dependencies are managed using [Maven] (http://eclipse.org/m2e/). Note that you'll need to install the m2e Android Maven plugin in Eclipse.
To get started with this project, use a Git client to clone this repository to your local computer. Then, in Eclipse do "File->Import->Maven->Existing Maven Projects", and point to the directory where you cloned the repo.
SiriRestClient has dependencies on Jackson for parsing JSON and XML. We also need some XML libraries that have been modified so they work on Android. Both of these dependencies are managed via Maven, so no action is required on your part.
Please see the Parsing JSON and XML on Android wiki page for a full description of the use of Jackson with Android.
This project also uses the SIRI POJOs project for Jackson data binding. This project is included in the Maven dependencies, so no action is required.
Clean and build the project. If you have any problems, try cleaning the project, restarting Eclipse, then building the SiriRestClient project.
We've set up a Maven repository to hold the artifacts from this project in a Github project - cutr-mvn-repo.
At CUTR, we should run the following at the command-line to create a new artifact:
mvn -DaltDeploymentRepository=cutr-snapshots::default::file:"/Git Projects/cutr-mvn-repo/snapshots" clean deploy
Then commit using Git and push new artifacts to Github.
Note that the "snapshots" in the command-line should be replaced with "releases" for release versions.
We anticipate that the SIRI specification will change over time and the SIRI Plain Old Java Objects (POJOs) code will need to be regenerated. The SIRI v1.3 POJOs are maintained in their own OBA SIRI v1.3 POJOs project. If a new version of SIRI is released (e.g., v2.0), a new SIRI POJOs project will need to be created for this version of SIRI.
There are two strategies for creating new SIRI POJOs needed for data binding with a new version of SIRI:
-
Use tools such as [json gen] (http://jsongen.byingtondesign.com/) to generate POJOs based on SIRI JSON data
-
Strip the XML annotations and other characteristics that are incompatible with Android from the SIRI JAXB classes to create true POJOs that work on Android. See the current SIRI POJO project wiki for details on how to perform this manual process.
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:
- Parsing JSON and XML on Android - Discusses how to use Jackson data binding to parse JSON and XML data in an Android app
- Modifying XML libraries for Android - Discusses the challenges of using XML parsing libraries on Android and how to overcome them
- Optimizations and Performance Benchmarks - We've outlined a few steps you can take to enhance the performance of parsing JSON or XML, including test results demonstrating the benefits on real devices! These optimizations are also built into the SiriRestClient library so you can start using them in your own app!