Skip to main content

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.

ParameterDescription
api_keyThe API key of your app, as displayed on your app's Integration settings page.
personal_keyYour 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​

ParameterTypeDescriptionExample
queryStringThe 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
pageIntegerDepending on the number of results, the page number within the results that you want to display. Defaults to 1.page=1
page_sizeIntegerThe number of results you want to display per page, to a maximum of 50. The default is 15.page_size=10
sortStringHow you want to sort the results, either by "name" or date "created_at". The default is "name".sort=name
orderStringThe 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:

{
"page": CURRENT_PAGE,
"page_size": PAGE_SIZE,
"count": COUNT_OF_TOTAL_GEOPLACES,
"data":
}

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.

{
"id": GEOPLACE_ID,
"name": "CIRCULAR_GEOPLACE_NAME",
"custom_properties": ,
"geofences":
}

Create 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.

{
"geoplace": {
"name": "CIRCULAR_GEOPLACE_NAME",
"custom_properties": ,
"geofences":
}
}

Response​

Same as Get details of a single geoplace.

Update 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.

{
"geoplace": {
"id": GEOPLACE_ID,
"name": "CIRCULAR_GEOPLACE_NAME",
"custom_properties": ,
"geofences":
}
}

Response​

Same as Get details of a single geoplace.

Delete 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:

{
"geoplace":{
...
"opening_hours":{
"mon":,
"tue":,
"wed":,
"thu":,
"fri":[],
"sat":[],
"sun":[]
}
...
}
}

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:

{
"errors": "There was an error"
}

Some error samples are provided below:

CodeError messageDescription
404Not foundCould not find the geoplace with the provided ID.
400Found 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.