_{© 2019, Onur Yıldırım (@onury). Please see the Disclaimer and License.}

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.

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 for locating by IP. You can use geolcoator.setGeoIPSource() method to set a [different Geo-IP source][geo-src], but see the 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 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 HTTP content when the page is served over HTTPS.

Currently, Geolocator will use GeoJS 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 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 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,
- 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