Contents |
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_idAttach the geotrigger to this place. If place_id is specified, layer_id cannot be specified.
- layer_idAttaching 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 OptionalA unique identifier for the trigger. See the page on De-Duplication for more information
- type message, or callbackIf 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.
- extraA 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_fromThe trigger will be fired only after this date
- date_toThe trigger will be deactivated after this date
- time_fromThe trigger will be fired only after this time (of every day)
- time_toThe trigger will be fired only before this time (of every day)
- trigger_on Default: enterValues: "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: 1If "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_afterFire 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 RequiredThe latitude of the center of the place
- longitude RequiredThe longitude of the center of the place
- radius OptionalThe radius of the the place in meters. If not set, span_longitude must be provided instead.
- span_longitude OptionalThe longitudinal span of the place. Radius is calculated from this span internally.
Geocoding
- geocode RequiredThe 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 OptionalIf 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 OptionalThe 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 OptionalA 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 OptionalThe name of the place to create.
- place_description OptionalThe description of the place.
- place_extraA 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"}