# Geozones API

## getNearestZone

由 SDK 内部调用。检索最近地理区域的参数及其距离。同时记录设备位置以用于地理推送通知。

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


### 请求正文参数


| 参数 | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|-----------|--------|:--------:|-------------|
| **application** | `string` | 是 | [Pushwoosh 应用代码](/zh/developer/api-reference/api-identifiers/#application-code) |
| **hwid** | `string` | 是 | 在 `/registerDevice` 请求中使用的[硬件设备 ID](/zh/developer/api-reference/api-identifiers/#hardware-id)。 |
| **lat** | `string` | 是 | 设备的纬度。 |
| **lng** | `string` | 是 | 设备的经度。 |


### 请求示例

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

### PHP 示例

```php
// 请参阅 http://gomoob.github.io/php-pushwoosh/get-nearest-zone.html

use Gomoob\Pushwoosh\Model\Request\GetNearestZoneRequest;

// 创建请求实例
$request = GetNearestZoneRequest::create()
    ->setHwid('HWID')
    ->setLat(10.12345)
    ->setLng(28.12345);

// 调用 '/getNearestZone' Web 服务
$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

向特定应用添加一个地理区域。

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


### 请求正文参数


| 参数 <div style="width:150px"></div> | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|-----------|--------|:--------:|-------------|
| **auth** | `string` | 是 | 来自 Pushwoosh 控制面板的 [API 访问令牌](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| **application** | `string` | 是 | [Pushwoosh 应用代码](/zh/developer/api-reference/api-identifiers/#application-code) |
| **geozones** | `array` | 是 | 地理区域参数，以 JSON 数组形式表示。 |
| **geozones.name** | `string` | 是 | 地理区域名称。 |
| **geozones.lat** | `string` | 是 | 地理区域纬度。 |
| **geozones.lng** | `string` | 是 | 地理区域经度。 |
| **geozones.cooldown** | `integer` | 是 | 发送通知后的静默期（以秒为单位）。 |
| **geozones.range** | `integer` | 是 | 地理区域范围（以米为单位）。最小值为 50。 |
| **geozones.content** | `string or object` | 如果 `presetCode` 为空，则为必需。 | 地理区域消息内容。 |
| **geozones.presetCode** | `string` | 如果 `content` 为空，则为必需。 | 用于替代 `content` 的[推送预设](/zh/developer/api-reference/api-identifiers/#preset-code)。 |
| **geozones.cluster** | `string` | 否 | 指定 `null` 以将集群与地理区域解绑。 |
| **geozones.campaign** | `string` | 否 | 指定 `null` 以将营销活动与地理区域解绑。如果省略，营销活动值将保持不变。注意：其优先级高于预设中的营销活动。 |
| **geozones.timetable** | `object` | 否 | 设置时间表间隔。 |


### 请求示例

```json
{ 
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX",            // Pushwoosh 应用代码
    "geozones": [{
      "name": "Statue of George",            // 必需。地理区域名称。
      "lat": "40.70087797",                   // 必需。地理区域纬度。
      "lng": "-73.931851387",                 // 必需。地理区域经度。
      "cooldown": 60,                         // 以秒为单位，必需。发送通知后的静默期
      "range": 50,                            // 以米为单位，最小 50，必需。地理区域的范围。
      "content": "Lorem ipsum dolor sit amet,
       consectetur adipiscing elit.",         // 或对象
      "presetCode": "AAAAA-BBBBB",            // 可选。可使用推送预设代替内容
      "cluster": "GEOZONE CLUSTER CODE",      // 可选。将应用集群的冷却期
      "campaign": "CAMPAIGN_CODE",            // 可选。指定 null 以将营销活动与地理区域解绑
      "timetable": {                          // 可选
        "timezone": 1234,                     // 以秒为单位
        "Mon": [                              // 可用日期：Mon, Tue, Wed, Thu, Fri, Sat, Sun。推送发送
          {
            "start": "04:11",
            "stop": "12:00"
          }
        ],
        "Sun": [
          {                                    // 一个或两个时间间隔
            "start": "01:11",
            "stop": "17:00"
          },
          {
            "start": "18:01",
            "stop": "23:59"
          }
        ]
      }
    }]
  }
}

```
## updateGeoZone

更新地理区域属性。

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

### 请求正文参数

| 参数 <div style="width:150px"></div> | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|-----------|--------|:--------:|-------------|
| **auth** | `string` | 是 | 来自 Pushwoosh 控制面板的 [API 访问令牌](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| **geoZoneId** | `string` | 是 | 来自 `/addGeoZone` 请求的[地理区域 ID](/zh/developer/api-reference/api-identifiers/#geozone-id)。 |
| **name** | `string` | 否 | 新的地理区域名称。 |
| **cooldown** | `integer` | 否 | 要更新的冷却时间，以秒为单位。 |
| **status** | `integer` | 否 | 0 - 停用，1 - 激活。 |
| **content** | `string` | 否 | 地理区域推送通知的内容。不能与 `presetCode` 一起使用。 |
| **cluster** | `string` | 否 | 新的集群名称。指定 `null` 以将集群与地理区域解绑。 |
| **campaign** | `string` | 否 | 新的营销活动 ID。指定 `null` 以将营销活动与地理区域解绑。如果省略，营销活动值将不会改变。其优先级高于预设中的营销活动。 |
| **lat** | `number` | 否 | 地理区域纬度。 |
| **lng** | `number` | 否 | 地理区域经度。 |
| **range** | `integer` | 否 | 新的范围，以米为单位。 |
| **timetable** | `object` | 否 | 地理区域时间表。详见下文。 |

---


### 请求示例

```json
{ 
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "geoZoneId": 100016750,                  // 必需，来自 /addGeoZone 方法
    "name": "new geozone name",              // 可选
    "cooldown": 222,                         // 以秒为单位，可选
    "status": 0,                             // 可选，0 - 停用，1 - 激活
    "presetCode": "BBBBB-AAAAA",             // 可选，不能与 "content" 一起使用
    "content": "new geozone content",        // 可选，不能与 "presetCode" 一起使用
    "cluster": "GEOZONE CLUSTER CODE",       // 可选。指定 null 以将集群与地理区域解绑
    "campaign": "CAMPAIGN_CODE",             // 可选。指定 null 以将营销活动与地理区域解绑
    "lat": 10.56,                            // 可选，地理区域纬度
    "lng": 12.523,                           // 可选，地理区域经度
    "range": 500,                            // 可选，地理区域范围
    "timetable": {                           // 可选
      "timezone": 1234,                      // 以秒为单位
      "Mon": [                               // 可用日期：Mon, Tue, Wed, Thu, Fri, Sat, Sun。推送发送
        {
          "start": "04:11",
          "stop": "12:00"
        }
      ],
      "Sun": [
        {                                    // 一个或两个时间间隔
          "start": "01:11",
          "stop": "17:00"
        },
        {
          "start": "18:01",
          "stop": "23:59"
        }
      ]
    }
  }
}
```

## deleteGeoZone

从应用中移除地理区域。

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

### 请求正文参数


| 参数 <div style="width:150px"></div> | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|-------------|--------|:--------:|-------------|
| **auth** | `string` | 是 | 来自 Pushwoosh 控制面板的 [API 访问令牌](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| **application** | `string` | 是 | [Pushwoosh 应用代码](/zh/developer/api-reference/api-identifiers/#application-code) |
| **geozones** | `string` | 是 | 要移除的地理区域的 ID 数组或[单个 ID](/zh/developer/api-reference/api-identifiers/#geozone-id)。 |



### 请求示例

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX",            // 必需，Pushwoosh 应用代码
    "geozones": [550, 526]                   // 必需，地理区域 ID
  }
}
```

