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

The Geoloqi API

API Version

Current API version: 1

The base URL for all api methods is currently: https://api.geoloqi.com/1/

Note: You don't need an API key to write applications that will access your own account. Read the cURL examples or Client Libraries for instructions on getting started with the API quickly.

Introduction

Triggers

Triggers are geofences. When a user enters or exits a location, or dwells in a place for a period of time, a trigger will activate, sending a message to the user, or a callback to your web server with a provided URL.

  • trigger/create (POST)
    • Create a new trigger. The trigger can be attached to a place or a layer, or a place can be automatically created for the trigger.
  • trigger/delete (POST)
    • Delete a previously created trigger.
  • trigger/list (GET, POST)
    • List triggers associated with a place or a layer.
  • trigger/history (GET)
    • Retrieves trigger history for a user, a layer, or a place.
  • trigger/run/:id (POST)
    • Manually run a trigger. Useful for testing.
  • Trigger Callback
    • This is an example of what the Geoloqi API will send to your URL when a callback is triggered.

Geonotes

Geonotes are location-based messages that are sent to a user when they arrive at a location. These API methods are provided for convenience when developing an app like our Geonotes app. Typically you won't need to use these, and you should use the trigger and place methods instead.

  • geonote/create (POST)
    • Create a new Geonote given a latitude, longitude and radius. Internally, this creates a new place and an associated message trigger.
  • geonote/list_set (GET)
    • Retrieve a list of all undelivered Geonotes.
  • geonote/list_recent (GET)
    • Retrieve a list of all delivered Geonotes.
  • geonote/info/:id (GET)
    • Retrieve info about a single Geonote

Location

These API calls are for working with the user's location. The iOS and Android SDKs automatically update a user's location, so getting the current location and getting the location history are probably most useful here. If you are updating a user's location through a different mechanism than the SDK, location/update allows you to update the user's location manually. There is also a call for removing locations that have been stored in the system.

Note: By default, all apps created after August 13, 2013 do not store location history for their users. If you would like to enable this feature, please contact [email protected] to request access. You will need to be able to demonstrate your application's need for storing and retrieving history, and we will work with you to find a paid plan that can accommodate your needs.

Places

Places are objects in the API that represent physical locations. All triggers have a place - when a trigger is created in our system with a latitude and longitude, a place is automatically created for the trigger.

Places allow you to manipulate the location separately from the trigger. You can do things like remove the trigger (but keep the place), or add multiple triggers. You can use the "key" to have a unique ID for your place, ensuring that you won't have duplicate place entries.

Places do not have to be permanently fixed in a specific location - they can move. If you have a place that is moving frequently (such as a vehicle or a food cart), you can update the place's location with a simple call to the API via place/update.

  • place/create (POST)
    • Create a new place in a layer
  • place/update/:id (POST)
    • Update a place
  • place/list (GET)
    • List all places on the specified layer
  • place/nearby (GET)
    • Find places nearby the user's last location or a specified location
  • place/info/:id (GET)
    • Return information about this place, including any triggers that are set, and possibly the last time the user was at this place.
  • place/delete/:id (POST)
    • Delete the specified place and all associated triggers

Layers

Layers represent a group of places. They are very helpful for sorting places, and for choosing which users will be subscribed to a set of places, in scenarios where not all users will see the same places.

Layers allow you to create global triggers. If you add a trigger to the layer, the trigger will be attached to every place on a layer. This way, you can have one trigger for multiple places, without having to create a lot of triggers.

In order to have a user receive updates from places on a layer, you need to subscribe the user to the layer with layer/subscribe. This allows you to have a set of places/triggers for one group of users, but not for others.

Layers can be edited in our graphical layer editor (available for personal layers.. coming soon for applications), and can be given a latitude, longitude and radius to assist in finding layers nearby to the user (layer/nearby).

Places and triggers do not necessarily require placement in a layer. However it is strongly recommended that you add places to a layer.

Users

Users represent each installed instance of your mobile application. When you start a new application on your phone with the Geoloqi SDK, it automatically calls user/create_anon on initial load, creating an anonymous user account for the application to use.

