Swrve Geoplace API
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:
{
"page": CURRENT_PAGE,
"page_size": PAGE_SIZE,
"count": COUNT_OF_TOTAL_GEOPLACES,
"data": [
{
"id": GEOPLACE_ID,
"name": "GEOPLACE_NAME"
}
]
}
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": [
{
"name": "CUSTOM_PROP_NAME",
"value": "CUSTOM_PROP_VALUE"
}
],
"geofences": [
{
"id": GEOFENCE_ID,
"name": "GEOFENCE_NAME",
"geofence_type": "circle",
"definition": {
"latitude": LATITUDE,
"longitude": LONGITUDE,
"radius": RADIUS
}
}
]
}
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": [
{
"name": "CUSTOM_PROP_NAME",
"value": "CUSTOM_PROP_VALUE"
}
],
"geofences": [
{
"name": "GEOFENCE_NAME",
"geofence_type": "circle",
"definition": {
"latitude": LATITUDE,
"longitude": LONGITUDE,
"radius": RADIUS
}
}
]
}
}
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": [
{
"name": "CUSTOM_PROP_NAME",
"value": "CUSTOM_PROP_VALUE"
}
],
"geofences": [
{
"id": GEOFENCE_ID,
"name": "GEOFENCE_NAME",
"geofence_type": "circle",
"definition": {
"latitude": LATITUDE,
"longitude": LONGITUDE,
"radius": RADIUS
}
}
]
}
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":[
{"from_hour":9,
"from_minute":30,
"to_hour":14,
"to_minute":0}
],
"tue":[
{"from_hour":9,
"from_minute":30,
"to_hour":14,
"to_minute":0}
],
"wed":[
{"from_hour":9,
"from_minute":30,
"to_hour":14,
"to_minute":0},
{"from_hour":17,
"from_minute":0,
"to_hour":22,
"to_minute":10}
],
"thu":[
{"from_hour":0,
"from_minute":0,
"to_hour":23,
"to_minute":59}
],
"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:
| 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.