Occyd Android Client

What do you see right here, right now ?

Occyd is a social tagging service for geolocations.

This page contains the development notes for the Occyd server and Android client.

We are currently working on the principle of “release early, release often”. As such, there almost certainly will be serious bugs.

Server code: occyd-gae-server

Client code: occyd-android

Bug tracking is handled by Google Code.

Both the client and server are made available under the GNU Affero General Public License 3.0

Developers Quickstart

Hacking the Occyd Android Client

In order to help develop the Occyd Android client, you will need the Android SDK and associated Eclipse plugin installed . Then, clone the git repository and import the project into Eclipse as an “Existing project into Workspace”.

You will also need your own private Google Maps API key, which can be obtained here . Put your API key into the android:apiKey= variable in res/layout/mapview.xml.

Hacking the Occyd Server for Google App Engine

You will require the Google App Engine SDK .

Bug reports

The Occyd client and server are far from stable and are undergoing rapid development. Bug reports, issues and feature requests can be reported at the issue tracking at Google Code

Tasks, TODO list

Server

• Add posts.(done)
• Return ‘n’ most recent posts by:
  • user
  • tag
  • ( &format=json )
  • ( &format=rss ) [georss]

Client

• Add post with:
  • current location (& current time)
  • tags
  • description
  • (user from preferences)
• Fetch ‘n’ most recent posts:
  • user
  • tag
  • distance from current location (rough, by geohash)
• Display fetched posts on map
• Display fetched posts as a list

Client screens

• Search screen
  • Query boxes, time and distance sliders/spinners, search button (popup menu: Map, Preferences, Help)
  • Two query boxes: Tags, user.
  • Two sliders or spinners: Distance (from current location), Time (within the last)
• Add post screen (popup menu: Search, Map, Preferences, Help)
  • Two input boxes: tags (autocomplete with favorite tags), description
  • Single button: “Post”
  • Defaults to current location, current time (GMT).
• Map screen (popup menu: Search, Preferences, Follow, Save search as Favorite, Help)
  • Marker pins on map, auto centres on current location. Click on markers for detailed info.
• Favorite searches (popup menu: Search, Preferences, Follow, Help)
  • A list of favorite, saved searches
• Results list (popup menu: Search, Preferences, Save search as Favorite, Help)
  • Results from a search in list format, sortable by date or distance from current location.

Search, Favorites and Results list screens could be put in tabs. Map and Preferences screen should be untabbed, fullscreen

Currently, the history stack is manipulated such that when navigating to the map, via the popup Menu buttons or via a Search, we can return to the screen (Activity) that launched the map using the back button. Pressing the back button from the Search or NewPost screen will exit, bringing us back to home (or whichever other Activity launched the occyd-android-client via an Intent).

API

• Add KML output (&format=kml) option.

Testing

Test URLs:

Dev server: http://occyd-dev.appspot.com

• /v1/posts/add?ll=-30.5,35.0&desc=blablabla&tags=bla1,bla2,bla3&link=http://www.scroogle.org
• /v1/posts/add?ll=-37.78424,144.951543&desc=The+Melbourne+Zoo&tags=zoo,animals,fun,elephant&link=http://www.melbournezoo.com.au
• /v1/posts/add?ll=-37.773378,144.945993&desc=The+House&tags=house,place,fun&link=http://pansapiens.myopenid.com
• /v1/posts/delete?key=ahRuZXctcHJvamVjdC10ZW1wbGF0ZXIKCxIEUG9zdBgFDA
• /v1/posts/get?format=rss
• /v1/posts/get?format=json
• /v1/posts/get?format=rss&tag=test+fuel&near=-37.771,144.94&radius=150000
• /admin
• /remotekey
• /remotekey?reset

Web interface – pages

• / – home page, with various summaries
• /remotekey – get your remote key (must be logged in)

• /remotekey?reset – reset your remote key (must be logged in)
• /admin – database management page (accessible to admin accounts only)

API

The API is inspired by the delicious API to some extent, but deviates significantly.

The API is currently in development. Don’t rely on anything; both queries and responses could change in the future.

Query types

Implemented

• posts/add – add a new bookmark
• posts/delete – delete an existing bookmark
• posts/get – return bookmarks, filtered by recency, tag and distance from a location

Not yet implemented (some may never be)

• posts/dates – list dates on which bookmarks were posted
• posts/recent – fetch recent bookmarks
• posts/all – fetch all bookmarks by date or index range
• posts/all?hashes – fetch a change detection manifest of all items
• tags/get – fetch all tags
• tags/delete – delete a tag from all posts
• tags/rename – rename a tag on all posts

Response formats

Currently JSON (probably conforming to GeoJSON specification) for Android client/server communication, and GeoRSS-Simple .

Future features, ideas

Crossposting to delicious (or similar sites), adding geohash tags .

Attach photos to a posting, via crosspost to Twitpic, Flickr, etc.

Consider changing the API to support requests like http://occyd.appspot.com/tags/test,bla2/rss and http://occyd.appspot.com/tags/test,bla2/json. User page would be http://occyd.appspot.com/somenickname , which more closely follows the URL scheme used by many social apps. To get results as browser readable HTML, use http://occyd.appspot.com/tags/test,bla2. Read this for some good ideas on design decisions for RESTful URL schemes.

Authentication idea

On first run, forward the user to a web-based (browser, or WebKit view) App Engine login screen. Once they have logged in with their Google account, they will be given a “secret key”. Optionally allow them to associate a ‘nickname’ and not use their Google account nickname.

Cut’n’paste this secret key (long hold on the text box it is in), then go back to the Occyd Android client, and paste it into the secret key box.

The occyd-gae-server database will store usernames, nicknames (optional) and secret keys. User can login again to reset their secret key.

