API de Geozonas

getNearestZone

Llamado internamente desde el SDK. Recupera los parámetros de la geozona más cercana y la distancia a ella. También registra la ubicación del dispositivo para las notificaciones push geolocalizadas.

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

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	Código de aplicación de Pushwoosh
hwid	string	Sí	ID de hardware del dispositivo utilizado en la solicitud /registerDevice.
lat	string	Sí	Latitud del dispositivo.
lng	string	Sí	Longitud del dispositivo.

Ejemplo de solicitud

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

Ejemplo de 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

Agrega una Geozona a una aplicación específica.

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

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
auth	string	Sí	Token de acceso a la API desde el Panel de Control de Pushwoosh.
application	string	Sí	Código de aplicación de Pushwoosh
geozones	array	Sí	Parámetros de la Geozona como un array JSON.
geozones.name	string	Sí	Nombre de la Geozona.
geozones.lat	string	Requerido para un círculo.	Latitud de la Geozona. Omitir cuando se establece polygon — una geozona poligonal deriva su propio centro.
geozones.lng	string	Requerido para un círculo.	Longitud de la Geozona. Omitir cuando se establece polygon — una geozona poligonal deriva su propio centro.
geozones.cooldown	integer	Sí	Período de silencio después de enviar una notificación (en segundos).
geozones.range	integer	Requerido para un círculo.	Rango de la Geozona en metros. Mínimo 50. Omitir cuando se establece polygon — una geozona poligonal deriva su propio rango.
geozones.polygon	object	No	Convierte la geozona en un polígono en lugar de un círculo. No se puede combinar con lat/lng/range — enviar ambos será rechazado. Ver Geozonas poligonales.
geozones.content	string or object	Requerido si presetCode está vacío.	Contenido del mensaje de la Geozona.
geozones.presetCode	string	Requerido si content está vacío.	Preset de push para usar en lugar de content.
geozones.cluster	string	No	Especificar null para desvincular un clúster de la Geozona.
geozones.campaign	string	No	Especificar null para desvincular una campaña de la Geozona. Si se omite, el valor de la campaña no cambiará. Nota: Tiene mayor prioridad que la campaña en el preset.
geozones.timetable	object	No	Establece los intervalos del horario.

Ejemplo de solicitud

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

Agregar varias geozonas a la vez

geozones toma un array, por lo que una llamada puede crear un lote completo. El lote se valida en su totalidad antes de que se escriba algo: si se rechaza alguna entrada, la llamada falla y no se crea ninguna geozona de esa solicitud. El error nombra la entrada infractora por su posición en el array, contada desde cero:

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

Corrija esa entrada y envíe la solicitud de nuevo. Si tiene éxito, GeoZones contiene los nuevos ID numéricos en el mismo orden que las entradas que envió.

Se aceptan lotes de más de 500 entradas y se dividen en trozos internamente. Todo el array se valida antes de la primera escritura, pero la escritura en sí no es atómica entre trozos: una entrada puede pasar la validación y aun así no escribirse, por ejemplo, si el preset que nombra se elimina mientras tanto. En ese caso, la llamada devuelve 200 con los ID que se escribieron más un array Errors que nombra la entrada que detuvo la ejecución, por lo que no se pierde nada de lo creado:

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

Errors está ausente cuando se escribió cada entrada, por lo que una respuesta totalmente exitosa no cambia. Un array GeoZones más corto que el array que envió siempre significa que algunas entradas no se crearon.

Precaución

Los nombres de las Geozonas no son únicos. Reenviar un lote que ya tuvo éxito crea una segunda copia de cada geozona en él.

Geozonas poligonales

Envíe polygon en lugar de lat/lng/range para hacer de la geozona un polígono. polygon.vertices es un anillo ordenado de puntos {lat, lng} que describe el contorno de la forma:

