Geous.js grows up

Geous.js is a tiny javascript library that makes geocoding and geolocation tasks a snap…

…and for most of its brief existence, feature development has been dictated by need. The core geocoder arose to save the trouble of repeated integrations with geocoding services. Geolocation support was added to support mobile applications, jquery integration for form pre-fills, and so on.

Throughout that time, geous relied heavily on the Google Maps API to do its heavy lifting. But the exclusive relationship is over: a flurry of recent development and some enormous strides made by the open data community have opened geous up for use with just about any geocoding provider.

A brief example

Before diving into the details, try using geous to find the current (geolocated) coordinates…

var myLocation;
geous.getUserLocation({
  success: function (location) {
    myLocation = location;
  }
});

And resolving them into an address…

geous.geocode(myLocation, { 
  reverse: true, 
  success: function (location) {
    console.log("Hello, " + location.toAddress());
  }
});

Not bad, eh?

Location, Location, Location

For some time now, Geous has been coalescing around the geous.Location object, a sort of lingua franca for storing the coordinates and address of a point on a grid. There’s nothing new here—most geocoders provide similar data in their results—but the Location object enables geous to provide consistency with multiple geocoding services and its own internal functions. The basic geolocation API will only return a coordinate pair, for instance, but the same request made through geous will return a Location instance. This may then be resolved into an address using an arbitrary geocoder abstracted through geous’ geocode method, maintaining homogeneity throughout the request.

And now, with jQuery

Locations are also the focus of a particularly useful geous plugin—geousable, a jQuery plugin for integrating geous directly with existing forms and interactive content. $.geousable basically provides a direct map between a location object and arbitrary elements in the DOM. The default mapping binds the fields in a geous.Location to elements with the corresponding CSS class, but any selector may be bound using the plugin’s map or defaultMapPattern. To follow rails’ nested object naming style, for instance:

$('form').geousable({ 
  defaultMapPattern: '[name="location[{%}]"]' 
});

Now, to populate a form with the results of a geocoding request, simply pass the location on to geousable.setLocation:

$('form').geousable('setLocation', location);

Similarly, a geous.Location containing the form’s current fields—say, a user’s mailing address—can be retrieved using getLocation():

myLocation = $('form').geousable('getLocation');

There are a few examples of geousable in action here.

And the catch?

First, there’s the service. While geous abstracts away the particulars of interacting with a geocoding service, its results will never be better than the geocoder can provide. Each service is also restricted by its own terms of service. The (oft-changing) terms of the default (Google) geocoder, for instance, prohibit caching data or use in any applications that doesn’t display a map via the Google Maps API. Fortunately, geous may be easily adapted to additional services or even self-hosted data—just place an appropriate binding in the geocoders directory, rebuild, and you’re off.

Second, there’s the browser. HTML5 geolocation only works in modern browsers, and even then only with a user’s permission. Take either away, and no amount of javascript will be able to bring the magic back. Great news for privacy advocates, but it also obliges developers to take special care when relying on browser-based geolocation.

Coming soon

For all of its newfound encapsulation, geous remains very much in bed with its Google roots. Time allowing, I’d love to get a few additional geocoding options and map integrations spec’d and committed to the project. I’m expecting to add GeoJSON parsing and a leaflet integration in the not-too-distant future, but any (all) adapters and plugins contributed via the github page will be included in the master build as soon as they can be verified.

Featured