{"id":13510249,"url":"https://github.com/onury/geolocator","last_synced_at":"2025-04-08T10:16:47.378Z","repository":{"id":548433,"uuid":"9737736","full_name":"onury/geolocator","owner":"onury","description":"A utility for getting geo-location information via HTML5 and IP look-ups, geocoding, address look-ups, distance and durations, timezone information and more...","archived":false,"fork":false,"pushed_at":"2022-12-08T01:35:30.000Z","size":4391,"stargazers_count":645,"open_issues_count":33,"forks_count":107,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-04-01T08:42:08.259Z","etag":null,"topics":["address","coordinates","distance","geo-location","geocode","html5","js","matrix","timezone"],"latest_commit_sha":null,"homepage":"https://onury.io/geolocator","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onury.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-28T23:12:07.000Z","updated_at":"2025-03-18T07:59:45.000Z","dependencies_parsed_at":"2022-08-06T09:15:45.380Z","dependency_job_id":null,"html_url":"https://github.com/onury/geolocator","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onury%2Fgeolocator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onury%2Fgeolocator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onury%2Fgeolocator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onury%2Fgeolocator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onury","download_url":"https://codeload.github.com/onury/geolocator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247819940,"owners_count":21001394,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["address","coordinates","distance","geo-location","geocode","html5","js","matrix","timezone"],"created_at":"2024-08-01T02:01:30.549Z","updated_at":"2025-04-08T10:16:47.336Z","avatar_url":"https://github.com/onury.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","js"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n    \u003ca href=\"https://github.com/onury/geolocator\"\u003e\n        \u003cimg width=\"340\" height=\"275\" src=\"https://raw.github.com/onury/geolocator/master/geolocator-logo.png\" /\u003e\n    \u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://cdnjs.com/libraries/geolocator\"\u003e\u003cimg src=\"https://img.shields.io/cdnjs/v/geolocator.svg?style=flat-square\" alt=\"CDNJS\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/geolocator\"\u003e\u003cimg src=\"http://img.shields.io/npm/v/geolocator.svg?style=flat-square\" alt=\"npm\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/onury/geolocator\"\u003e\u003cimg src=\"https://img.shields.io/github/release/onury/geolocator.svg?style=flat-square\" alt=\"release\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/onury/geolocator/blob/master/LICENSE\"\u003e\u003cimg src=\"http://img.shields.io/npm/l/geolocator.svg?style=flat-square\" alt=\"license\" /\u003e\u003c/a\u003e\n\u003cbr /\u003e\n\u003csub\u003e© 2019, Onur Yıldırım (\u003cb\u003e\u003ca href=\"https://github.com/onury\"\u003e@onury\u003c/a\u003e\u003c/b\u003e). Please see the \u003ca href=\"https://github.com/onury/geolocator/blob/master/DISCLAIMER\"\u003eDisclaimer\u003c/a\u003e and \u003ca href=\"https://github.com/onury/geolocator/blob/master/LICENSE\"\u003eLicense\u003c/a\u003e.\u003c/sub\u003e\n\u003c/p\u003e\n\u003cbr /\u003e\n\n**Geolocator**.js is a utility for getting geo-location information, geocoding, address look-ups, distance \u0026 durations, timezone information and more...\n\n## Features\n\n - HTML5 geolocation (by user permission) with **improved accuracy**.\n - Location by IP\n - Reverse Geocoding (address lookup)\n - Full address information (street, town, neighborhood, region, country, country code, postal code, etc...)\n - Fallback mechanism (from HTML5-geolocation to Geo-IP lookup)\n - Watch geographic position\n - Locate by mobile information\n - Get timezone information\n - Get distance matrix and duration information\n - Calculate distance between two geographic points\n - Various geographic conversion utilities\n - Get client IP\n - Fetched location includes country flag image (SVG) URL\n - Language support (depends on the service provider)\n - Supports Google Loader (loads Google APIs dynamically)\n - Dynamically create Google Maps, **on demand** (with marker, info window, auto-adjusted zoom)\n - Get static Google Map (image) URL for a location\n - Non-blocking script loading (external sources are loaded on the fly without interrupting page load)\n - No library/framework dependencies (such as jQuery, etc...)\n - Universal module (CommonJS/AMD..)\n - Small file size (9KB minified, gzipped)\n - Browser Support: IE 9+, Chrome, Safari, Firefox, Opera...\n\n## Get Geolocator.js\n\n- Link or download via [**CDNJS**][cdnjs].\n- Download full source code from [GitHub releases][releases].\n- Install via **Bower**: `bower install geolocator`\n- Install via **NPM**: `npm install geolocator`\n\n## Usage:\n\nExample below, will attempt to get user's geo-location via HTML5 Geolocation and if user rejects, it will fallback to IP based geo-location.\n\nInside the `\u003chead\u003e` of your HTML:\n```html\n\u003cscript type=\"text/javascript\" src=\"geolocator.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\"\u003e\n\n    geolocator.config({\n        language: \"en\",\n        google: {\n            version: \"3\",\n            key: \"YOUR-GOOGLE-API-KEY\"\n        }\n    });\n\n    window.onload = function () {\n        var options = {\n            enableHighAccuracy: true,\n            timeout: 5000,\n            maximumWait: 10000,     // max wait time for desired accuracy\n            maximumAge: 0,          // disable cache\n            desiredAccuracy: 30,    // meters\n            fallbackToIP: true,     // fallback to IP if Geolocation fails or rejected\n            addressLookup: true,    // requires Google API key if true\n            timezone: true,         // requires Google API key if true\n            map: \"map-canvas\",      // interactive map element id (or options object)\n            staticMap: true         // get a static map image URL (boolean or options object)\n        };\n        geolocator.locate(options, function (err, location) {\n            if (err) return console.log(err);\n            console.log(location);\n        });\n    };\n\n\u003c/script\u003e\n```\n\nIf you've enabled `map` option; include the following, inside the `\u003cbody\u003e` of your HTML:\n```html\n\u003cdiv id=\"map-canvas\" style=\"width:600px;height:400px\"\u003e\u003c/div\u003e\n```\nRead [**API documentation**][api-docs] for lots of other features and examples.\n\n## Important Notes\n\n- Since Geolocation API is an HTML5 feature, make sure your `doctype` is HTML5 (e.g. `\u003c!DOCTYPE html\u003e`).\n- 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.\n- 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.)*\n- 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.\n- **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.\n\n## Caveats\n\n- **[Mixed Content](https://developers.google.com/web/fundamentals/security/prevent-mixed-content/what-is-mixed-content) Restriction**:\n\n    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.\n\n    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!.. \n    \n    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.\n\n- **Isomorphic Applications / SSR Support**:\n\n    This library currently only works on client-side (browser). Any kind of server-side functionality (including Server Side Rendering) is not yet oficially supported.\n\n    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;\n\n    - Continue discussion on [this thread](https://github.com/onury/geolocator/issues/55),\n    - PRs are welcome since I need help improving and maintaining this library.\n\n## Under the Hood\n\nGeolocator v2 is written in ES2015 (ES6), compiled with [Babel][babel], bundled with [Webpack][webpack] and documented with [Docma][docma].\n\n## Change Log\n\nSee version changes [here][changelog].\n\n## License\n\nMIT. See the [Disclaimer][disclaimer] and [License][license].\n\n\n[api-docs]:https://onury.github.io/geolocator/?api=geolocator\n[changelog]:https://onury.github.io/geolocator/?content=changelog\n[license]: https://github.com/onury/geolocator/blob/master/LICENSE\n[disclaimer]: https://github.com/onury/geolocator/blob/master/DISCLAIMER\n[uncompressed]: https://raw.github.com/onury/geolocator/master/src/geolocator.js\n[compressed]: https://raw.github.com/onury/geolocator/master/src/geolocator.min.js\n[cdnjs]:https://cdnjs.com/libraries/geolocator\n[demo]: http://rawgit.com/onury/geolocator/master/example/index.html\n[geo-src]:https://github.com/onury/geolocator/tree/master/src/geo-ip-sources\n[example-img]: https://raw.github.com/onury/geolocator/master/screenshots/geolocator-example.jpg\n[npm-package]: https://www.npmjs.com/package/geolocator\n[releases]:https://github.com/onury/geolocator/releases\n[legacy-version]:https://github.com/onury/geolocator/releases/tag/v1.2.9\n[babel]:https://github.com/babel/babel\n[webpack]:https://github.com/webpack/webpack\n[docma]:https://github.com/onury/docma\n[google-docs]:https://developers.google.com/maps/documentation/javascript\n[google-console]:https://console.developers.google.com\n[chrome-unsecure]:https://developers.google.com/web/updates/2016/04/geolocation-on-secure-contexts-only?hl=en\n[bug-884921]:https://bugzilla.mozilla.org/show_bug.cgi?id=884921\n[bug-675533]:https://bugzilla.mozilla.org/show_bug.cgi?id=675533\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonury%2Fgeolocator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonury%2Fgeolocator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonury%2Fgeolocator/lists"}