{
  "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 y range se derivan del anillo — el círculo que un dispositivo realmente monitorea está centrado en la forma con un radio que alcanza su vértice más lejano (mínimo 50 m). Se rechaza el envío de polygon junto con lat/lng/range.

Puede enviar el anillo abierto o cerrado — si el último vértice repite el primero, el servidor elimina ese duplicado de cierre antes de validar. Validación de vértices, en el anillo resultante: de 3 a 100 vértices distintos. El anillo también se rechaza si sus puntos son colineales, si sus bordes se auto-intersecan, o si cruza el antimeridiano.

updateGeoZone

Actualiza las propiedades de la Geozona.

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

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
auth	string	Sí	Token de acceso a la API desde el Panel de Control de Pushwoosh.
geoZoneId	string	Sí	ID de Geozona de la solicitud /addGeoZone.
name	string	No	Nuevo nombre de la Geozona.
cooldown	integer	No	Cooldown para actualizar, en segundos.
status	integer	No	0 - desactivado, 1 - activado.
content	string	No	Contenido para la notificación push de la Geozona. No se puede usar con presetCode.
cluster	string	No	Nuevo nombre del clúster. Especificar null para desvincular el clúster de la Geozona.
campaign	string	No	Nuevo ID de campaña. Especificar null para desvincular la Campaña de la Geozona. Si se omite, el valor de la Campaña no cambiará. Tiene mayor prioridad que una Campaña de un preset.
lat	number	No	Latitud de la Geozona. No se puede combinar con polygon.
lng	number	No	Longitud de la Geozona. No se puede combinar con polygon.
range	integer	No	Nuevo rango en metros. No se puede combinar con polygon.
polygon	object	No	Nuevo anillo de vértices {lat, lng} — reemplaza la forma y re-deriva lat/lng/range a partir de él. Ver Geozonas poligonales. Funciona en ambos sentidos: envíelo en una geozona circular existente para convertirla en un polígono, o envíe un anillo vacío ({"vertices": []}) en una geozona poligonal existente para volver a convertirla en un círculo. Omita polygon por completo para dejar la forma sin cambios. Misma validación de vértices que en addGeoZone.
timetable	object	No	Horario de la Geozona. Ver más información a continuación.

---

Ejemplo de solicitud

{
  "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

Elimina Geozonas de la aplicación.

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

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
auth	string	Sí	Token de acceso a la API desde el Panel de Control de Pushwoosh.
application	string	Sí	Código de aplicación de Pushwoosh
geozones	string	Sí	Array de IDs o un único ID de una Geozona para eliminar.

Ejemplo de solicitud

{
  "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

Agrega un Clúster de Geozonas a la aplicación.

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

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
auth	string	Sí	Token de acceso a la API desde el Panel de Control de Pushwoosh.
application	string	Sí	Código de aplicación de Pushwoosh
name	string	Sí	Nombre del clúster.
cooldown	integer	Sí	Un retraso antes de que un solo usuario pueda recibir el mismo mensaje del Clúster de Geozonas, en segundos.

Ejemplo de solicitud

{
  "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

Elimina un Clúster de Geozonas de la aplicación.

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

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
auth	string	Sí	Token de acceso a la API desde el Panel de Control de Pushwoosh.
application	string	Sí	Código de aplicación de Pushwoosh
geoZoneCluster	string	Sí	ID del clúster de Geozonas a eliminar.

Ejemplo de solicitud

{
  "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

Recupera una lista de Geozonas para la aplicación.

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

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
auth	string	Sí	Token de acceso a la API desde el Panel de Control de Pushwoosh.
application	string	Sí	Código de aplicación de Pushwoosh

Ejemplo de solicitud

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

listGeoZoneClusters

Recupera una lista de clústeres de Geozonas para la aplicación.

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

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
auth	string	Sí	Token de acceso a la API desde el Panel de Control de Pushwoosh.
application	string	Sí	Código de aplicación de Pushwoosh

Ejemplo de solicitud

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