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

• Authentication
  • Learn how Geoloqi handles authentication using OAuth 2.
• De-Duplication and Extra Parameters
  • Adding custom info to various objects.
• Time and Dates
  • Geoloqi has flexible ways for handling dates and times across multiple time zones.
• Paging
  • Learn how Geoloqi handles paging through large sets of data.
• Error Codes
  • Learn how to handle errors from the Geoloqi API.

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 support@geoloqi.com 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.

• location/last (GET)
  • Query the user's last location
• location/history (GET)
  • Query the user's location history, by date range or bounding box
• location/update (POST)
  • Update the user's location with an array of data points
• location/delete_batch/:id (POST)
  • Delete location data from the system
• location/tracking_profile (GET, POST)
  • Use this method to switch the phone into a different tracking profile.

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.

• layer/create (POST)
  • Create a new layer.
• layer/nearby (GET)
  • Find nearby layers given a latitude and longitude.
• layer/list (GET)
  • List all layers the authenticating user has created
• layer/subscriptions (GET)
  • List all layers the authenticating user is subscribed to
• layer/info/:id (GET)
  • Return information about the layer specified by "id"
• layer/update/:id (POST)
  • Update information about the layer specified by "id"
• layer/delete/:id (POST)
  • Delete the specified layer
• layer/subscribe/:id (POST)
  • Subscribe to a layer
• layer/unsubscribe/:id (POST)
  • Unsubscribe from a layer
• layer/subscription/:id (GET, POST)
  • Set or retrieve meta information about the user's subscription to the layer
• layer/users/:id (GET)
  • Get a list of users who are inside any places on the 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.

• group/create (POST)
  • Create a new group
• group/update/:token (POST)
  • Update basic information about a group
• group/delete/:token (POST)
  • Delete a group
• group/join/:token (POST)
  • Join a group. This will cause this user's location to be broadcast to everyone watching the group.
• group/leave/:token (POST)
  • Leave a group. The user's location updates will no longer be broadcast to the group.
• group/message/:token (POST)
  • Sends a message to the group channel. Only members who have 'publishing' permission can send messages.
• group/list (GET)
  • Retrieve a list of groups created by the user
• group/info/:token (GET)
  • Retrieve basic information about a group
• group/members/:token (GET)
  • Retrieve a list of users in the group
• group/subscriptions (GET)
  • Retrieve a list of groups the user is part of
• group/messages/:token (GET)
  • Retrieve the history of messages sent to this group
• group/locations/:token (GET)
  • Retrieve the history of location updates sent to this group

Streaming

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

• Using the Geoloqi Streaming Server

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.

• message/send (POST)
  • Send a message to a single user
• message/broadcast (POST)
  • Send a message to all users within a specific region
• message/count_broadcast (POST)
  • Count the number of people that will receive your broadcast
• message/device (POST)
  • Send a JSON payload to a device via its socket connection

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.

• application/list (GET)
  • Retrieves a list of applications created by the authenticating user
• application/info/:id (GET)
  • Gets info about the specified application
• application/layers/:id (GET)
  • Retrieves a list of layers created by the application
• application/usage/:id (GET)
  • Retrieves usage information about the number of triggers and messages used by this application
• application/api_hits/:id (GET)
  • Retrieves usage information about the number of API calls made by this 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