Esri's Geotrigger Service is replacing Geoloqi! Learn More | FAQ

Javascript Library for Browsers

To get you started quickly your personal access token is included in these examples. However you should use an application access token instead, which you can get from the applications page.

Log in to get your personal access token

Similar to Facebook's connect-js, this library allows you to develop rich web applications using only javascript. There are no backend/server requirements - all you need to get started is a web browser and a text editor!

You can get it from our CDN!

<script type="text/javascript" src="https://api.geoloqi.com/js/geoloqi.min.js"></script>

This file will always be the latest version. If you'd prefer to fix to a specific version, check the versions folder:

<script type="text/javascript" src="https://api.geoloqi.com/js/versions/geoloqi-1.0.13.min.js"></script>

Usage

This first example only requires an access token, which all user accounts receive automatically. You can retrieve yours at the Geoloqi Developers Site. You can get an application access token from your applications page.

You should never use your access token in production applications as it would allow anyone who can load the page to read/write your data. It is only used here for demonstration purposes.

<!DOCTYPE html>
<html>
  <head>
    <script type="text/javascript" src="http://api.geoloqi.com/js/geoloqi.min.js"></script>
    <script type="text/javascript">
      window.onload = function () {
        geoloqi.init({
          client_id: "YOUR_API_KEY (optional but recommended)"
        });
        geoloqi.auth = {'access_token': 'YOUR_USER_OR_APPLICATION_ACCESS_TOKEN'};

        function getLastLocation() {
          geoloqi.get('location/last', function(result, error) {
            console.log(result);
          });
        }

        function changeProfileWebsite() {
          geoloqi.post('account/profile', {'website':'http://example.org/my_cool_site'}, function(result, error) {
            console.log(result);
          });
        }
      }
    </script>
    <title>Geoloqi Client JS Test with Access Token</title>
  </head>
  <body>
    <a href="#" onclick="getLastLocation(); return false">Get Last Location</a>
    <br>
    <a href="#" onclick="changeProfileWebsite(); return false">Change Profile Website</a>
    <br>
  </body>
</html>

Warning: OAuth features will be depricated in a future version of the Javascript API.

Want to make an application with OAuth2? Create an application at the Geoloqi Developers Site and try this:

<html>
  <head>
    <script type="text/javascript" src="https://api.geoloqi.com/js/geoloqi.min.js"></script>
    <script type="text/javascript">
      window.onload = function () {
        geoloqi.init({'client_id': 'YOUR_API_KEY_FROM_DEVELOPERS.GEOLOQI.COM'});
      }

      function getProfile() {
        geoloqi.get('account/profile', function(result, error) {
          console.log(result);
        });
      }
    </script>
    <title>Geoloqi Client JS Test</title>
  </head>
  <body>
    <div id="geoloqi-root" style="display:none;"></div>
    <a href="#" onclick="geoloqi.authenticate(); return false">Login Directly</a>
    <br>
    <a href="#" onclick="geoloqi.authenticateWithPopup(); return false">Login via popup (not supported in IE)</a>
    <br>
    <a href="#" onclick="getProfile(); return false">Get Profile</a>
    <br>
    <a href="#" onclick="geoloqi.expire(); return false">Logout</a>
    <br><br>
  </body>
</html>

Configuring and Initializing

Before geoloqi.js can be used you must run the geoloqi.init() method. There are no required options although it is recommended you set the client_id option to track usage statistics. (Click "Usage" on your applications list)

geoloqi.init({
  client_id: 'STRING', // Your applications api key here (https://developers.geoloqi.com/account/applications)
  package_name: 'STRING', // An optional name for your package to be tracked at https://developers.geoloqi.com/account
  package_version: 'STRING', // An optional name for your package to be tracked at https://developers.geoloqi.com/account
  persist: 'STRING' // Sets the persistence method used to store user sessions. Uses 'localStorage' or 'cookies'
});

Authentication

