Geozones API

getNearestZone

Called internally from the SDK. Retrieves the parameters of the nearest geozone and the distance to it. Also records the device location for geo push notifications.

POST https://api.pushwoosh.com/json/1.3/getNearestZone

Request body parameters

Parameter	Type	Required	Description
application	`string`	Yes	Pushwoosh application code
hwid	`string`	Yes	Hardware device ID used in the `/registerDevice` request.
lat	`string`	Yes	Latitude of the device.
lng	`string`	Yes	Longitude of the device.

Request example

{
  "request": {
    "application": "APPLICATION_CODE",
    "hwid": "HWID",
    "lat": 10.12345,
    "lng": 28.12345
  }
}

PHP example

// See http://gomoob.github.io/php-pushwoosh/get-nearest-zone.html

use Gomoob\Pushwoosh\Model\Request\GetNearestZoneRequest;

// Creates the request instance
$request = GetNearestZoneRequest::create()
    ->setHwid('HWID')
    ->setLat(10.12345)
    ->setLng(28.12345);

// Call the '/getNearestZone' Web Service
$response = $pushwoosh->getNearestZone($request);

if ($response->isOk()) {
    print 'Zone name : ' . $response->getResponse()->getName();
    print 'Latitude : ' . $response->getResponse()->getLat();
    print 'Longitude : ' . $response->getResponse()->getLng();
    print 'Range : ' . $response->getResponse()->getRange();
    print 'Distance : ' . $response->getResponse()->getDistance();
} else {
    print 'Oops, the operation failed :-(';
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

addGeoZone

Adds a Geozone to a specific app.

POST https://api.pushwoosh.com/json/1.3/addGeoZone

Request body parameters

Parameter	Type	Required	Description
auth	`string`	Yes	API access token from Pushwoosh Control Panel.
application	`string`	Yes	Pushwoosh application code
geozones	`array`	Yes	Geozone parameters as a JSON array.
geozones.name	`string`	Yes	Geozone name.
geozones.lat	`string`	Required for a circle.	Geozone latitude. Omit when `polygon` is set — a polygon geozone derives its own center.
geozones.lng	`string`	Required for a circle.	Geozone longitude. Omit when `polygon` is set — a polygon geozone derives its own center.
geozones.cooldown	`integer`	Yes	Silent period after sending a notification (in seconds).
geozones.range	`integer`	Required for a circle.	Geozone range in meters. Minimum 50. Omit when `polygon` is set — a polygon geozone derives its own range.
geozones.polygon	`object`	No	Makes the geozone a polygon instead of a circle. Cannot be combined with `lat`/`lng`/`range` — sending both is rejected. See Polygon geozones.
geozones.content	`string or object`	Required if `presetCode` is empty.	Geozone message content.
geozones.presetCode	`string`	Required if `content` is empty.	Push preset to use instead of `content`.
geozones.cluster	`string`	No	Specify `null` to unbind a cluster from the Geozone.
geozones.campaign	`string`	No	Specify `null` to unbind a campaign from the Geozone. If omitted, the campaign value remains unchanged. Note: Has higher priority than the campaign in the preset.
geozones.timetable	`object`	No	Sets timetable intervals.

Request example

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // API access token from Pushwoosh Control Panel
    "application": "XXXXX-XXXXX",            // Pushwoosh application code
    "geozones": [{
      "name": "Statue of George",            // required. Geozone name.
      "lat": "40.70087797",                   // required. Geozone latitude.
      "lng": "-73.931851387",                 // required. Geozone longitude.
      "cooldown": 60,                         // in seconds, required. Silent period after sending a notification
      "range": 50,                            // in meters, minimum 50, required. Range of the geozone.
      "content": "Lorem ipsum dolor sit amet,
       consectetur adipiscing elit.",         // or object
      "presetCode": "AAAAA-BBBBB",            // optional. Push preset could be used instead of content
      "cluster": "GEOZONE CLUSTER CODE",      // optional. Cluster's cooldown period will be applied
      "campaign": "CAMPAIGN_CODE",            // optional. Specify null to unbind Campaign from Geozone
      "timetable": {                          // optional
        "timezone": 1234,                     // in seconds
        "Mon": [                              // available days: Mon, Tue, Wed, Thu, Fri, Sat, Sun. Push sending
          {
            "start": "04:11",
            "stop": "12:00"
          }
        ],
        "Sun": [
          {                                    // one or two intervals
            "start": "01:11",
            "stop": "17:00"
          },
          {
            "start": "18:01",
            "stop": "23:59"
          }
        ]
      }
    }]
  }
}

