Last modified April 29, 2020 by Sergio Mira

Swrve Geoplace API

The Swrve Geoplace API is a series of REST calls for creating geoplaces in Swrve to use as triggers for your geo-triggered notification campaigns.

Required URL parameters

The following parameters are required for all API calls, in addition to those listed per method.

Parameter Description
api_key The API key of your app, as displayed on your app’s Integration settings page.
personal_key Your personal key, as displayed on your app’s Integration settings page.

US vs. EU URL

The URL examples in this article reference Swrve’s URL for data and content stored in our US data center. If your app uses EU data storage and URL endpoints (that is, you log into the Swrve dashboard at https://eu-dashboard.swrve.com), use the EU-based URL for all API calls (for example, https://eu-dashboard.swrve.com/api/1/geoplaces.json).

Required content type

The API supports only application/json content type.

UTF-8 encoding

Swrve recommends that you UTF-8 encode POST bodies.


List of geoplaces

Lists all your existing geoplaces, paginated, with the ability to specify a search term.

Request method

GET

URL

https://dashboard.swrve.com/api/1/geoplaces.json

URL parameters

Parameter Type Description Example
query String The search term you want to use to query your geoplaces, depending on your geoplace naming convention. For example, you might search for all geoplaces linked to a city or store name. The query and returned results are not case sensitive and list all geoplaces that include the search term in their name. Limited to 191 characters. query=Dublin
page Integer Depending on the number of results, the page number within the results that you want to display. Defaults to 1. page=1
page_size Integer The number of results you want to display per page, to a maximum of 50. The default is 15. page_size=10
sort String How you want to sort the results, either by “name” or date “created_at”. The default is “name”. sort=name
order String The order in which you want to display results, ascending (“asc”) or descending (“desc”). The  default is “asc”. order=asc

Example request

https://dashboard.swrve.com/api/1/geoplaces.json?query=Dublin&page=2&order=desc

Response

Returns a list of matching geoplaces with their name and ID:


Get details of a single geoplace

Get more information about an individual geoplace from its ID. A geoplace can contain a single circular geofence although in the future the API might support multiple geofences per geoplace.

Request method

GET

URL

https://dashboard.swrve.com/api/1/geoplaces/ID.json

Example request

https://dashboard.swrve.com/api/1/geoplaces/987.json

Example of a circular geoplace response

Circular geoplaces include latitude, longitude, and radius in their definition.


Creating a geoplace

Send this API call to Swrve to create a new circular geoplace. Currently there is a 1:1 mapping of geoplaces to a geofence. Extra parameters other than the ones shown in the examples are not permitted.

Request method

POST

URL

https://dashboard.swrve.com/api/1/geoplaces.json

Example body to create a circular geoplace

Creates a circular geoplace. Note that you must create any custom properties in Swrve first before you can reference them via API. For more information about adding custom properties to your geoplaces, see About geoplaces.

Response

Same as Get details of a single geoplace.


Updating a geoplace

Send this API call to Swrve to update an existing geoplace. Currently there is a 1:1 mapping of geoplaces to a geofence. Only the provided attributes are updated. Extra parameters other than the ones shown in the examples are not permitted.

Request method

PUT

URL

https://dashboard.swrve.com/api/1/geoplaces/ID.json

Example request

https://dashboard.swrve.com/api/1/geoplaces/987.json

Example body to update a circular geoplace

Updates a circular geoplace. Note that you must create any custom properties in Swrve first before you can reference them via API.

Response

Same as Get details of a single geoplace.


Deleting a geoplace

Deletes one geoplace from your app.

Request method

DELETE

URL

https://dashboard.swrve.com/api/1/geoplaces/ID.json

Example request

https://dashboard.swrve.com/api/1/geoplaces/987.json

Response

204 HTTP No Content


Opening hours

The Swrve Geoplace API supports remote management of geoplace opening hours.

  • Opening hours – Limits the timeframe during which a customer can trigger a notification by comparing the geoplace opening hours to the local time on the customer’s device. The default setting for a new geoplace is always open (that is 00:00-23:59).

Include the property and its values under your geoplace definition.

Setting geoplace opening hours

To set geoplace opening hours, include the opening_hours property in your geoplace definition and define the days and hours as follows:

  • Include a sub-property for each day of the week using lowercase, 3-letter format: mon, tue, wed, thu, fri, sat, sun
  • For each day, include a JSON array of opening hour ranges, defined by a set of these properties with integer values that represent the time using the 24-hour clock:
    • from_hour
    • from_minute
    • to_hour
    • to_minute

For example:

So in the above example, the opening hours are:

  • Monday and Tuesday – 9:00 am to 2:00 pm
  • Wednesday – 9:30 am to 2:00 pm and 5:00 pm to 10:10 pm
  • Thursday – open all day
  • Friday to Sunday – closed all day

Response codes and errors

Errors are returned in a JSON format with HTTP response code 400/404:

Some error samples are provided below:

Error code Error message Description
404 Not found Could not find the geoplace with the provided ID.
400 Found unpermitted parameter: {parameter name} Extra parameters are not permitted.
400 (Other validation errors) Provided geoplace data is invalid.

Rate limiting

This API is rate limited to five requests per second per app. If the limit is reached, the response code will be 429 Forbidden (Rate Limit Exceeded) with the body: Rate Limit Exceeded.