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

Introduction to Layers, Places and Triggers


Triggers are geofences, the basic building block of the Geoloqi API. When a user enters, exits, or dwells in an area defined by a trigger, you can have the trigger send a message to the user's phone, or have it send an HTTP POST to your server. Triggers recur automatically by default, but they can be configured to run only once per user. They can also be configured to run only in a specific date/time range.

You can create a trigger with the trigger/create call. Here is an example of creating a trigger using the cURL command. For the POST body, you can use either JSON (recommended) or form-encoded:

curl -H "Authorization: OAuth YOUR_APPLICATION\_ACCESS\_TOKEN" \ \
     -d '{"key":"powells_books","type":"message","latitude":45.523334,"longitude":-122.681612,"radius":300,"text":"Powell\'s books is nearby","place_name":"Powell\'s Books"}'

This will create a message trigger for your application. It will send a message to a user's phone using the SDK if the user's phone is within 300 meters of Powell's books.

Creating a callback trigger is similar. You set the type to callback, and provide a url to your server:

curl -H "Authorization: OAuth YOUR_APPLICATION\_ACCESS\_TOKEN" \ \
     -d '{"key":"powells_books","type":"callback","url":"http://yourserver/incoming_geoloqi_triggers","latitude":45.523334,"longitude":-122.681612,"radius":300,"text":"Powells books is nearby","place_name":"Powells Books"}'

Now when a phone enters this trigger, a JSON payload will be sent to your server. You can parse the payload to retrieve user profile data and information about the location that was triggered and take whatever action you want. Click here to see an example of what the callback payload looks like.

If you set the trigger to callback, it will not send a message to the phone directly, even if the text parameter is set. You will need to send a message to the phone from your server using an API call with the user_id provided by the trigger JSON payload. This is useful because it allows you to program the message sent. For example, if you wanted to tell the user how many times he/she has been to a place:

curl -H "Authorization: OAuth YOUR_APPLICATION\_ACCESS\_TOKEN" \ \
     -d '{"user_id":"123f","text":"Welcome to Powells books, you have been here 5 times"}'

While developing, it is useful to be able to run a trigger immediately and see what the API will send to the callback URL. You can do this by using the trigger/run/:id call. This will simulate the trigger being run so you can have an easier time testing your code.

Trigger API Methods


Places are a way to organize triggers in a way that reduces duplicate information. For example, if you wanted to create an "enter" and an "exit" trigger at the same location, you could use a place for that, and add two triggers without coordinates to that place. First you would create the place with the latitude, longitude and radius, then you would attach two triggers to it. By doing it this way, you avoid duplicating the location information in the two separate triggers.

Once you've created a place, you can also set various properties on it such as a date range (date_from, date_to) or additional metadata using the "extra" parameter. You can also create a permanent place such as a concert venue, and attach multiple short-lived triggers for each event at the venue where the trigger would expire after the event takes place.

You can also retrieve the history of times you've been at a place after you've created it.

Place API Methods


When you want to start organizing content that multiple users can access, you'll need to use a layer. A layer is a collection of places, and each place can have one or more triggers associated with it.

One way to apply layers is to use them as categories of content for your app. For example, if you're making a "deals" app, you could have a "Nightlife" layer, a "Restaurants" layer, a "Concerts" layer, and others. You could then create a place for each business that you have a deal at, and a trigger for each deal. This lets you set the expiration date of the triggers without also expiring the place record.

Triggers can be assigned to layers. If you add a trigger to a layer, it will be attached to every place on the layer. This is convenient if you want to have a single trigger for thousands of places.

Layer API Methods