where-am-i

Simple wrapper around several client-side geolocation APIs

Note - This is still a work in progress!

Installation

NPM (for Browserify)

$ npm install --save where-am-i

Script tag

Just include the dist/where-am-i.min.js file in a script tag on your page.

Usage

Via Browserify

var WhereAmI = require('where-am-i')
  , help = new WhereAmI()
 
help.findMe(
    function (place) {
        // Located successfully!
        console.log(place.lat)
        console.log(place.lng)
        console.log(place.country.name)
    }
  , function (err) {
        // Could not locate!
    }
)

Via script

<script src="dist/where-am-i.min.js"></script>
<script>
    var help = new WhereAmI()
 
    help.findMe(
        function (place) {
            // Located successfully!
            console.log(place.lat)
            console.log(place.lng)
            console.log(place.country.name)
        }
      , function (err) {
            // Could not locate!
        }
    )
</script> 

UMD is supported for AMD and Node-style module loaders.

Example

Checkout the example for more usage. You can run the example in your browser like:

$ git clone git@github.com:BenConstable/where-am-i.git
$ cd where-am-i/
$ npm install
$ [node_modules/.bin/]gulp example

API

WhereAmI object

var w = new WhereAmI([locator], [storage])

The constructor accepts 2 parameters. The first is the geolocation service to use, and the second is the caching backend to use. Both parameters are optional, with sensible defaults.

Available gelocation services:

• freegeoip (default): Locate via http://freegeoip.net/

Availble caches:

• localstorage (default): Store the geolocation result in local storage
• variable: Store the geolocation in a local variable

w.findMe(success, error, [fromStorage])

Locate a user. Accepts success and error callbacks, and optionally overriding the option to retrieve the data from storage if it exists (true by default). E.g:

w.findMe(
    function (place) {}
  , function (err) {}
)

WhereAmI.addLocatorAdapter(key, service)

Register a new geolocation adapter for use with the service.

The locator should provide locate(success, err) method. See the Free Geo IP adapter for an example.

WhereAmI.addStorageAdapter(key, service)

Register a new storage adapter for use with the service.

The storage adapter should provide hasLocated(), putPlace(place) and getPlace() methods. See the local storage adapter for an example.

Place object

p.lat

The geolocated latitude.

p.lng

The geolocated longitude.

p.country.iso

The geolocated ISO 3166-1 country code (e.g GB).

May be undefined if country could not be determined.

p.country.name

The geolocated country name (e.g United Kingdom).

May be undefined if country could not be determined.

p.country.region

The geolocated country region. Possible values are:

• Africa
• Antarctica
• Asia
• Europe
• North America
• Oceania
• South America

May be undefined if country could not be determined.

p.inCountry(isoCodes)

Check if the geolocated result is in the given country. Accepts an ISO code, or an array of codes.

If country info is not available, will return false.

p.inRegion(regions)

Check if the geolocated result is in the given region (see possible values above). Accepts a single region, or an array of regions. Each region can have an case and any amount of whitespace. E.g:

p.inRegion('North America')
p.inRegion('NORTH AMERICA')
p.inRegion('nOrTHAMerica')
p.inRegion(['North America', 'Europe'])

If country info is not available, will return false.

License

MIT © Ben Constable