A Geolocation API plugin for jQuery or Zepto
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


jQuery (Zepto) Geolocator


jQuery Geolocator is a plugin that takes a list of addresses and gets a distance and directions to each address from your current geolocation position. If available, it uses W3C Geolocation API (HTML5 Geolocation) to find your current location, and queries Google Maps API for distances to each address inside your list. If the visitor's browser is old and does not support the Geolocation API, the more inaccurate IP address based geolocation from Google is used.

This plugin is a fork of / based on HTML5-GeoLocation-jQuery-Plugin by teleject.

Why did I decide to make a new plugin instead of using the old one?

At first I only wanted to add some options to the original plugin, and fix variables that were leaking into the global scope. I soon realized that there were far more things that I wanted change inside the plugin, so I ended up rewriting many parts of the plugin code.


Click here for a demo


To use the plugin the following scripts/libraries are required, and should be included on your page:

  • jQuery (requires at least version 1.6) or Zepto (needs a custom build like this rake concat[-detect:-form:data:selector:fx_methods] dist you can find the mentioned custom build inside the dist folder)
  • Google JS API + API key
  • Google Maps API

How to use

1. Markup

You need to wrap each address inside your list item with Microformats hCard ADR defined classes, and somewhere inside the list item an element that has distance as its classname (that is where the distance for that address is printed). Classnames used in default markup can be changed via plugin options.

Example markup:

<div id="locations">
    <div class="adr">
      <span class="street-address">2907 E MLK Jr Blvd.</span>, 
      <span class="locality">Austin</span>, 
      <span class="region">TX</span>, 
      <span class="postal-code">78702</span>
    <div class="distance"></div>
    <div class="adr">
      <span class="street-address">Aleksanterinkatu 52</span>
      <span class="postal-code">00100</span>, 
      <span class="locality">Helsinki</span> 
      <span class="country-name">Finland</span>
    <div class="distance"></div>

If you want, you can optionally set latitude and longitude of the address as data attributes to .adr elements, to get more accurate results:

<div class="adr" data-latitude="##.######" data-longitude="##.######">

You can also have multiple unordered list elements with different addresses inside your locations element. However, you should only have one instance of the plugin running, since running multiple instances of the plugin seems to be quite buggy.

2. Needed scripts

Before you use the plugin, make sure that you have jQuery (or Zepto), Google JS API, Google Maps and jQuery Geolocator plugin linked inside your <head> tag, or before your ending </body> tag (recommended).

<script src="//www.google.com/jsapi?key=YOUR_GOOGLE_API_KEY"></script>
<script src="//maps.googleapis.com/maps/api/js?sensor=true"></script>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.0/jquery.min.js"></script>
<script src="js/jquery.geolocator.js"></script>

3. Javascript

After you have all script tags included, you can call the plugin on a list (unordered list, ul - by default) with your custom options. (Remember to wrap your code in jQuery's or Zepto's .ready() function)

Here we are changing the plugin to use kilometers instead of miles:

$(document).ready(function() {
	$("#locations").geolocator({ distanceBigStr: 'km', distanceSmallStr: 'm' });

You can also use the plugin without manually including Google API script tags, but it is not recommended since it will slow down the time it takes to find geolocation/distances as it has to load the Google APIs after the plugin has been initialized. This can be done with the apiKey option:

$(document).ready(function() {
	$("#locations").geolocator({ apiKey: 'YOUR_GOOGLE_API_KEY' });

If you later need to refresh the plugin, you can call it again on the same element without any options:


Info about Zepto support

Default build of Zepto.js does not provide all the methods that are needed, so you need to build a custom version of Zepto.

This is the custom build of Zepto that you can find inside the dist folder:

rake concat[-detect:-form:data:selector:fx_methods] dist

Plugin options: General settings

Following options can be used to customize the plugin:


Set to false if you don't want addresses to be sorted by distance automatically. Default: true.


Set to true if you want to disable automatic geolocating, and let the user manually geolocate using a link. Default: false.


<a href="#" id="check">Check geolocation</a>


A notification style for your 'getting geolocation...' text. 'fade' or 'show'. Default: 'show'.


An Google API key is needed if you want the plugin to download all Google APIs for you. Default: null.


Set to true to open all 'Show directions' links in a new browser tab/window. Default: false.


Set to true to enable debug mode. This mode logs all Geolocation and Google API errors to you browser's Javascript console. Default: false.

Plugin options: Elements


Element selector (a link element) for manualCheck setting. Default: '#check'.


Element selector (a link element) to recheck geolocation. Default: '#recheck'.


Element that displays your own location. Default: '#geodata'.


Element that displays a 'getting geolocation...' notification when the plugin is running. Default: '.notification'.


Parent element for a list (usually ul or ol). Default: 'ul'.


Child element for list items. Default: 'li'.


Element that displays the distance for each address. Has to be a child of listElem element. Default: '.distance'.


Element that holds each address. Has to be a child of listElem element. Microformats hCard ADR defined classes. Default: '.adr'.


Element that is appended to each list item. Has to be a child of listElem element. Default: '.maps-link'.


With this setting you can assign your main element like this $.geolocator({ locationsElem: '#locations' });. Default: null.

Plugin options: Language strings

You can change the default texts used by the plugin to your own language.


Language string for big distance (miles or kilometers). If default string miles is changed, kilometers will be used. Default: 'miles'.


Language string for small distance (meters). Default: 'meters'.


Language string for unknown distance. Default: 'unknown'.


Language string that is displayed when your location is not found. Default: 'Could not get your location'.


Language string for a Google Maps link that is showed next to each address. Default: 'Show directions'.

Plugin options: W3C Geolocation API options


Set to true if you want to get the most accurate location estimate possible. Getting geolocation might take longer if enabled. Default: false.


The number of milliseconds to wait before timing out. Default: 6000 (6 seconds).


Amount of time in milliseconds that the geolocation result is cached. Default: 60000 (1 minute).

Custom events

The following events are triggered on the element that is running jQuery Geolocator:

  • 'geolocator:fail' when getting geolocation (Geolocation API or Google) fails.
  • 'geolocator:done' when the script has finished running, and getting geolocation was successful.
  • 'geolocator:own-fail' when getting your own location failed.
  • 'geolocator:own-done' when getting your own location was successful.

You can listen to the events by using for example jQuery's .on() (or .bind()):

$("#locations").on("geolocator:done", function(){
  // do something

Browser support

The script uses Geolocation API in newer browsers. A fallback to a IP address based geolocation from Google is used in older browsers. It should work in Internet Explorer 7+, Firefox, Safari, Chrome and Opera. Even though the browser support is quite good, the performance might not be that good in older desktop and mobile browsers.

Reporting issues and bugs

If something is not working for you or you find a bug, please open a new issue at the issues section.


Developed by Krister Kari.


This software is released under the MIT license


  • 1.0.4 (19.08.2012) - Added support for Zepto.js
  • 1.0.3 (19.08.2012) - Added a workaround for Google API limitations and added Grunt as a build tool
  • 1.0.2 (01.05.2012) - added clearTimeout to fix a bug in older browsers, and did a small change to link creation
  • 1.0.1 (27.04.2012) - 'targetBlank' option for links, support for country names (.country-name) and small fixes to loops.
  • 1.0.0 (20.04.2012) - Initial release