Version: 1.2.9
Author: Onur Yıldırım © 2015
Source code licensed under the MIT License.
Please see the Disclaimer and License.
- HTML5 geolocation (by user permission)
- Location by IP (Supported source services: FreeGeoIP, GeoPlugin, WikiMedia)
- Reverse Geocoding (address lookup)
- Full address information (street, town, neighborhood, region, country, country code, postal code, etc...)
- Fallback mechanism (from HTML5-geolocation to IP-geo lookup)
- Supports Google Loader (loads Google Maps dynamically)
- Dynamically creates Google Maps (with marker, info window, auto-adjusted zoom)
- Non-blocking script loading (external sources are loaded on the fly without interrupting page load)
- No library/framework dependencies (such as jQuery, MooTools, etc...)
- Browser Support: IE 9+, Chrome, Safari, Firefox, Opera...
Direct Download:
Full Version 13KB (3.5KB gzipped), Minified Version 4KB (1.8KB gzipped)
Install via Bower:
bower install geolocatorInstall via NPM:
npm install geolocatorSee a live demo here.
Inside the <head> of your HTML:
<script type="text/javascript" src="geolocator.js"></script> <script type="text/javascript"> //The callback function executed when the location is fetched successfully. function onGeoSuccess(location) { console.log(location); } //The callback function executed when the location could not be fetched. function onGeoError(error) { console.log(error); } window.onload = function () { //geolocator.locateByIP(onGeoSuccess, onGeoError, 2, 'map-canvas'); var html5Options = { enableHighAccuracy: true, timeout: 6000, maximumAge: 0 }; geolocator.locate(onGeoSuccess, onGeoError, true, html5Options, 'map-canvas'); }; </script>Also place the line below, inside your <body> if you want to dynamically draw a map (you should also pass the element ID to the corresponding method for the map to be drawn):
<div id="map-canvas" style="width:600px;height:400px"></div>geolocator.js provides 3 useful methods:
Use this method to get the location via HTML5 geolocation.
geolocator.locate( successCallback, [errorCallback], [fallbackToIP], [html5Options], [mapCanvasId] )Parameters:
successCallbackFunction A callback function to be executed when the location is successfully fetched. The recentgeolocator.locationobject is passed to this callback, as the only argument.
errorCallbackFunction (optional, default:null) A callback function to be executed when the location could not be fetched due to an error. The recentPositionErrorobject is passed to this callback, as the only argument.
fallbackToIPBoolean|Number (optional, default:false) Specifies whether geolocator should fallback to IP geo-lookup when HTML5 geolocation is not supported, timeout expired, position is unavailable or permission rejected by the user. A positive integer value will indicate the index of the source ip-geo service (if the value is in range). Booleantruewill set the default ip-geo service index which is1(GeoPlugin). Valid values:0(use FreeGeoIP for ip-geo fallback),1ortrue(use GeoPlugin for ip-geo fallback),2(use Wikimedia for ip-geo fallback),falseor-1ornullor any other value (will disable ip-geo fallback)
html5OptionsObject (optional, default:null) HTML5 geolocation options. e.g.{ enableHighAccuracy: true, timeout: 6000, maximumAge: 0 }
Note: Set thetimeoutvalue to at least5000milliseconds; otherwise this may produce a timeout error (which will fallback to IP geo-lookups if enabled.)
mapCanvasIdString (optional, default:null) HTML element ID for the Google Maps canvas. If set to null, no map is drawn.
Example:
var html5Options = { enableHighAccuracy: true, timeout: 6000, maximumAge: 0 }; geolocator.locate(onGeoSuccess, onGeoError, true, html5Options, 'map-canvas');Use this method to get the location from the user's IP.
geolocator.locateByIP( successCallback, [errorCallback], [ipSourceIndex], [mapCanvasId] )Parameters:
successCallbackFunction A callback function to be executed when the location is successfully fetched. The recentgeolocator.locationobject is passed to this callback, as the only argument.
errorCallbackFunction (optional, default:null) A callback function to be executed when the location could not be fetched due to an error. The recentErrorobject is passed to this callback, as the only argument.
ipGeoSourceIndexInteger (optional, default:0) Indicates the index of the IP geo-lookup service. Valid values:0(FreeGeoIP),1(GeoPlugin),2(Wikimedia)
mapCanvasIdString (optional, default:null) HTML element ID for the Google Maps canvas. If set to null, no map is drawn.
Example:
geolocator.locateByIP(onGeoSuccess, onGeoError, 1, 'map-canvas');Checks whether the type of the given object is HTML5 PositionError and returns a Boolean value.
geolocator.isPositionError( error )Parameters:
errorObject Object to be checked.
##Properties
Provides the recent geo-location information.
Example Output:
{ address: { city: "New York", country: "United States", countryCode: "US", neighborhood: "Williamsburg", postalCode: "11211", region: "New York", street: "Bedford Avenue", streetNumber: "285", town: "Brooklyn" }, coords: { accuracy: 65, altitude: null, altitudeAccuracy: null, heading: null, latitude: 40.714224, longitude: -73.961452, speed: null }, map: { canvas: HTMLDivElement, //DOM element for the map map: Object, //google.maps.Map options: Object, //map options infoWindow: Object, //google.maps.InfoWindow marker: Object //google.maps.Marker }, formattedAddress: "285 Bedford Avenue, Brooklyn, NY 11211, USA", ipGeoSource: null, timestamp: 1360582737790 }version 1.2.9
- Improvement: Added HTTPS secure connection support for IP geo-sources. (Note: GeoPlugin does not support HTTPS. You should use FreeGeoIP or Wikimedia IP sources instead.). (Fixes Issue #11. PR: @iurisilvio,)
version 1.2.8
- Revision: Removed the
sensorparameter from Goole Maps loader, since it's not required anymore. - Revision: Bumped Google Maps version to
3.18. - Revision: Created NPM package.
- Revision: Created Bower package.
version 1.2.6
- Revision: The recent
ErrororPositionError(HTML5) is passed to error callbacks instead ofStringerror message. See updated documentation. Fixes issue #7. (This shouldn't be a breaking-change but do test your app if you decide to upgrade.) - Feature: Added new method:
isPositionError(). - Updated example. (Enable/disable HTML5-to-IP fallback.)
version 1.2.4
- Revision: Source scripts are now automatically removed from DOM after result is received.
- Bug-Fix:
errorCallbackwould not be invoked if IP geo-source service is not available. Fixes issue #6. - Revision: Changed default IP source to GeoPlugin (index:
1); since FreeGeoIP is occasionally down these days.
version 1.2.1
- Added License.
version 1.2.0
- Code optimizations.
- Now loads the latest release version of Google Maps (
3.15).
version 1.1.0
- JSLint compliant code.
- Minor code revisions.
version 0.9.5
- Google has deprecated
google.loader.ClientLocationAPI. As a result; Google (Loader) is removed from IP-Geo Sources. - Indexes changed for IP-Geo sources. New Indexes: FreeGeoIP (0), GeoPlugin (1), Wikimedia (2)