Recently I've been evaluating a new REST API for the storage and retrieval of geo location data with Flex and ActionScript with success - since it previously had no Flash examples and I'd like to share my code with you.
I've had an interest in coding location based apps for quite some time and discovered SimpleGeo while I was doing the research for a presentation I recently did at webdu . They offer three geo products for developers: Storage, Context & Places - with pricing based on the number of calls rather than disk space.
Calls to the SimpleGeo API are via REST with results retrieved in either JSON or PJSON. Authentication is required for all calls, developers need to get an OAuth key for their apps. Code libraries already exist for JavaScript, Python, Java (including Android), Objective-C, PHP, Ruby and .Net - what's missing out of that list is ActionScript.
Within ActionScript there's already classes to handle making a HTTP call to a server and handle the results that come back from that request. Out of the box there's no parsing for JSON but there's external libraries for that - I'm using as3corelib for that found on github here: https://github.com/mikechambers/as3corelib
The SimpleGeo API needs authentication for all requests, this is handled by OAuth and again there's an external AS3 library for OAuth that can be found here: http://code.google.com/p/oauth-as3/
I've worked with OAuth in AS3 projects previously. The typical scenario for authentication is that you have both a consumer key and consumer secret issued by the site that you've got a developer account for. You connect to that site passing those two values - in the case of Twitter an app would launch a separate window displaying a page on Twitter where a user is asked to grant your application permission. During that process we collect tokens which are used in further communications with the host. That kind of authentication process happens only once.
You're likely to already be familiar with that process, sometimes called 3-Legged OAuth. SimpleGeo instead uses a simpler implementation called 2-Legged OAuth where the app passes keys and secrets with every request without requiring access premission to be granted for individual users. As developer we are the account holder for the site instead of the users of our application - the individual authorisation and token collection steps are eliminated alltogether. It's explained further on the SimpleGeo blog in this post: Two-Legged OAuth
I've successfully built a sample app to use the Places part of the API and will go through that in the bits of sample code below.
Imports
First things first, below you'll see the necessary libraries that I've imported for this project, although the JSON import appears to be from com.adobe it's actually included in as3corelib mentioned above. The import for org.iotashan.oauth is using the OAuth library also mentioned previously.
Variables
Below I've created static contants for the consumer key & secret, base url for all calls to SimpleGeo and defined the encryption method for the OAuth data we're going to eventually generate - you need to apply for the keys at SimpleGeo by signing up here: https://simplegeo.com/signup/. I've also created an ArrayCollection to store the results I get from the call. There's instances of the OAuthConsumer class and the AS3 HTTPService class.
This sample app was intended to run in the browser so I've created variables to store latitude and longitude for my test location that I've pre-populated (downtown Sydney) - these could easily be retrieved from the GPS of a mobile device within a mobile version of this application, something that I've already done successfully with a Flex application running on an Android device which I'll talk about in another post.
The last variable I've created is an object to store any of the optional arguments that can be passed to the REST service as part of the call, this can be left empty if none are required - in the example code I've added the parameter to restrict results to a radius of 5 kilometres. Check the documentation for SimpleGeo's Places to see what parameters are available: https://simplegeo.com/docs/api-endpoints/simplegeo-places
Functions
We start with a function used to instantiate the oAuthKeys and simpleGeoService, add event listeners to simpleGeoService for returned results and faults and lastly called another function that will then call the service. This init function is called by a creationComplete event on the Flex application tag.
The serviceResultHandler function receives the result data from the call to the SimpleGeo API, parses the data to a new object and uses a nested array in that new object to populate the placesData ArrayCollection. The serviceFaultHandler function, for the purpose of this exercise, displays any faults in an Alert control.
The fetchPlaces function assigns to the url property of simpleGeoService a url built using the getRequestUrl function below which parses url details into a valid OAuthRequest string.
Note how the reqURL string is built in the getRequestUrl function, that I'm concatenating the latitude and longitude values as part of the url as per the SimpleGeo documentation.
Flex list control
For simplicity's sake I'm displaying the results in a standard Flex list control, the only thing interesting that I'm doing is using a label function to select the value that I'm displaying because each item in the ArrayCollection contains a nested object for the Place details.
List label function
The label function allows me to nominate a specific property of the nested "properties" object within each item in the ArrayCollection used as the dataprovider for the List control.
The completed code
Finally here is all is together, I hope that you have found this useful - please let me know in the comments below if it's been of value to you. I intend to write more about my adventures with SimpleGeo as I do some more developing with this very useful online service.
