Last modified April 24, 2019 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 or polygonal geofence although in the future the API might support multiple geofences per geoplace. The response differs slightly between each type.

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.

Example of a polygonal geoplace response

Polygonal geoplaces include an array of coordinate pairs for every point (vertex) in their definition.


Creating a geoplace

Send this API call to Swrve to create a new circular or polygonal 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.

Example body to create a polygonal geoplace

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

To create a polygonal geoplace, you must include a minimum of three vertices.

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.

Example body to update a polygonal geoplace

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

A minimum of three vertices is required to create a polygon.

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


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 403 Forbidden (Rate Limit Exceeded) with the body: Rate Limit Exceeded.