Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/onury/geolocator
A utility for getting geo-location information via HTML5 and IP look-ups, geocoding, address look-ups, distance and durations, timezone information and more...
https://github.com/onury/geolocator
address coordinates distance geo-location geocode html5 js matrix timezone
Last synced: 28 days ago
JSON representation
A utility for getting geo-location information via HTML5 and IP look-ups, geocoding, address look-ups, distance and durations, timezone information and more...
- Host: GitHub
- URL: https://github.com/onury/geolocator
- Owner: onury
- License: mit
- Created: 2013-04-28T23:12:07.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2022-12-08T01:35:30.000Z (almost 2 years ago)
- Last Synced: 2024-04-25T21:21:55.934Z (7 months ago)
- Topics: address, coordinates, distance, geo-location, geocode, html5, js, matrix, timezone
- Language: JavaScript
- Homepage: https://onury.io/geolocator
- Size: 4.19 MB
- Stars: 640
- Watchers: 36
- Forks: 113
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
© 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...
## 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
geolocator.config({
language: "en",
google: {
version: "3",
key: "YOUR-GOOGLE-API-KEY"
}
});
window.onload = function () {
var options = {
enableHighAccuracy: true,
timeout: 5000,
maximumWait: 10000, // max wait time for desired accuracy
maximumAge: 0, // disable cache
desiredAccuracy: 30, // meters
fallbackToIP: true, // fallback to IP if Geolocation fails or rejected
addressLookup: true, // requires Google API key if true
timezone: true, // requires Google API key if true
map: "map-canvas", // interactive map element id (or options object)
staticMap: true // get a static map image URL (boolean or options object)
};
geolocator.locate(options, function (err, location) {
if (err) return console.log(err);
console.log(location);
});
};
```
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