A javascript library for retrieving geolocation information via HTML5 and IP look-ups...
Version: 1.2.6
Author: Onur Yıldırım © 2015
Source code licensed under the MIT License.
Please see the Disclaimer and License.
###Features:
Direct Download:
Full Version 13KB (3.5KB gzipped), Minified Version 4KB (1.8KB gzipped)
Install via NPM:
npm install geolocator
See a live demo here.
###Usage:
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:
##Methods
###geolocator.locate()
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');
###geolocator.locateByIP()
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');
###geolocator.isPositionError()
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
###geolocator.location Object
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
}
###Change Log:
version 1.2.6
Error or PositionError (HTML5) is passed to error callbacks instead of String error message. See updated documentation. Fixes issue #7. (This shouldn't be a breaking-change but do test your app if you decide to upgrade.)isPositionError().version 1.2.4
errorCallback would not be invoked if IP geo-source service is not available. Fixes issue #6.1); since FreeGeoIP is occasionally down these days.version 1.2.1
version 1.2.0
version 1.1.0
version 0.9.5
Google has deprecated google.loader.ClientLocation API. 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)
isPositionError().Error or PositionError (HTML5) is passed to error callbacks instead of String error message. See updated documentation. Fixes issue #7. (This shouldn't be a breaking-change but do test your app if you decide to upgrade.)FAQs
A utility for getting geo-location information via HTML5 and IP look-ups, geocoding, address look-ups, distance and durations, timezone information and more...
The npm package geolocator receives a total of 2,233 weekly downloads. As such, geolocator popularity was classified as popular.
We found that geolocator demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.