# واجهة برمجة تطبيقات المناطق الجغرافية (Geozones API)

## getNearestZone

يتم استدعاؤها داخليًا من SDK. تسترجع معلمات أقرب منطقة جغرافية والمسافة إليها. كما تسجل موقع الجهاز لإشعارات الدفع الجغرافية.

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


### معلمات نص الطلب  


| المعلمة | النوع <div style="width:80px"></div> | مطلوب | الوصف |
|-----------|--------|:--------:|-------------|
| **application** | `string` | نعم | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |
| **hwid** | `string` | نعم | [معرف جهاز العتاد (Hardware device ID)](/ar/developer/api-reference/api-identifiers/#hardware-id) المستخدم في طلب `/registerDevice`. |
| **lat** | `string` | نعم | خط عرض الجهاز. |
| **lng** | `string` | نعم | خط طول الجهاز. |


### مثال على الطلب 

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

### مثال PHP

```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  

يضيف منطقة جغرافية (Geozone) إلى تطبيق معين.  

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


### معلمات نص الطلب  


| المعلمة <div style="width:150px"></div>  | النوع <div style="width:80px"></div> | مطلوب | الوصف |
|-----------|--------|:--------:|-------------|
| **auth** | `string` | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| **application** | `string` | نعم | [رمز تطبيق Pushwoosh](/ar/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` فارغًا. | [إعداد مسبق للدفع (Push preset)](/ar/developer/api-reference/api-identifiers/#preset-code) لاستخدامه بدلاً من `content`. |
| **geozones.cluster** | `string` | لا | حدد `null` لإلغاء ربط مجموعة (cluster) من المنطقة الجغرافية. |
| **geozones.campaign** | `string` | لا | حدد `null` لإلغاء ربط حملة (campaign) من المنطقة الجغرافية. إذا تم حذفه، تظل قيمة الحملة دون تغيير. ملاحظة: له أولوية أعلى من الحملة في الإعداد المسبق. |
| **geozones.timetable** | `object` | لا | يحدد فترات الجدول الزمني. |


### مثال على الطلب  

```json
{ 
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "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  

يحدّث خصائص المنطقة الجغرافية (Geozone).  

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

### معلمات نص الطلب  

| المعلمة <div style="width:150px"></div> | النوع <div style="width:80px"></div> | مطلوب | الوصف |
|-----------|--------|:--------:|-------------|
| **auth** | `string` | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| **geoZoneId** | `string` | نعم | [معرف المنطقة الجغرافية (Geozone ID)](/ar/developer/api-reference/api-identifiers/#geozone-id) من طلب `/addGeoZone`. |
| **name** | `string` | لا | اسم المنطقة الجغرافية الجديد. |
| **cooldown** | `integer` | لا | فترة التهدئة للتحديث، بالثواني. |
| **status** | `integer` | لا | 0 - معطل، 1 - مفعل. |
| **content** | `string` | لا | محتوى إشعار الدفع للمنطقة الجغرافية. لا يمكن استخدامه مع `presetCode`. |
| **cluster** | `string` | لا | اسم المجموعة الجديد. حدد `null` لإلغاء ربط المجموعة من المنطقة الجغرافية. |
| **campaign** | `string` | لا | معرف الحملة الجديد. حدد `null` لإلغاء ربط الحملة من المنطقة الجغرافية. إذا تم حذفه، فلن تتغير قيمة الحملة. له أولوية أعلى من الحملة من الإعداد المسبق. |
| **lat** | `number` | لا | خط عرض المنطقة الجغرافية. |
| **lng** | `number` | لا | خط طول المنطقة الجغرافية. |
| **range** | `integer` | لا | النطاق الجديد بالأمتار. |
| **timetable** | `object` | لا | الجدول الزمني للمنطقة الجغرافية. انظر المزيد من المعلومات أدناه. |

---


### مثال على الطلب  

```json
{ 
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "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  

يزيل المناطق الجغرافية (Geozones) من التطبيق.  

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

### معلمات نص الطلب  


| المعلمة   <div style="width:150px"></div>   | النوع <div style="width:80px"></div>   | مطلوب | الوصف |
|-------------|--------|:--------:|-------------|
| **auth**    | `string` | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| **application** | `string` | نعم | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |
| **geozones** | `string` | نعم | مصفوفة من المعرفات أو [معرف واحد](/ar/developer/api-reference/api-identifiers/#geozone-id) لمنطقة جغرافية لإزالتها. |



### مثال على الطلب  

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX",            // مطلوب، رمز تطبيق Pushwoosh
    "geozones": [550, 526]                   // مطلوب، معرفات المناطق الجغرافية
  }
}
``` 

## addGeoZoneCluster  

يضيف مجموعة مناطق جغرافية (Geozone Cluster) إلى التطبيق.  

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

### معلمات نص الطلب  

| المعلمة  <div style="width:150px"></div>  | النوع <div style="width:80px"></div>    | مطلوب | الوصف |
|-------------|--------|:--------:|-------------|
| **auth**    | `string` | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| **application** | `string` | نعم | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |
| **name** | `string` | نعم | اسم المجموعة. |
| **cooldown** | `integer` | نعم | تأخير قبل أن يتمكن مستخدم واحد من تلقي نفس الرسالة من مجموعة المناطق الجغرافية، بالثواني. |


### مثال على الطلب 

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX",            // مطلوب، رمز تطبيق Pushwoosh
    "name": "Raccoon city",                  // مطلوب، اسم المجموعة
    "cooldown": 3210                         // مطلوب، بالثواني
  }
}
``` 

## deleteGeoZoneCluster  

يزيل مجموعة مناطق جغرافية (Geozone Cluster) من التطبيق.  

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


### معلمات نص الطلب


| المعلمة   <div style="width:150px"></div>        | النوع  <div style="width:80px"></div>  | مطلوب | الوصف |
|-------------------|--------|:--------:|-------------|
| **auth**         | `string` | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| **application**  | `string` | نعم | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |
| **geoZoneCluster** | `string` | نعم | معرف مجموعة المناطق الجغرافية المراد إزالتها. |


### مثال على الطلب   

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX",            // مطلوب، رمز تطبيق Pushwoosh
    "geoZoneCluster": "EA1CE-69405"          // مطلوب، معرف المجموعة الذي تم الحصول عليه من طلب /addGeoZoneCluster
  }
}
```

## listGeoZones  

يسترجع قائمة بالمناطق الجغرافية (Geozones) للتطبيق.  


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

### معلمات نص الطلب 


| المعلمة  <div style="width:150px"></div>    | النوع <div style="width:80px"></div>   | مطلوب | الوصف |
|-------------|--------|:--------:|-------------|
| **auth**    | `string` | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| **application** | `string` | نعم | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |


### مثال على الطلب  

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX"             // مطلوب، رمز تطبيق Pushwoosh
  }
}
```
## listGeoZoneClusters  

يسترجع قائمة بمجموعات المناطق الجغرافية (Geozone clusters) للتطبيق.  

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


### معلمات نص الطلب 


| المعلمة <div style="width:150px"></div>   | النوع <div style="width:80px"></div>    | مطلوب | الوصف |
|-------------|--------|:--------:|-------------|
| **auth**    | `string` | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| **application** | `string` | نعم | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |


### مثال على الطلب

```json
{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // مطلوب، رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "application": "XXXXX-XXXXX"             // مطلوب، رمز تطبيق Pushwoosh
  }
}
```