**Geolocator**.js is a utility for getting geo-location information, geocoding, address look-ups, distance & durations, timezone information and more... ## Features - HTML5 geolocation (by user permission) with **improved accuracy**. - Location by IP - Reverse Geocoding (address lookup) - Full address information (street, town, neighborhood, region, country, country code, postal code, etc...) - Fallback mechanism (from HTML5-geolocation to Geo-IP lookup) - Watch geographic position - Locate by mobile information - Get timezone information - Get distance matrix and duration information - Calculate distance between two geographic points - Various geographic conversion utilities - Get client IP - Fetched location includes country flag image (SVG) URL - Language support (depends on the service provider) - Supports Google Loader (loads Google APIs dynamically) - Dynamically create Google Maps, **on demand** (with marker, info window, auto-adjusted zoom) - Get static Google Map (image) URL for a location - Non-blocking script loading (external sources are loaded on the fly without interrupting page load) - No library/framework dependencies (such as jQuery, etc...) - Universal module (CommonJS/AMD..) - Small file size (9KB minified, gzipped) - Browser Support: IE 9+, Chrome, Safari, Firefox, Opera... See a [**Live Demo**](https://onury.github.io/geolocator/?content=examples). ## Get Geolocator.js - Link or download via [**CDNJS**][cdnjs]. - Download full source code from [GitHub releases][releases]. - Install via **Bower**: `bower install geolocator` - Install via **NPM**: `npm install geolocator` ## Usage: Example below, will attempt to get user's geo-location via HTML5 Geolocation and if user rejects, it will fallback to IP based geo-location. Inside the `` of your HTML: ```html ``` If you've enabled `map` option; include the following, inside the `` of your HTML: ```html

``` Read [**API documentation**][api-docs] for lots of other features and examples. ## Important Notes - Since Geolocation API is an HTML5 feature, make sure your `doctype` is HTML5 (e.g. ``). - Make sure you're calling Geolocation APIs (such as `geolocator.locate()` and `geolocator.watch()`) from a secure origin (i.e. an **HTTPS** page). In Chrome 50+, Geolocation API is [removed][chrome-unsecure] from **unsecured origins**. Other browsers are expected to follow. - Although some calls might work without a key, it is generally required by most Google APIs (such as Time Zone API). To get a free (or premium) key, [click here][google-docs]. After getting a key, you can enable multiple APIs for it. Make sure you [enable][google-console] all the APIs supported by Geolocator. *(If you don't have a key, you can still use Geolocator like the previous versions, but with limited features.)* - Geolocator now uses a single Geo-IP provider ([GeoJS](https://www.geojs.io) for locating by IP. You can use `geolcoator.setGeoIPSource()` method to set a [different Geo-IP source][geo-src], but see the [Caveats](#caveats) section before you do so. - **Most importantly**; please use this library for anonymous usage data only. And **get consent** from your users that you're collecting their **personal data** and present your reasons. ## Caveats - **[Mixed Content](https://developers.google.com/web/fundamentals/security/prevent-mixed-content/what-is-mixed-content) Restriction**: There are [alternative Geo-IP services][geo-src] to be used with this library. But most of these services do not provide a free API over HTTPS (SSL/TLS). You need to subscribe for a premium API key to use HTTPS. The caveat is; HTML5 Geolocation API is restricted to HTTPS and when you enable the `fallbackToIP` option, some browsers (such as Chrome and Firefox) will not allow mixed content. It will [block](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content/How_to_fix_website_with_mixed_content) HTTP content when the page is served over HTTPS. Currently, Geolocator will use [GeoJS](https://www.geojs.io) by default which is free and supports HTTPS. **Please use this service responsibly**. For example, do NOT call `locate()` or `.locatebyIP()` on every user/request but only on site entrance. Their location or IP will not change suddenly unless they can teleport!.. Also, [**support GeoJS**](https://www.geojs.io) if you can so we can continue using this nice free service. If you know other free Geo-IP services over HTTPS, let me know and we can add/use them as alternatives. - **Isomorphic Applications / SSR Support**: This library currently only works on client-side (browser). Any kind of server-side functionality (including Server Side Rendering) is not yet oficially supported. There is a [discussion](https://github.com/onury/geolocator/issues/55) about at least preventing it from throwing on server; or maybe adding support for some (if not all) methods to work on server. If you're interested and willing to contribute; - Continue discussion on [this thread](https://github.com/onury/geolocator/issues/55), - PRs are welcome since I need help improving and maintaining this library. ## Under the Hood Geolocator v2 is written in ES2015 (ES6), compiled with [Babel][babel], bundled with [Webpack][webpack] and documented with [Docma][docma]. ## Change Log See version changes [here][changelog]. ## License MIT. See the [Disclaimer][disclaimer] and [License][license]. [api-docs]:https://onury.github.io/geolocator/?api=geolocator [changelog]:https://onury.github.io/geolocator/?content=changelog [license]: https://github.com/onury/geolocator/blob/master/LICENSE [disclaimer]: https://github.com/onury/geolocator/blob/master/DISCLAIMER [uncompressed]: https://raw.github.com/onury/geolocator/master/src/geolocator.js [compressed]: https://raw.github.com/onury/geolocator/master/src/geolocator.min.js [cdnjs]:https://cdnjs.com/libraries/geolocator [demo]: http://rawgit.com/onury/geolocator/master/example/index.html [geo-src]:https://github.com/onury/geolocator/tree/master/src/geo-ip-sources [example-img]: https://raw.github.com/onury/geolocator/master/screenshots/geolocator-example.jpg [npm-package]: https://www.npmjs.com/package/geolocator [releases]:https://github.com/onury/geolocator/releases [legacy-version]:https://github.com/onury/geolocator/releases/tag/v1.2.9 [babel]:https://github.com/babel/babel [webpack]:https://github.com/webpack/webpack [docma]:https://github.com/onury/docma [google-docs]:https://developers.google.com/maps/documentation/javascript [google-console]:https://console.developers.google.com [chrome-unsecure]:https://developers.google.com/web/updates/2016/04/geolocation-on-secure-contexts-only?hl=en [bug-884921]:https://bugzilla.mozilla.org/show_bug.cgi?id=884921 [bug-675533]:https://bugzilla.mozilla.org/show_bug.cgi?id=675533