Adding several geozones at once

geozones takes an array, so one call can create a whole batch. The batch is validated as a whole before anything is written: if any entry is rejected, the call fails and no geozone from that request is created. The error names the offending entry by its position in the array, counted from zero:

{
  "status_code": 210,
  "status_message": "geozones[301]: range: range must be at least 50 meters"
}

Fix that entry and send the request again. On success, GeoZones holds the new numeric IDs in the same order as the entries you sent.

Batches larger than 500 entries are accepted and split into chunks internally. The whole array is still validated before the first write, but the write itself is not atomic across chunks: an entry can pass validation and still fail to be written, for example if the preset it names is deleted in between. In that case the call returns 200 with the IDs that were written plus an Errors array naming the entry that stopped the run, so nothing created is lost:

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "GeoZones": [100016750, 100016751],
    "Errors": [{ "index": 2, "message": "preset not found" }]
  }
}

Errors is absent when every entry was written, so a fully successful response is unchanged. A GeoZones array shorter than the array you sent always means some entries were not created.

Polygon geozones

Send polygon instead of lat/lng/range to make the geozone a polygon. polygon.vertices is an ordered ring of {lat, lng} points describing the shape’s outline:

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",
    "application": "XXXXX-XXXXX",
    "geozones": [{
      "name": "Downtown mall — ground floor",
      "cooldown": 60,
      "polygon": {
        "vertices": [
          { "lat": 40.70087797, "lng": -73.931851387 },
          { "lat": 40.70112456, "lng": -73.931602211 },
          { "lat": 40.70095321, "lng": -73.930987654 },
          { "lat": 40.70068912, "lng": -73.931233456 }
        ]
      },
      "content": "Welcome! Enjoy 15% off your first purchase today."
    }]
  }
}

lat, lng, and range are derived from the ring — the circle a device actually monitors is centered on the shape with a radius reaching its farthest vertex (minimum 50 m). Sending polygon together with lat/lng/range is rejected.

You can send the ring open or closed — if the last vertex repeats the first, the server drops that closing duplicate before validating. Vertex validation, on the resulting ring: 3 to 100 distinct vertices. The ring is also rejected if its points are collinear, if its edges self-intersect, or if it crosses the antimeridian.

updateGeoZone

Updates Geozone properties.

POST https://api.pushwoosh.com/json/1.3/updateGeoZone

Request body parameters

Parameter	Type	Required	Description
auth	`string`	Yes	API access token from Pushwoosh Control Panel.
geoZoneId	`string`	Yes	Geozone ID from `/addGeoZone` request.
name	`string`	No	New Geozone name.
cooldown	`integer`	No	Cooldown to update, in seconds.
status	`integer`	No	0 - deactivated, 1 - activated.
content	`string`	No	Content for Geozone push notification. Cannot be used with `presetCode`.
cluster	`string`	No	New cluster name. Specify `null` to unbind cluster from Geozone.
campaign	`string`	No	New campaign ID. Specify `null` to unbind Campaign from Geozone. If omitted, Campaign value won’t be changed. Has higher priority than a Campaign from a preset.
lat	`number`	No	Geozone latitude. Cannot be combined with `polygon`.
lng	`number`	No	Geozone longitude. Cannot be combined with `polygon`.
range	`integer`	No	New range in meters. Cannot be combined with `polygon`.
polygon	`object`	No	New ring of `{lat, lng}` vertices — replaces the shape and re-derives `lat`/`lng`/`range` from it. See Polygon geozones. Works both ways: send it on an existing circle geozone to turn it into a polygon, or send an empty ring (`{"vertices": []}`) on an existing polygon geozone to turn it back into a circle. Omit `polygon` entirely to leave the shape unchanged. Same vertex validation as `addGeoZone`.
timetable	`object`	No	Geozone timetable. See more info below.

