benconstable / where-am-i Goto Github PK

#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 [email protected]: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