## addGeoZoneCluster

向应用添加地理区域集群。

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


### 请求正文参数

| 参数 <div style="width:150px"></div> | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|-------------|--------|:--------:|-------------|
| **auth** | `string` | 是 | 来自 Pushwoosh 控制面板的 [API 访问令牌](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| **application** | `string` | 是 | [Pushwoosh 应用代码](/zh/developer/api-reference/api-identifiers/#application-code) |
| **name** | `string` | 是 | 集群名称。 |
| **cooldown** | `integer` | 是 | 单个用户从地理区域集群接收相同消息前的延迟时间，以秒为单位。 |


### 请求示例

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX",            // 必需，Pushwoosh 应用代码
    "name": "Raccoon city",                  // 必需，集群名称
    "cooldown": 3210                         // 必需，以秒为单位
  }
}
```

## deleteGeoZoneCluster

从应用中移除地理区域集群。


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


### 请求正文参数


| 参数 <div style="width:150px"></div> | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|-------------------|--------|:--------:|-------------|
| **auth** | `string` | 是 | 来自 Pushwoosh 控制面板的 [API 访问令牌](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| **application** | `string` | 是 | [Pushwoosh 应用代码](/zh/developer/api-reference/api-identifiers/#application-code) |
| **geoZoneCluster** | `string` | 是 | 要移除的地理区域集群的 ID。 |


### 请求示例

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX",            // 必需，Pushwoosh 应用代码
    "geoZoneCluster": "EA1CE-69405"          // 必需，从 /addGeoZoneCluster 请求中获取的集群 ID
  }
}
```

## listGeoZones

检索应用的地理区域列表。


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

### 请求正文参数


| 参数 <div style="width:150px"></div> | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|-------------|--------|:--------:|-------------|
| **auth** | `string` | 是 | 来自 Pushwoosh 控制面板的 [API 访问令牌](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| **application** | `string` | 是 | [Pushwoosh 应用代码](/zh/developer/api-reference/api-identifiers/#application-code) |


### 请求示例

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX"             // 必需，Pushwoosh 应用代码
  }
}
```
## listGeoZoneClusters

检索应用的地理区域集群列表。

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


### 请求正文参数


| 参数 <div style="width:150px"></div> | 类型 <div style="width:80px"></div> | 必需 | 描述 |
|-------------|--------|:--------:|-------------|
| **auth** | `string` | 是 | 来自 Pushwoosh 控制面板的 [API 访问令牌](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| **application** | `string` | 是 | [Pushwoosh 应用代码](/zh/developer/api-reference/api-identifiers/#application-code) |


### 请求示例

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX"             // 必需，Pushwoosh 应用代码
  }
}
```