Request example

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // required, API access token from Pushwoosh Control
    "geoZoneId": 100016750,                  // required, from /addGeoZone method
    "name": "new geozone name",              // optional
    "cooldown": 222,                         // in seconds, optional
    "status": 0,                             // optional, 0 - deactivated, 1 - activated
    "presetCode": "BBBBB-AAAAA",             // optional, cannot be used along with "content"
    "content": "new geozone content",        // optional, cannot be used along with "presetCode"
    "cluster": "GEOZONE CLUSTER CODE",       // optional. Specify null to unbind cluster from Geozone
    "campaign": "CAMPAIGN_CODE",             // optional. Specify null to unbind Campaign from Geozone
    "lat": 10.56,                            // optional, geozone latitude
    "lng": 12.523,                           // optional, geozone longitude
    "range": 500,                            // optional, geozone range
    "timetable": {                           // optional
      "timezone": 1234,                      // in seconds
      "Mon": [                               // available days: Mon, Tue, Wed, Thu, Fri, Sat, Sun. Push sending
        {
          "start": "04:11",
          "stop": "12:00"
        }
      ],
      "Sun": [
        {                                    // one or two intervals
          "start": "01:11",
          "stop": "17:00"
        },
        {
          "start": "18:01",
          "stop": "23:59"
        }
      ]
    }
  }
}

deleteGeoZone

Removes Geozones from the app.

POST https://api.pushwoosh.com/json/1.3/deleteGeoZone

Request body parameters

Parameter	Type	Required	Description
auth	`string`	Yes	API access token from Pushwoosh Control Panel.
application	`string`	Yes	Pushwoosh application code
geozones	`string`	Yes	Array of IDs or a single ID of a Geozone to remove.

Request example

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // required, API access token from Pushwoosh Control
    "application": "XXXXX-XXXXX",            // required, Pushwoosh application code
    "geozones": [550, 526]                   // required, geozones IDs
  }
}

addGeoZoneCluster

Adds Geozone Cluster to the app.

POST https://api.pushwoosh.com/json/1.3/addGeoZoneCluster

Request body parameters

Parameter	Type	Required	Description
auth	`string`	Yes	API access token from Pushwoosh Control Panel.
application	`string`	Yes	Pushwoosh application code
name	`string`	Yes	Cluster name.
cooldown	`integer`	Yes	A delay before a single user can receive the same message from the Geozone Cluster, in seconds.

Request example

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // required, API access token from Pushwoosh Control
    "application": "XXXXX-XXXXX",            // required, Pushwoosh application code
    "name": "Raccoon city",                  // required, cluster name
    "cooldown": 3210                         // required, in seconds
  }
}

deleteGeoZoneCluster

Removes a Geozone Cluster from the app.

POST https://api.pushwoosh.com/json/1.3/deleteGeoZoneCluster

Request body parameters

Parameter	Type	Required	Description
auth	`string`	Yes	API access token from Pushwoosh Control Panel.
application	`string`	Yes	Pushwoosh application code
geoZoneCluster	`string`	Yes	ID of the Geozone cluster to remove.

Request example

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // required, API access token from Pushwoosh Control
    "application": "XXXXX-XXXXX",            // required, Pushwoosh application code
    "geoZoneCluster": "EA1CE-69405"          // required, cluster ID obtained from the /addGeoZoneCluster request
  }
}

listGeoZones

Retrieves a list of Geozones for the app.

POST https://api.pushwoosh.com/json/1.3/listGeoZones

Request body parameters

Parameter	Type	Required	Description
auth	`string`	Yes	API access token from Pushwoosh Control Panel.
application	`string`	Yes	Pushwoosh application code

Request example

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // required, API access token from Pushwoosh Control
    "application": "XXXXX-XXXXX"             // required, Pushwoosh application code
  }
}

listGeoZoneClusters

Retrieves a list of Geozone clusters for the app.

POST https://api.pushwoosh.com/json/1.3/listGeoZoneClusters

Request body parameters

Parameter	Type	Required	Description
auth	`string`	Yes	API access token from Pushwoosh Control Panel.
application	`string`	Yes	Pushwoosh application code

Request example

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // required, API access token from Pushwoosh Control
    "application": "XXXXX-XXXXX"             // required, Pushwoosh application code
  }
}