Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rjz/geous.js
Javascript Geolocation made easy
https://github.com/rjz/geous.js
Last synced: 6 days ago
JSON representation
Javascript Geolocation made easy
- Host: GitHub
- URL: https://github.com/rjz/geous.js
- Owner: rjz
- Created: 2011-07-20T21:46:02.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2012-10-23T16:03:51.000Z (about 12 years ago)
- Last Synced: 2024-12-17T15:43:41.054Z (9 days ago)
- Language: JavaScript
- Homepage: rjz.github.com/geous.js
- Size: 336 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
Geous.js
===============
Javascript geolocation and geocoding made easy.
* [Overview](#overview)
- [Location object](#geouslocation)
- [Geocoding](#geousgeocode)
- [Geolocation](#geousgetuserlocation)
* [Using with jQuery](#geous--jquery)
* [Geocoders](#geocoders)
* [License](#license)
Getting started
---------------
Clone the geous repository to your application's script directory:
$ cd /my/project/js/
$ git clone https://github.com/rjz/geous.js.git
Include `geous.js`:
If you're planning to use geous to assist in geocoding tasks, you will also need to include the google maps API:
And that's it! You can now begin taking advantage of geous in your javascript application.
Overview
--------
Geous provides a common format for managing location-based data and handy utilities for performing location-related tasks.
###geous.Location
Location objects provide the basic currency for all other geous operations. A basic location may be constructed from a variety of formats, including any of the following:
// copy constructor
new geous.Location(new geous.Location());
// address string
new geous.Location('123 abc st, akron, ohio');
// address components
new geous.Location(['123 abc st', 'akron', 'ohio']);
new geous.Location({city: 'akron', state: 'ohio'});
// lat/lng coordinates
new geous.Location(48.3689, -99.9962);
new geous.Location([48.3689, -99.9962]);
new geous.Location({lat: 48.3689, lng: -99.9962});
The `setAddress` and `setCoordinates` methods used by the constructor may also be used to assign location components to an existing `geous.Location`:
var location = new geous.Location();
location.setAddress({city: 'akron', state: 'ohio'});
console.log(location.city, location.state);
location.setCoordinates(48.3689, -99.9962);
console.log(location.coords);
###geous.geocode
Geous provides a catch-all method for converting between various location formats.
var location = new geous.Location({ city: 'Truckee', state: 'CA' });
geous.geocode(location, {
error: function () {
alert('well, that didn\'t work out!');
},
success: function (location) {
console.log(location.coords);
}
});
Besides supporting `success` and `error` callbacks, the geocoder may be used to reverse-geocode a lat-lng pair by specifiying `{ reverse: true }`.
var location = new geous.Location(48.3689, -99.9962);
geous.geocode(location, {
reverse: true,
success: function (location) {
console.log(location);
}
});
Prior to calling `geous.geocode`, an alternative geocoder may be assigned using `geous.configure()`:
geous.configure({
geocoder: 'google'
});
###geous.getUserLocation
A wrapper for the HTML5 location API that will return a Geous Location. `success` and `error` callbacks may be provided as options to handle the corresponding events:
geous.getUserLocation({
error: function () {
console.log('Something terrible has happened!');
},
success: function (location) {
console.log('User is at: ', location.coords);
}
});
Adding `geocode: true` to the options hash will instruct geous to attempt to geocode the user's location.
geous.getUserLocation({
geocode: true,
success: function (location) {
console.log('Geocoded location:', location.toAddress());
}
});
Geous + jQuery
--------------
Geous includes a jQuery plugin (jquery.geousable) for translating between HTML inputs and `geous.Location` objects.
### configuration
Get started by including geous, jquery, and the jquery.geousable plugin:
jQuery selectors will now have access to the `geousable` plugin. Pass configuration settings when first initializing it on a selector. For instance, to allow the plugin to overwrite existing content in related fields and elements, set the `overwrite` option:
$('form').geousable({
overwrite: true
});
Options include:
Option
Type
Description
defaultMapPattern
String
The pattern used to map field names to CSS-selectors.
Default: '.{%}'
errorHandler
Function
General error handler to be passed as the default error parameter to geous requests
map
Object
A map of the fields of a geous.Location object (address, city, state, etc.) to a corresponding CSS selector. If null is supplied, an appropriate selector will be constructed from the field's name and the defaultMapPattern parameter
onFieldError
Function
Callback to call when a lookup fails to populate a field using setLocation. Callbacks specified using onFieldError should accept a jQuery selector containing the field in question ($field) as their only parameter.
onFieldSuccess
Function
Callback to call when a lookup successfully populates a field using setLocation. Callbacks specified using onFieldError should accept a jQuery selector containing the field in question ($field) as their only parameter.
overwrite
Boolean
Allow setLocation to overwrite fields with existing content?
default: false
### getLocation()
With `geous.js` and `jquery.geousable.js` included, location fields may be retrieved directly from an HTML form:
$('form').submit(function (e) {
e.preventDefault();
var location = $(this).geousable('getLocation');
console.log(location);
});
### setLocation()
Similarly, a `Location` may be assigned directly to the form:
var location = new geous.Location({
address: '123 ABC st',
city: 'Akron',
state: 'Ohio'
});
$('form').geousable('setLocation', location);
### geocode()
Finally, the `Location` described by a form may be completed via a geocoding request:
$('form').geousable('geocode', {
success: function (location) {
console.log(location);
}
});
Geocoders
---------
Geous ships with support for Google's Geocoding API, but other geocoding services may be used as well. To use an alternate geocoder, wrap the geocoder in a module that exposes a `geocode()` method (see `src/geocoders`). If you author a wrapper for another service, please don't hesitate to contribute!
If you choose to rely on the Google Geocoding API, please be sure that your application conforms to its terms of service.
License
----------------
geous.js is released under the JSON License. You can read the license [here](http://www.json.org/license.html)