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

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


### Request body parameters  


| Parameter | Type <div style="width:80px"></div> | Required | Description |
|-----------|--------|:--------:|-------------|
| **application** | `string` | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |
| **hwid** | `string` | Yes | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id ) used in the `/registerDevice` request. |
| **lat** | `string` | Yes | Latitude of the device. |
| **lng** | `string` | Yes | Longitude of the device. |


### Request example 

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

### PHP example

```php
// 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.  

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


### Request body parameters  


| Parameter <div style="width:150px"></div>  | Type <div style="width:80px"></div> | Required | Description |
|-----------|--------|:--------:|-------------|
| **auth** | `string` | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| **application** | `string` | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |
| **geozones** | `array` | Yes | Geozone parameters as a JSON array. |
| **geozones.name** | `string` | Yes | Geozone name. |
| **geozones.lat** | `string` | Yes | Geozone latitude. |
| **geozones.lng** | `string` | Yes | Geozone longitude. |
| **geozones.cooldown** | `integer` | Yes | Silent period after sending a notification (in seconds). |
| **geozones.range** | `integer` | Yes | Geozone range in meters. Minimum 50. |
| **geozones.content** | `string or object` | Required if `presetCode` is empty. | Geozone message content. |
| **geozones.presetCode** | `string` | Required if `content` is empty. | [Push preset](/developer/api-reference/api-identifiers/#preset-code) 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  

```json
{ 
  "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"
          }
        ]
      }
    }]
  }
}

```
## updateGeoZone  

Updates Geozone properties.  

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

### Request body parameters  

| Parameter <div style="width:150px"></div> | Type <div style="width:80px"></div> | Required | Description |
|-----------|--------|:--------:|-------------|
| **auth** | `string` | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| **geoZoneId** | `string` | Yes | [Geozone ID](/developer/api-reference/api-identifiers/#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. |
| **lng** | `number` | No | Geozone longitude. |
| **range** | `integer` | No | New range in meters. |
| **timetable** | `object` | No | Geozone timetable. See more info below. |

---


### Request example  

```json
{ 
  "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.  

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

### Request body parameters  


| Parameter   <div style="width:150px"></div>   | Type <div style="width:80px"></div>   | Required | Description |
|-------------|--------|:--------:|-------------|
| **auth**    | `string` | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| **application** | `string` | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |
| **geozones** | `string` | Yes | Array of IDs or a [single ID](/developer/api-reference/api-identifiers/#geozone-id) of a Geozone to remove. |



### Request example  

```json
{
  "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.  

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

### Request body parameters  

| Parameter  <div style="width:150px"></div>  | Type <div style="width:80px"></div>    | Required | Description |
|-------------|--------|:--------:|-------------|
| **auth**    | `string` | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| **application** | `string` | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#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 

```json
{
  "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.  

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


### Request body parameters


| Parameter   <div style="width:150px"></div>        | Type  <div style="width:80px"></div>  | Required | Description |
|-------------------|--------|:--------:|-------------|
| **auth**         | `string` | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| **application**  | `string` | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |
| **geoZoneCluster** | `string` | Yes | ID of the Geozone cluster to remove. |


### Request example   

```json
{
  "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.  


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

### Request body parameters 


| Parameter  <div style="width:150px"></div>    | Type <div style="width:80px"></div>   | Required | Description |
|-------------|--------|:--------:|-------------|
| **auth**    | `string` | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| **application** | `string` | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |


### Request example  

```json
{
  "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.  

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


### Request body parameters 


| Parameter <div style="width:150px"></div>   | Type <div style="width:80px"></div>    | Required | Description |
|-------------|--------|:--------:|-------------|
| **auth**    | `string` | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-token) from Pushwoosh Control Panel. |
| **application** | `string` | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |


### Request example

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