LATEST VERSION: 1.9 - CHANGELOG
Push Notification Services v1.9

Geofences

Endpoints for Managing Geofences

Create Geofence

POST /v1/geofence

Create a geofence for an app

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:
  {
    "tags": [
      "tag1",
      "tag2"
    ],
    "locations": [
      "1",
      "2"
    ],
    "trigger_type": "enter",
    "start_time": 0,
    "expiry_time": 1424443201000,
    "platform": "",
    "data": {
      "ios": {
        "alertBody": "",
        "category": "",
        "alertAction": "",
        "alertTitle": "",
        "alertLaunchImage": "",
        "hasAction": false,
        "applicationBadgeNumber": 0,
        "soundName": "",
        "userInfo": "object"
      },
      "android": "object"
    }
  }
Geofence Fields
  • tags

    type: array of strings

    required: no

    This is a list of tags to target. If not empty it will limit the audience for the geofence to only users that have subcribed to one or more of the listed tags
  • locations

    required: yes

    type: array of numbers

    List of location ids for the locations that should be included in the geofence
  • trigger_type

    required: yes

    type: “string”; possible values are “enter”, “exit”

    When trigger_type is set to “enter” the notification will be displayed when a user enter the geofence. When it is set to “exit” the notification will not be displayed until the user exits the geofence.
  • start_time

    required: yes

    type: millisecond timestamp (integer)

    Geofences are only active for a fixed period of time. “start_time” determines when the geofence should become active. Set this to “0” to activate the geofence upon creation
  • expiry_time

    required: yes

    type: millisecond timestamp (integer)

    Sets the time when the geofence should become inactive.
  • platform

    required: yes

    type: string; possible values are “android”, “ios”, “all”

    Target the geofence to devices of a specific platform
  • data

    required: yes

    type: object

    The data object contains platform specific fields for constructing the notification to be displayed. These are slightly different than fields used in the push api because geofence notifications are actually local notifications. Custom User IDs are not a supported way to target registered devices for geofences.
iOS Geofence Data Fields

For Apple’s reference on local notifications see https://developer.apple.com/library/ios/documentation/iPhone/Reference/UILocalNotification_Class/index.html#//apple_ref/occ/instp/UILocalNotification/alertBody

All fields here are optional.

  • alertBody

    type: string

    A string or localized-string key to use as the notification alert message. If nil or empty there no alert will be shown. Printf style escape characters are stripped from the string prior to display; to include a percent symbol (%) in the message, use two percent symbols (%%).
  • category type: string

    The value of this property is the category name associated with a registered UIUserNotificationSettings object. When the alert for the local notification is displayed, the system uses the string you specify to look up the group and retrieve its actions. It then adds a button to the alert for each action defined by the group. When the user taps one of those buttons, the app is woken up (or launched) and given a chance to perform the designated action. If the specified category name does not belong to a registered group of actions, the alert does not display any additional action buttons.
  • alertAction

    type: string

    A string or localized-string key to use as the title of the right button of the alert or the value of the unlock slider, where the value replaces “unlock” in “slide to unlock”. If you specify nil, and alertBody is non-nil, “View” (localized to the preferred language) is used as the default value.
  • alertTitle

    type: string

    A short description of the reason for the alert. Apple Watch displays the title string as part of the short look notification interface, which has limited space.
  • alertLaunchImage

    type: string

    Identifies the image used as the launch image when the user taps (or slides) the action button (or slider).
  • hasAction type: boolean Determines whether or not to show an alert action.
  • applicationBadgeNumber

    type: number

    The number to display as the app icon’s badge. Default value is 0 which will simply not display a badge.
  • soundName

    type: string

    The name of the file containing the sound to play when an alert is displayed.
  • userInfo

    type: dictionary A dictionary for passing custom information to the notified app.

Response:
  {
    "id": 0,
    "tags": [
      ""
    ],
    "expiry_time": 0,
    "trigger_type": "",
    "locations": [
      {
        "name": "",
        "id": 0,
        "long": "",
        "rad": 0,
        "lat": "",
        "created_at": 0,
        "updated_at": 0
      }
    ],
    "platform": "",
    "created_at": 0,
    "updated_at": 0,
    "data": {
       "ios": {
        "alertBody": "",
        "category": "",
        "alertAction": "",
        "alertTitle": "",
        "alertLaunchImage": "",
        "hasAction": false,
        "applicationBadgeNumber": 0,
        "soundName": "",
        "userInfo": "object"
      },
      "android": "object"
    },
    "start_time": 0
  }

