Geotagging and GeoRSS support has been available in Elgg for a little while now, but like so many cool features of the platform, I haven’t really had the time to draw people’s attention to it.

Although I am drawing your attention to it now, it should be noted that this is still somewhat under development!

Anatomy of a geocoder

To begin geocoding your data you will need a geocoder. This is not something that Elgg comes installed with by default, although here’s one I coded earlier.

This geocoder users the Google maps API to do the actual encoding, and provides two primary features.

  • It handles the plugin hook “geocode”,”location”
  • It listens to all create events and attempts to tag it with the latitude and longitude – either from a ->location metadata on the object itself, or from the user’s current ->location – you could get more creative, this is a simple example.

When you attempt to geocode a location you call the function elgg_geocode_location(). This in turn triggers the above plugin hook and attempts to encode the data.

For efficiency once a location has been geocoded the result is cached. Future attempts to code the same location will return the result from the cache.

Once installed and configured, new content (wire posts etc) will be tagged with a latitude and longitude. Fill in your profile location field and try it out for yourself!

Location based searches

Once things are tagged with a location, you can start to use location as a starting point for searching by using some of the location aware search functions in location.php.

This hasn’t currently been hooked up to the Elgg interface in any way, but that doesn’t stop you making use of it in your plugins.

GeoRSS

This is something you’ll be pleased to know that you get for free!

As you list your entities using the Elgg listing tools using the RSS view, if an entity has a position defined it will be included using standard geoRSS simple notation, i.e:

<georss:point> 45.256 -71.92 </georss:point>

Happy coding!

in_ur_realityAnother one of Elgg‘s less documented but very powerful features is the ability to expose functionality from the core and user modules in a standard way via a REST like API.

This gives you the opportunity to develop interoperable web services and provide them to the users of your site, all in a standardised way.

The endpoint

To make an API call you must direct your query at a special URL. This query will be either a GET or a POST query (depending on the command you are executing), the specific endpoint you use depends on the format you want the return value returned in.

The endpoint:

http://yoursite.com/pg/api/[protocol]/[return format]/

Where:

  • [protocol] is the protocol being used, in this case and for the moment only “rest” is supported.
  • [return format] is the format you want your information returned in, either “php”, “json” or “xml”.

This endpoint should then be passed the method and any parameters as GET variables, so for example:

http://yoursite.com/pg/api/rest/xml/?method=test.test&myparam=foo&anotherparam=bar

Would pass “foo” and “bar” as the given named parameters to the function “test.test” and return the result in XML format.

Notice here also that the API uses the “PG” page handler extension, this means that it would be a relatively simple matter to add a new API protocol or replace the entire API subsystem in a module – should you be so inclined.

Return result

The result of the api call will be an entity encoded in your chosen format.

This entity will have a “status” parameter – zero for success, non-zero denotes an error. Result data will be in the “result” parameter. You may also receive some messages and debug information.

Exporting a function

Any Elgg function – core or module – can be exposed via the API, all you have to do is declare it using expose_function() from within your code, passing the method name, handler and any parameters (note that these parameters must be declared in the same order as they appear in your function).

Listing functions

You can see a list of all registered functions using the built in api command “system.api.list”, this is also a useful test to see if your client is configured correctly.

E.g.

http://yoursite.com/pg/api/rest/xml/?method=system.api.list

Authorising and authenticating

Most commands will require some form of authorisation in order to function. There are two main types of authorisation – protocol level which determines whether a given client is permitted to connect, and user level where a command whereby a user requires a special token in lieu of a username and password.

Protocol level authentication
Protocol level authentication is a way to ensure that commands only come from approved clients for which you have previously given keys. This is in keeping with many web based API systems and permits you to disconnect clients who abuse your system, or track usage for accountancy purposes.

The client must send a HMAC signature together with a set of special HTTP headers when making a call. This ensures that the API call is being made from the stated client and that the data has not been tampered with.

Eagle-eyed readers with long memories will see a lot of similarity with the ElggVoices API I wrote about previously.

The HMAC must be constructed over the following data:

  • The Secret Key provided by the target Elgg install (as provided easily by the APIAdmin plugin).
  • The current unix time in microseconds as a floating point decimal, produced my microtime(true).
  • Your API key identifying you to the Elgg api server (companion to your secret key).
  • URLEncoded string representation of any GET variable parameters, eg “method=test.test&foo=bar”
  • If you are sending post data, the hash of this data.

Some extra information must be added to the HTTP header in order for this data to be correctly processed:

  • X-Elgg-apikey – The API key (not the secret key!)
  • X-Elgg-time – Microtime used in the HMAC calculation
  • X-Elgg-hmac – The HMAC as hex characters.
  • X-Elgg-hmac-algo – The algorithm used in the HMAC calculation – eg, sha1, md5 etc

If you are sending POST data you must also send:

  • X-Elgg-posthash – The hash of the POST data.
  • X-Elgg-posthash-algo – The algorithm used to produce the POST data hash – eg, md5.
  • Content-type – The content type of the data you are sending (if in doubt use application/octet-stream).
  • Content-Length – The length in bytes of your POST data.

Much of this will be handled for you if you use the built in Elgg API Client.

User level tokens

User level tokens are used to identify a specific user on the target system, in much the same way as if they were to log in with their user name and password, but without the need to send this for every API call.

Tokens are time limited, and so it will be necessary for your client to periodically refresh the token they use to identify the user.

Tokens are generated by using the API command “auth.gettoken” and passing the username and password as parameters, eg:

http://yoursite.com/pg/api/rest/xml/?method=auth.gettoken&username=foo&password=bar

Anonymous methods
Anonymous methods (such as “system.api.list”) can be executed without any form of authentication, thus accepting connections from any client and regardless of whether they provide a user token. This is useful in certain situations and it goes without saying that you don’t expose sensitive functionality this way.

To do so set $anonymous=true in your call to expose_function().

Image “In UR Reality” by XKCD

One of the more hidden features of Elgg is the Export interface.

In a nutshell this interface provides an export view for Entities, Metadata, Annotations and relationships which can provide a convenient way of accessing data objects in a machine readable form.

Endpoints

The export url is constructed in different ways for entities, relationships and metadata.

All endpoints begin with:

http://yoursite.com/export/[VIEW]/

Where [VIEW] is the format you want the data exported in – e.g. json, opendd, php or default.

Entities
To export a GUID simply add it to the end:

http://yoursite.com/export/[VIEW]/[GUID]/

Annotations & Metadata

Metadata and annotation can be exported by providing the type (‘annotation’ or ‘metadata’) and the appropriate ID.

http://yoursite.com/export/[VIEW]/[GUID]/[annotation|metadata]/[annotation_id|metadata_id]/

Relationships
Follows the same format as above, but with [GUID] being the first guid in the relationship – in essence the entity to which the relationship “belongs”.

http://yoursite.com/export/[VIEW]/[GUID]/relationship/[relationship_id]/

Security

Some items of data (for example user passwords) are restricted from this export view. Exactly what is output by an output view is governed by $object->getExportableValues(); which returns a list of exportable fields in the entity.

In addition, access permissions on the object are respected – meaning that if you can’t see an item in Elgg, you will not be able to see it in the export view either.