trigger/create

URL

https://api.geoloqi.com/1/trigger/create

Description

Create a new geotrigger associated with a place or all places on a layer. The geotrigger can be either a callback URL or can send a message via SMS to the user.

Supported Request Methods

POST

Scope

triggers

Parameters

• place_id
  Attach the geotrigger to this place. If place_id is specified, layer_id cannot be specified.
• layer_id
  Attaching a geotrigger to a layer will fire the trigger for every place on that layer. If layer_id is specified, place_id cannot be specified.
• key Optional
  A unique identifier for the trigger. See the page on De-Duplication for more information
• type message, or callback
  If set to "message", then the text in the "text" parameter will be delivered to the user. If set to "callback", then provide a valid callback URL which Geoloqi will post to when the geotrigger is fired. Information about the place and user will be included in the post body to this URL.
• text Required if message type is "message"
  If the geotrigger is of type "message" then this text will be delivered to the user. Newlines will be removed, and the message should be shorter than 140 characters to fit in an SMS. If it is longer, a short version will be sent in SMS and the full message will be emailed.
• url Available if type is "message"
  If the message is delivered via Push notification, a "View" button will appear in the push and clicking it will open the URL in a browser. IF the message is delivered via SMS, the URL will be sent at the end of the text message
• url Required if message type is "callback"
  Provide a URL that Geoloqi will send a POST document to when the geotrigger fires. Information about the place and user will be included in the POST body. If you need to keep session information about this request, include some sort of hash or other unique string in the URL provided here.
• extra
  A hash of keys and values to store along with the trigger. Whatever you store here will be returned whenever the trigger info is read. See Extra Parameters for more details.
• date_from
  The trigger will be fired only after this date
• date_to
  The trigger will be deactivated after this date
• time_from
  The trigger will be fired only after this time (of every day)
• time_to
  The trigger will be fired only before this time (of every day)
• trigger_on Default: enter
  Values: "enter", "leave". If set to "enter", the trigger is fired when the user first enters the location. If set to "leave", the trigger fires when the user leaves the location.
• one_time Default: 1
  If "1", the trigger will only fire once (per user) and then will be deactivated. If "0", the trigger will not be deactivated and may be fired again if the conditions are met at a later date.
• trigger_after
  Fire this trigger only after the user has been at the given place for this many seconds.

Creating Places

It is possible to automatically create places when creating triggers. This helps when importing large datasets, since you don't need to make sequential requests to place/create and then trigger/create, you can do it in one API call.

You can create a place either by specifying a latitude, longitude and radius, or by using the built-in geocoder to create a place given an address.

Latitude/Longitude

• latitude Required
  The latitude of the center of the place
• longitude Required
  The longitude of the center of the place
• radius Optional
  The radius of the the place in meters. If not set, span_longitude must be provided instead.
• span_longitude Optional
  The longitudinal span of the place. Radius is calculated from this span internally.

Geocoding

• geocode Required
  The one-line text to geocode. Fully-specified addresses are recommended, but city names and some business names will work as well. Include the city and state for best results.
• radius Optional
  If no radius is specified, a radius will be automatically chosen based on the size of the feature returned from the geocoder. Addresses will usually result in a radius of 150 meters, while city names will be much larger

Other Parameters

• place_layer_id Optional
  The layer ID that will contain the place. If you don't specify a layer, the user's default layer will be used instead. Note that this is different from setting a trigger on the layer, this just tells the system which layer on which to auto-create the place.
• place_key Optional
  A unique identifier for the place. If a place with this key already exists, it will be used instead of creating a duplicate place. See De-Duplication for more information.
• place_name Optional
  The name of the place to create.
• place_description Optional
  The description of the place.
• place_extra
  A hash of keys and values to store along with the place.

Example

curl -H "Content-Type: application/json" \
     -H "Authorization: OAuth APPLICATION_ACCESS_TOKEN" \
     -d '{"type": "message", "text": "Welcome to Powells Books", "latitude": 45.523334, "longitude": -122.681612, "radius": 300}' \
     https://api.geoloqi.com/1/trigger/create

Response

{
  "trigger_id": "2CRm",
  "place_id": "24tA",
  "type": "message",
  "trigger_on": "enter",
  "trigger_after": 0,
  "one_time": 0,
  "text": "Welcome to Powells Books",
  "extra": {
  },
  "place": {
    "place_id": "24tA",
    "name": "",
    "latitude": 45.523334,
    "longitude": -122.681612,
    "radius": 300,
    "display_name": "",
    "time_from": "00:00:00",
    "time_to": "00:00:00",
    "active": 1,
    "extra": {
    },
    "description": ""
  }
}

Success

If the geotrigger was created successfully, you will get the trigger ID which can be used to delete the trigger in the future if you wish.

HTTP/1.1 200 OK
 
{"trigger_id":"HY8_3"}