Get Geofences

GET /v1/geofence

Get all geofences for an app

Authentication: HTTP basic application_uuid:api_key

Query Parameters:

Parameters Description
page: integer result page to display
size: integer number of results per page
timestamp: long timestamp in milliseconds
Request Body: None
Response:
    {
      "size": 25,
      "totalGeofences": 1,
      "totalPages": 1,
      "page": 1,
      "geofences": [
        {
          "id": 1,
          "expiry_time": 1424443201000,
          "trigger_type": "enter",
          "updated_at": 1423513994000,
          "created_at": 1423513994000,
          "data": {"object":{"key":"value"}},
          "tags": ["tag1"],
          "locations": [
            {
              "name": "sample",
              "id": 1,
              "lat": "0.0",
              "long": "0.0",
              "rad": 100,
              "updated_at": 1423513994000,
              "created_at": 1423513994000
            }
          ]
        }
      ]
    }

Get Geofence Updates

GET /v1/geofences

Get updated geofences since a timestamp. This endpoint is used by devices to fetch an updated list of geofences to monitor.

Authentication: HTTP basic platform_uuid:platform_secret

Query Parameters:

Parameters Description
timestamp: long timestamp in milliseconds
Request Body:

None.

Response:
    {
      "num": 3,
      "deleted_geofence_ids": [1,2],
       "geofences": [
        {
          "id": 5,
          "expiry_time": 1424443201000,
          "trigger_type": "enter",
          "updated_at": 1423513994000,
          "created_at": 1423513994000,
          "data": {"object":{"key":"value"}},
          "tags": ["tag1"],
          "locations": [
            {
              "name": "sample",
              "id": 1,
              "lat": "0.0",
              "long": "0.0",
              "rad": 100,
              "updated_at": 1423513994000,
              "created_at": 1423513994000
            }
          ],
      "last_modified": 1423513994000
    }
  • deleted_geofence_ids

    type: array of numbers

    List of ids for geofences that have been deleted since the requested timestamp.

  • geofences

    type: array of geofence objects

    List of geofences that have been added since the requested timestamp.


Get One Geofence

GET /v1/geofence/:geofence_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:

None.

Response:
    {
      "id": 1,
      "expiry_time": 1424443201000,
      "trigger_type": "enter",
      "updated_at": 1423513994000,
      "created_at": 1423513994000,
      "data": {"object":{"key":"value"}},
      "tags": ["tag1"],
      "locations": [
        {
          "name": "sample",
          "id": 1,
          "lat": "0.0",
          "long": "0.0",
          "rad": 100,
          "updated_at": 1423513994000,
          "created_at": 1423513994000
        }
      ]
    }

Update a Geofence

PUT /v1/geofence/:geofence_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:
    {
      "trigger_type": "enter",
      "expiry_time": 1424443201000,
      "data": {"object":{"key":"value"}},
      "tags": [
        "tag1"
      ],
      "locations": [1]
    }
Response:
    {
      "id": 1,
      "expiry_time": 1424443201000,
      "trigger_type": "enter",
      "updated_at": 1423513994000,
      "created_at": 1423513994000,
      "data": {"object":{"key":"value"}},
      "tags": [
        "tag1"
      ],
        "locations": [
        {
          "name": "sample",
          "id": 1,
          "lat": "0.0",
          "long": "0.0",
          "rad": 100,
          "updated_at": 1423513994000,
          "created_at": 1423513994000
        }
      ]
    }

Delete a Geofence

DELETE /v1/geofence/:geofence_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:

None.

Response: 204 (NO CONTENT)

Locations


Endpoints for managing geofence locations.

Get All Locations

GET /v1/locations

Get all geofence locations for an app

Authentication: HTTP basic application_uuid:api_key

Query Parameters:

Parameters Description
page: integer result page to display
size: integer number of results per page
timestamp: long timestamp in milliseconds
q: string keyword to search for
Request Body:

None.

Response:
  {
    "size": 25,
    "locations": [
      {
        "name": "sample",
        "id": 1,
        "long": "0.0",
        "rad": 100,
        "lat": "0.0",
        "created_at": 1423513994000,
        "updated_at": 1423513994000
      }
    ],
    "totalLocations": 1,
    "totalPages": 1,
    "page": 1
  }

Get One Location

GET /v1/locations/:location_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:

None.

Response:
    {
      "name": "sample",
      "id": 1,
      "lat": "0.0",
      "long": "0.0",
      "rad": 100,
      "updated_at": 1423513994000,
      "created_at": 1423513994000
    }

Create a New Location

POST /v1/locations

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:
    {
      "name": "sample",
      "lat": "0.0",
      "long": "0.0",
      "rad": 100
    }
  • name: a name for the location
  • lat: latitude in degrees
  • long: longitude in degrees
  • rad: radius in meters
Response:
    {
      "name": "sample",
      "id": 1,
      "lat": "0.0",
      "long": "0.0",
      "rad": 100,
      "updated_at": 14235139940000,
      "created_at": 1423513994000
    }

Update a Location

PUT /v1/locations/:location_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:
    {
      "name": "sample",
      "lat": "0.0",
      "long": "0.0",
      "rad": 100
    }
Response:
    {
      "name": "sample",
      "id": 1,
      "lat": "0.0",
      "long": "0.0",
      "rad": 100,
      "updated_at": 1423513994000,
      "created_at": 1423513994000
    }

Delete a Location

DELETE /v1/locations/:location_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:

None.

Response: 204 (NO CONTENT)

Location Groups


Endpoints for managing geofence locations.

Get All Location Groups

GET /v1/location_groups

Get all location groups for an app

Authentication: HTTP basic application_uuid:api_key

Query Parameters:

Parameters Description
page: integer result page to display
size: integer number of results per page
timestamp: long timestamp in milliseconds
q: string keyword to search for
Request Body:

None.

Response:
  {
    "size": 25,
    "location_groups": [
      {
        "name": "sample group",
        "id": 1,
        "description": "sample location group",
        "locations": [
          {
            "name": "sample",
            "id": 1,
            "long": "0.0",
            "rad": 100,
            "lat": "0.0",
            "createdAt": 1423513994000,
            "updatedAt": 1423513994000
          }
        ],
        "created_at": 1423513994000,
        "updated_at": 1423513994000
      }
    ],
    "totalLocationGroups": 1,
    "totalPages": 1,
    "page": 1
  }

Get One Location Group

GET /v1/location_groups/:location_group_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:

None.

Response:
  {
    "name": "sample group",
    "id": 1,
    "description": "sample location group",
    "locations": [
      {
        "name": "sample location",
        "id": 1,
        "long": "0.0",
        "lat": "0.0",
        "rad": 100
        "createdAt": 1423513994000,
        "updatedAt": 1423513994000
      }
    ],
    "created_at": 1423513994000,
    "updated_at": 1423513994000
  }

Create a Location Group

POST /v1/location_groups

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:
  {
    "name": "sample group",
    "location_ids": [
      1
    ],
    "description": "a sample location group"
  }
  • name: name for the location group
  • location_ids: list of ids for locations to include in the group
  • description: a short description of the group
Response:
  {
    "name": "sample group",
    "id": 1,
    "description": "",
    "locations": [
      {
        "name": "sample",
        "id": 1,
        "long": "0.0",
        "rad": 100,
        "lat": "0.0",
        "createdAt": 1423513994000,
        "updatedAt": 1423513994000
      }
    ],
    "created_at": 1423513994000,
    "updated_at": 1423513994000
  }

Update a Location Group

PUT /v1/location_groups/:location_group_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:
  {
    "name": "sample group",
    "location_ids": [
      1
    ],
    "description": "a sample location group"
  }
Response:
  {
    "name": "sample group",
    "id": 1,
    "description": "",
    "locations": [
      {
        "name": "sample",
        "id": 1,
        "long": "0.0",
        "rad": 100,
        "lat": "0.0",
        "createdAt": 1423513994000,
        "updatedAt": 1423513994000
      }
    ],
    "created_at": 1423513994000,
    "updated_at": 1423513994000
  }

Delete a Location Group

DELETE /v1/location_groups/:location_group_id

Authentication: HTTP basic application_uuid:api_key

Query Parameters: None

Request Body:

None.

Response: 204 (NO CONTENT)
Create a pull request or raise an issue on the source for this page in GitHub