Once you have initialized the library you should authenticate the user. There are several methods for authentication including OAuth (via http://geoloqi.com) which will give you access to the users http://geoloqi.com account. You can provide a username and password, or simply pass in a user's access_token (for cases where a user might already have a session on your server).

You can register a callback for user authentication events with geoloqi.onAuthorize:

geoloqi.init({
  client_id: "ABC123"
});

geoloqi.onAuthorize = function(response, error){
  console.log(response, error);
}

geoloqi.login("email", "password")

You can also listen for an authentication error by setting onOAuthError or onLoginError:

geoloqi.onOAuthError = function(error){
  console.log(error)
}

geoloqi.onLoginError = function(error){
  console.log(error)
}

Via OAuth

Warning: OAuth features will be depricated in a future version of the Javascript API.

There are three OAuth methods available. You must pass a client_id to geoloqi.init() to use these methods.

  • geoloqi.authenticate() - Shortcut for geoloqi.authenticateWithPopup()
  • geoloqi.authenticateWithRedirect() - Will send the user to Geoloqi's OAuth page and redirect them to your application's redirect url upon completion.
  • geoloqi.authenticateWithPopup() - Will attempt to use a popup to authenticate the user instead of a redirect.

geoloqi.authenticateWithPopup() does not work in some older versions of Internet Explorer.

With Email and Password

If you want a user to login to an account you have created with user/create you can use the login method: geoloqi.login(email, password). You must set client_id when you call geoloqi.init() to use this method.

geoloqi.init({
  client_id: "ABC123"
});

// Will be called upon a successful login
geoloqi.onAuthorize = function(response, error){
  console.log(response, error);
}

// Will be called upon a failed login
geoloqi.onLoginError = function(error){
  console.log(response, error);
}

geoloqi.login("email", "password")

With Access Token

If you want to set a user's access token without any additional authentication, you can do do by setting geoloqi.auth.

geoloqi.auth = {
  access_token = "YOUR_USER_OR_APPLICATION_ACCESS_TOKEN"
}

Making API Requests

To make requests to the Geoloqi API you will need to authenticate the user with geoloqi.login(username, password), geoloqi.authenticate() or geoloqi.authenticateWithPopup().

Once the user is authenticated you can use geoloqi.get() or geoloqi.post() to make requests.

GET

Example: geoloqi.get(method, params, callback, context)

  • method is the API method you want to run. You can find a full list of API methods here.
  • arguments is an optional object that will encoded as a query string before being sent to the API.
  • callback is a function that will be run when the request is complete. Receives response and error arguments (example: function(response, error) {}).
  • context optional, will bind the callback function to the given context. Similar to _.bind and jQuery.proxy.

Examples

Get the authenticated user's profile

geoloqi.get('account/profile', function(response, error){
  console.log(response, error);
});

Get nearby places

geoloqi.get('place/nearby', {
  latitude: 45.516454,
  longitude: -122.675997,
  radius: 100
}, function(response, error){
    console.log(response, error);
});

Get the users last known location and run the callback where this = User

User = {
  latitude: null,
  longitude: null
};

//arguments are optional
geoloqi.get('location/last', function(response, error){
  this.latitude = response.location.position.latitude;
  this.longitude = response.location.position.longitude;
}, User);

POST

Example: geoloqi.post(method, params, callback, context)

  • method the API method you want to run. You can find a full list of API methods here.
  • patams an object that will encoded as a query string or post body before being sent to the API.
  • callback a function that will be run when the request is complete. Receives response and error arguments (example: function(response, error) {}).
  • context optional, will bind the callback function to the given context. Similar to _.bind and jQuery.proxy.

Examples

Update the user's profile:

geoloqi.post("account/profile", {
    'website': "http://mycoolsite.com"
}, function(response, error){
    console.log(response, error);
});

Create a new place for the user:

geoloqi.post("place/create", {
  latitude: 45.516454,
  longitude: -122.675997,
  radius: 100,
  name: "Geoloqi Office"
}, function(response, error){
    console.log(response, error)
});

Create a new geotrigger. There are lots of options - please read the trigger/create documentation.

geoloqi.post("trigger/create", {
  place_name: "Geoloqi Office"
  latitude: 45.516454,
  longitude: -122.675997,
  radius: 100,
  trigger_on: "enter"
  type: "message",
  text: "Welcome To Geoloqi HQ"
}, function(response, error){
    console.log(response, error)
});

Batch Requests

The Geoloqi API supports running multiple requests at once through the batch/run method. you can use the geoloqi.Batch() object to build batch requests and send them to the API. This is particularly good for things such as initialization functions where you may want to make multiple requests at once, or imports of large sets of data.

To use the batch API create a new batch object by calling new geoloqi.Batch() there are no options for this object. Once you have a batch object you can chain .get("method", params, headers) and .post("method", params, headers) methods to build up your batch request.

When you are finished building your batch request use the run(callback, context) to send the request to our servers. For more information on the batch api see batch/run.

Notes: Complicated batch requests or batch requests to complex methods like location/history may take a very long time to respond or even timeout.

MyApp = {
  places: [],
  user: {
    profile: {},
    location: {}
  }
}

batch = new geoloqi.Batch();

batch.get("account/profile")
     .get("place/list", {limit: 50})
     .get("location/last");

// Run with a context. this will be MyApp in your callback function
init_batch.run(function(response){
  // response.result is an array of responses in the order you requested them.
  console.log(response.result);
  this.places = response.result[0].body.places;
  this.user.profile = response.result[1].body;
  this.user.location = response.result[2].body;
}, MyApp);

// Run without a context
init_batch.run(function(response){
  // response.result is an array of responses in the order you requested them.
  MyApp.places = response.result[0].body.places
  MyApp.user.profile = response.result[1].body
  MyApp.user.location = response.result[2].body
});

HTML5 Geolocation Helpers

Using HTML5s new geolocation features, you can update user's locations in the Geoloqi API with geoloqi.js once you have authenticated the user.

Caveats: These helpers implement HTML5s navigator.geolocation features, they DO NOT allow for battery safe geofencing or for updating location in the background. They will work only as long as the device is awake and the page has focus. These functions designed to quickly update user's locations from a web page for a short period of time.

Update locations

You can use geoloqi.updateLocation() to make a one time update to a user's location. It uses the standard navigator.geolocation.getCurrentPosition function under the hood and sends the results to the Geoloqi API and a optional callback function.

Options

  • success: a function that will be run after successfully updating a user's location. Will receive a HTML5 position object as it's parameter.
  • error: function will be run if there was an error getting or updating the user's location.
  • context: an object to bind the context of the callback functions.

Example

geoloqi.updateLocation({
  success: function(position){
    console.log("updated users position", position);
  },
  error: function(){
    console.log("there was an error");
  }
});

Watch for location changes

You can use geoloqi.watchPosition() to update a user's location as it changes. Implements navigator.geolocation.watchPosition under the hood and sends each point to the Geoloqi API and a callback function.

Options

  • success: a function that will be run after successfully updating a user's location. Will receive a HTML5 position object as its parameter.
  • error: function will be run if there was an error getting or updating the user's location.
  • context: an object to bind the context of the callback functions.

Example

// when initialized, this will start watching a user's location automatically
watch_user = new geoloqi.watchPosition({
  success: function(position){
    console.log("updated user's position", position);
  },
  error: function(){
    console.log("there was an error");
  }
});

// stop watching a users location
watch_user.stop();

// start watching a users location again
watch_user.start();

Socket.io and Realtime Location

geoloqi.js has support for listening to Geoloqi's socket.io server to listen to realtime location data. To get started you will need the socket.io library which you can get on our CDN.

<script src="https://subscribe.geoloqi.com/socket.io/socket.io.js" type="text/javascript"></script>

Once you have the socket.io library create a new geoloqi.Socket object.

socket = new geoloqi.Socket("AUTHENTICATION_TYPE", "TOKEN", {
  location: function(data){
    console.log(data)
  }
});
socket.start();

The AUTHENTICATION_TYPE can be "trip", "group" or "user". For trips and groups, the token is returned from a call to trip/create or group/create. For users, you must enable public location on a user's account (user/:id or account/profile) and pass the user's username as the token.

Listen for location updates from a group

socket = new geoloqi.Socket("group", "12345", {
  location: function(data){
    console.log(data)
  }
});
socket.start();

Listen for location updates from a trip token

socket = new geoloqi.Socket("trip", "1234567", {
  location: function(data){
    console.log(data)
  }
});
socket.start();

Found a bug?

Let us know! Send a pull request or a patch. Questions? Ask! We're here to help. File issues on Github, or look at our other support options including IRC and community forums.

Authors

Roadmap

  • Expanded geoloqi.Socket object with more options
  • Support for CORS (Cross Origin Resource Sharing)
  • Callback options for login and authenticate methods