Geolocator.js bundles HTML5 geolocation, IP lookup and Google Maps into one call

One locate call, three ways to find a position

Geolocator.js is described as a utility for getting geo-location information, geocoding, address look-ups, distance and durations, timezone information and more. The list of features is longer than that sentence, and the interesting design decision is the fallback chain.

The primary path is HTML5 geolocation, with the user's permission, and the README claims improved accuracy over the raw API. If that fails or is refused, there is a fallback to a Geo-IP lookup, and there is also a way to locate by mobile information, which uses carrier derived position rather than the device. The fallbackToIP option is what wires the chain together, and it is the feature that makes the library usable on a page where the user might click deny.

The rest of the surface builds on that position. There is reverse geocoding for an address lookup, full address information down to street, town, neighborhood, region, country, country code and postal code, and a country flag image as an SVG URL. There is timezone information, a distance matrix and duration information, distance between two points, and a set of geographic conversion utilities. You can watch the position rather than reading it once, and you can get the client IP.

The library has no runtime dependencies at all. The package.json dependencies object is empty, and the README says no library or framework dependencies such as jQuery are required. It is a universal module, CommonJS or AMD, and the README states a small file size of 9KB minified and gzipped. Browser support is listed as IE 9 and up, plus Chrome, Safari, Firefox and Opera.

The Google key is the configuration centre

Everything that needs a third party service is configured in one call before you use the library, and that call is where the Google API key goes.

<script type="text/javascript" src="geolocator.min.js"></script>
<script type="text/javascript">

    geolocator.config({
        language: "en",
        google: {
            version: "3",
            key: "YOUR-GOOGLE-API-KEY"
        }
    });

The google block carries a version and a key, and the README is explicit that a key is generally required by most Google APIs, naming the Time Zone API as an example. Without a key you can still use the library like the previous versions did, but with limited features.

The same section has a caveat that is easy to skim past. You have to enable all the APIs supported by Geolocator in the Google console for your key, so the key is not just a credential, it is a set of permissions. The language option is described as depending on the service provider, so the locale of the returned address is the provider's locale rather than something the library controls.

The library also supports the Google Loader, which loads the Google APIs dynamically, and it creates Google Maps on demand, with a marker, an info window and auto-adjusted zoom, and it can produce a static Google Map image URL for a location. Script loading is non-blocking, so the external sources are loaded on the fly without interrupting page load.

The options object is where the behaviour is decided

The call itself takes an options object and a callback. The options in the README's example cover accuracy, timeouts, caching, fallback and the optional features.

        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);
        });

Read in order, these map onto the native Geolocation API options, and the comments in the README do the explaining. enableHighAccuracy asks the device for a more precise fix. timeout is how long the call waits. maximumWait caps the total wait for the desired accuracy, which matters because a device may keep trying to improve the fix. maximumAge of 0 disables the cache, so the browser will not hand back a previously cached position. desiredAccuracy is expressed in meters, and 30 meters is a sensible urban figure.

Then the library's own options come in. fallbackToIP is what makes the failure path graceful. addressLookup and timezone both require a Google key, as the comments say. map takes the id of an interactive map element, or an options object instead of a string, and staticMap takes a boolean or options object to produce a static image URL.

The callback signature is the Node style one, err first, and the README's example returns early on error. That shape means the error object is where the failure reason lives, whether it was a permission refusal, a timeout, or a failed IP lookup.

The map element has to exist in the page

If you enable the map option, the element it names has to be in the document already, which the README handles with a one line example placed inside the body of the HTML:

<div id="map-canvas" style="width:600px;height:400px"></div>

This is worth noticing because it is the only structural requirement the library puts on your page. The map is not created for you in a container you do not control, it is attached to an element you provide, which is the behaviour you want if your layout already has a placeholder that resizes with the viewport, and the behaviour that surprises people if they expected a library owned container.

Two things follow from the way the map option is documented. Passing an id string is the simple case, and the map and staticMap options accept an options object instead, so the same call can be used for a static image URL, an interactive map, or both, as in the README example where both are enabled at once.

The library can also watch the position rather than reading it once, using geolocator.watch, and the README notes in passing that the Geolocation API calls should be made from a secure origin, meaning an HTTPS page. That is a browser requirement rather than a library one, but it is the reason the same code behaves differently in development, where you are often on http://localhost, and in production.

The free Geo-IP provider is the fragile part

This is the section to read before you ship. The README has a Caveats heading, and its first entry is about mixed content.

Geolocator uses a single Geo-IP provider by default, GeoJS, which is free and supports HTTPS. You can point it at a different source with the setGeoIPSource method, but the README says to read the caveats first, and here is why. Most alternative Geo-IP services do not provide a free API over HTTPS. You have to subscribe for a premium API key to use HTTPS. The 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, they will block HTTP content on an HTTPS page.

So the fallback path quietly depends on a free community service, and the alternative providers cost money. The README asks you to use GeoJS responsibly, with the specific instruction not to call locate() or locatebyIP() on every user or every request but only on site entrance, since a user's location or IP will not change suddenly unless they can teleport. It also asks you to support GeoJS if you can so the free service can continue.

That is a real operational dependency for a library that markets itself as having no dependencies. The dependency is not in the package.json, it is in the availability and the terms of a third party API.

The privacy guidance is in the same register. The README asks that the library be used for anonymous usage data only, that consent be obtained from users whose personal data is being collected, and that the reasons be presented to them. There is a DISCLAIMER file in the repository root alongside the LICENSE.

Client side only, and an old release tag

Two constraints frame any decision about this library.

The first is that it only works on the client side in the browser. The README states that this library currently only works on client side, that any kind of server side functionality including Server Side Rendering is not yet officially supported. If your application renders on the server, this library does not fit the architecture, and no configuration change will change that.

The second is the release history. The recent releases list shows v2.1.5 from 2019-01-09, v2.1.3 from 2018-04-02 and v2.1.1 from 2017-03-11. The version in package.json is 2.1.5, matching the newest tag. The last push was on 2026-10-19, so work is still happening in the repository, but there has been no tagged release since 2019, which means anyone installing from npm is installing code published seven years ago, and there is no release note telling you what changed in the meantime.

The repository layout shows a project that is still maintained in a conventional way. There is a src/ directory and a dist/ directory with the built bundle, a Gruntfile.js alongside a webpack.config.js, a test/ directory with jest configured to run against the built output in a jsdom environment with coverage collected from src/index.js, a bower.json for the older install path, a docma.json for the documentation, and an example/ directory with html, css, js and less. The build scripts produce a production and a development bundle with webpack, and the test script builds the dev bundle first and then runs jest verbose.

The licence is MIT and the author is Onur Yıldırım, with the copyright line in the README dated 2019.

Editorial conclusion

Adopt Geolocator.js if you are building a browser only application that needs a position with a graceful degradation path, and you are prepared to serve over HTTPS and to key a Google API for the address and timezone features. Do not adopt it for server side rendering, which the README says is not supported, and weigh the fact that the newest tagged release is 2.1.5 from 2019-01-09 even though the repository is still being pushed to. Before you depend on it, check the Google APIs you need enabled on your key, read the mixed content caveat if you plan to swap the default Geo-IP provider, and confirm that a client side only library matches your rendering model.

Frequently asked questions

Official sources

1. License: MIT
2. onury/geolocator on GitHub
3. Project website
4. README
5. Releases