API will accept &apikey=blaBlaBl4blabLa which will associate added posts with a user.

Links, reference

Tagging engines

Take a look at pycite … I’d forgotten about this project, but it would may make a good server backend, with minor modificaitions … (although a quick look at the code suggests that the datastore model’s implementation of tags uses a simple StringListProperty, and much like my current server implementation probably wouldn’t scale well ?).

Authentication

Android SDK currently doesn’t have any mechanism to access the users Google account. Until it does, we need to do something else.

Authentication with Google Account (until the SDK is fixed): http://agilemedicine.com/medBlog/?p=22

Or the official docs: http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html

Could also use OAuth ( http://code.google.com/p/jfireeagle/ or http://code.google.com/p/jpoco/ and http://code.google.com/p/oauth/ )

Or use OpenID, seperate from Google, (GAE OpenID consumer: http://code.google.com/p/google-app-engine-samples/source/browse/#svn/trunk/openid-consumer or http://code.google.com/p/google-app-engine-django-openid/ ) except that this [http://aralbalkan.com/1357 probably will fail in many cases] ?

Similar or related geolocation based services & databases

From my research so far, it seems none of them have decent support for delicious-style tagging. Which means the Occyd server will need to maintain it’s own database and probably can’t be entirely backed by one of these services.

• Google Maps – see:
  • http://code.google.com/apis/maps/documentation/index.html
• Yahoo maps – see:
  • http://developer.yahoo.com/maps/applications.html
  • http://toys.lerdorf.com/archives/35-GeoCool!.html
• Marvin (http://marvinreloaded.com/)
• Brightkite
• Yahoo Fire Eagle API ? — seems to only deal with current users location, not other tagged placemarks.
• IceCondor ? : http://donpark.org/wiki/icecondor
  • has an android client already, and an API …
  • GPL source client: http://github.com/donpdonp/icecondor-client-android/tree/master
  • server: https://github.com/donpdonp/icecondor-server-rails/

• http://featureserver.org/ — FeatureServer, Python geo feature server code, BSD-license.
• http://pypi.python.org/pypi/geojson/ — GeoJSON from Python. May help in making valid GeoJSON output.

Google App Engine

• Nice example of using App Engine as a geodatabase: 24 hours in SF: A Geolocation App
• Great article on using the new GeoModel entity with GAE for geospatial queries: Geospatial Queries with Google App Engine using GeoModel — this is definitely what Occyd should use in addition to geohashes.

Geohashing

• Great post describing how to make a geographic datastore and query it with Google App Engine , using GeoHashes or GeoStrings.
• Discussion of ‘geohashes’ for geolocation database used by Bubbles!, backend on Google App Engine: http://blog.rabidgremlin.com/index.php/2008/08/19/bubbles-now-uses-google-app-engine/
• Public Domain Geohashing code in Python, for App Engine: http://code.google.com/p/geodatastore/source/browse/trunk/geohash.py
  • And more at: http://code.google.com/p/geopy/
  • AGPL “Affero” licensed GeoHash code for Python on the server side: http://pypi.python.org/pypi/Geohash/1.0rc1
• LGPL licensed geohashing code in Java: http://code.google.com/p/geospatialweb/source/browse/trunk/geohash/src/Geohash.java?r=104
• Here is a javascript implementation under an MIT license .. it could probably be ported easily to Python and Java: http://github.com/davetroy/geohash-js/tree/master
• Delicious geotagging (geo:lat= and geo:long= ):
  • see http://worldkit.org/delicious/
  • yahoo pipe for turning delicious geotags into GeoRSS: http://ouseful.open.ac.uk/blogarchive/010408.html
  • My blog post :) : http://blog.pansapiens.com/2008/12/29/delicious-geohashes-mmmm-tagging-drool/
• General geotagging: http://en.wikipedia.org/wiki/Geotagging

GeoRSS

• Two good examples of GeoRSS format feeds: http://www.shizzow.com/donpdonp/rss and http://brightkite.com/people/donpdonp/objects.rss (courtesy of Don Park ).
• GeoRSS.org has the specs for GeoRSS. In practice, I found the two reference feeds above more useful.

General schema for tags

Using key/value pair “document” databases (ala App Engine Datastore or CouchDB)

• Tag implementation for GAE by Nick Johnson: http://blog.notdot.net/2009/10/Blogging-on-App-Engine-part-5-Tagging – seems to be what I’d call a “lightweight” implementation suitable for a small blog but not a very large service – Tags are not treated as first-class entities.
• The Taggable mixin for GAE, and [http://groups.google.com/group/google-appengine/browse_thread/thread/daa072f6c68ed823/0326daa82b6c635c?lnk=gst&q=tagging#0326daa82b6c635c why it is flawed for large apps].
• Tagging for Django on GAE.. (might be useful but don’t blindly assume it’s the best model): http://xponrails.net/wrblog/view_post/19
• Tag implementation for CouchDB http://wiki.apache.org/couchdb/Tags_inside_documents

Using Relational Databases

…. since the Occyd server currently uses the App Engine datastore, these approachs probably don’t apply

• http://www.pui.ch/phred/archives/2005/04/tags-database-schemas.html
• http://www.pui.ch/phred/archives/2005/06/tagsystems-performance-tests.html
• http://tagschema.com/blogs/tagschema/2005/07/tags-get-no-respect.html
• http://www.whatspop.com/blog/2006/01/setting-up-database-for-tagging.cfm
• http://www.slideshare.net/edbond/tagging-and-folksonomy-schema-design-for-scalability-and-performance/

Related

I hadn’t seen it at the time I started developing Occyd, but it would make a good component of Jamais Cascio’s ‘Earth Witness’