Note: All of the user methods require authentication with the application's client ID and secret. See Authentication for more information.

  • user/create (POST)
    • Create a new account given an email address and username. Returns OAuth tokens.
  • user/create_anon (POST)
    • Create a new anonymous account. Returns OAuth tokens.
  • user/list (GET)
    • Returns a list of all users created by this application.
  • user/info/:id (GET)
    • Return user profile for a user created by the application.
  • user/update/:id (POST)
    • Update user profile for a user created by the application.
  • user/delete/:id (POST)
    • Deletes a user that was created by the application.
  • user/secure_delete/:id (POST)
    • Securely deletes a user and removes all associated data.

Groups

Groups are a component of our high performance, real-time streaming service. A group is essentially a collections of users. When users are subscribed to a group, you can listen to the group via the Geoloqi streaming Socket.IO/Websockets server, and see location updates from users' phones in real-time. You can also efficiently broadcast a message to all users in a group.

Groups can be created with an application access token, or a user access token. If created using a user access token and set as "public", other users can subscribe to the group using their own user access tokens. Otherwise, an application access token is required to subscribe the user to the group.

Streaming

Geoloqi provides a real-time streaming service through Websockets and Socket.IO.

Account Methods

These API calls are used to retrieve information about the current user (via their access token).

  • account/username (GET)
    • GET: Get the username of the account corresponding to the OAuth tokens
  • account/check_username (POST)
    • GET: Check if a username is available to be registered
  • account/profile (GET, POST)
    • GET: Return profile information of the current user
    • POST: Update profile information of the current user
  • account/privacy (GET, POST)
    • GET: Get current privacy settings
    • POST: Update privacy settings (only available to pre-approved clients)
  • account/connections (GET)
    • Return the list of third-party app connections authorized on the user's account
  • account/set_apn_token (POST)
    • Called after the device registers for push notifications to store the push token in the API

Messaging

The Geoloqi Platform provides the ability to send messages to users, either with SMS or with push notifications for Android and iOS.

If you need to send a message to a lot of users at once, it is strongly recommend that you use a group to send a broadcast message. See Groups for more information.

Batched Requests

batch/run allows you to run a lot of requests to the API, without making individual requests. This will allow your scripts to run considerably faster, since there will only be one request made to the API. The results of the requests will be returned once they have finished.

This is very helpful for import scripts that have to add a lot of layers, places or triggers, because it will run much more quickly than doing a single request at a time. Here is a real-world example of how to integrate it into an import script.

  • batch/run (POST)
    • Run a batch of jobs on the server

Applications

You should create one Geoloqi application for each mobile application you develop. This can be done on the application management page. API calls will be made within the context of the application.

Share Links

Share Links allow you to temporarily (or permanently) share your location with others. When you create a link (link/create), it returns a token that you can use to view the user's location, either with an API call to share/info, or via a web browser using our real-time location streaming service (see Streaming). If you are using a share link privately, be sure to keep the token a secret!

Share links can be de-activated, re-activated, or expired. When expired, the share link is permanently ended, and cannot be re-activated.

  • link/create (POST)
    • Create a sharing link which will grant anybody with this token access to the user's location for the specified time period.
  • link/expire (POST)
    • Expire an existing sharing link so that it will no longer have access to the user's location.
  • link/activate (POST)
    • Re-activate a deactivated link so that it shows the user's location again.
  • link/deactivate (POST)
    • Deactivate a link so that it doesn't show the user's location. This is different from expiring, because deactivated links can be reactivated again. Once a link is expired, it will never be accessible again.
  • link/stats (GET)
    • Retrieve the statistics (number of viewers, referrers) for a shared link
  • share/last (GET)
    • Access the last location of a user given one or more shared tokens
  • share/history (GET)
    • Retrieve the location history of a user given a shared token
  • share/info (GET)
    • Retrieve the profile information and link meta information from a shared link token.

OAuth 2

  • Authentication
    • Direct the user to this URL to approve access to your app
  • oauth/token (POST)
    • Your server makes a POST request here given the auth token received in the previous step, you will receive an access token as the response.
    • This method may be called with the following grant_types:
      • authorization_code - an auth code received upon the redirect from the authorize step above
      • password: for mobile clients, if you have asked the user for their username/password in your app you can provide them directly to the API here
      • refresh_token: if you are refreshing your access token, provide your refresh token here
      • client_credentials: applications can get an access token for their own resources
      • assertion: applications can request access tokens for users they created