Servicio segmento de polígono geográfico

Artículo
07/16/2024

Nota:

Este servicio está en Alfa. Esta característica está sujeta a cambios sin previo aviso y solo está disponible para seleccionar clientes. Si desea participar en la prueba Alfa, póngase en contacto con el administrador de cuentas.

Geo Polygon Segment Service le permite crear, configurar y exportar segmentos de polígono geográfico. Un segmento de polígono geográfico es una lista de ubicaciones de usuario especificadas por coordenadas de polígono de texto conocido (WKT). El texto conocido (WKT) es un lenguaje de marcado de texto para representar objetos de geometría vectorial en un mapa mediante coordenadas. Después de crear un segmento de polígono geográfico, puede usar el segmento asociado automáticamente a él para la segmentación geográfica de varias ubicaciones de usuario. El servicio de segmento de polígono geográfico le permite cargar archivos CSV de WKT de polígono geográfico en un segmento geográfico. Puede usar el mismo segmento geográfico para la segmentación en el nivel de elemento de línea.

Advertencia

Geo Polygon Segment Service se basa en coordenadas de polígono de texto conocido (WKT). Esto indica que los polígonos geográficos deben cargarse en formato de longitud y latitud (long, lat) en lugar de latitud y longitud (lat, long).

Flujo de proceso

Para crear un segmento con polígonos geográficos, siga estos pasos:

Cree un segmento de shell. Para crear el segmento de shell, realice una llamada POST al punto de /geo-polygon-segment conexión.
Cargue polígonos en el segmento de shell. Puede crear un archivo CSV con polígonos en él y realizar una llamada POST al punto de /geo-polygon-segment/{segmentID}/upload-polygon conexión.
Para comprobar si la carga se realizó correctamente, compruebe el estado del trabajo a través del /geo-segment-processor/job-status punto de conexión después de enviar una solicitud de carga para los polígonos.

API de REST

Http (método)	Endpoint	Description
`POST`	`https://api.appnexus.com/geo-polygon-segment` (JSON new-geo-polygon-segment)	Creación de un nuevo segmento de polígono geográfico
`POST`	`https://api.appnexus.com/geo-polygon-segment/{segmentID}/upload-polygon` (add-polygons.csv)	Adición de polígonos a un segmento
`POST`	`https://api.appnexus.com/geo-polygon-segment` (JSON new-geo-polygon-segment)	Creación de un nuevo segmento de polígono geográfico
`POST`	`https://api.appnexus.com/geo-polygon-segment/select` `POST -d '{"criteria":{},"ordering": {"direction":"desc","by":"id"}}' "https://api.appnexus.com/geo- polygon-segment/select"`	Visualización de todos los segmentos de polígono geográfico de un miembro
`POST`	`https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/select` `POST -d '{"criteria":{},"ordering":{"direction":"desc","by":"id"}}' "https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/select"`	Ver los detalles de un segmento de polígono geográfico específico
`POST`	`https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/select` `POST -d '{"criteria":{},"ordering":{"direction":"desc","by":"id"}}' "https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/select"`	Visualización de todas las definiciones de polígono geográfico en un segmento
`GET`	`https://api.appnexus.com/apd-status`	Visualización de cargas recientes
`GET`	`https://api.appnexus.com/apd-status?id=%7Bapd_id%7D`	Visualización del estado de una carga específica
`GET`	`https://api.appnexus.com/geo-segment-processor/job-status`	Visualización del estado de una carga de polígono geográfico
`DELETE`	`https://api.appnexus.com/geo-polygon-segment/{segmentID}`	Eliminación de un segmento de polígono geográfico
`DELETE`	`https://api.appnexus.com/geo-polygon-segment/%7BsegmentID%7D/polygon/delete` `POST -d '{"criteria":{"id":{"in":[_polygon_feature_id_]}}}' "https://api.appnexus.com/geo-polygon-segment/{segmentID}/polygon/delete"`	Eliminación de una característica específica de un segmento de polígono geográfico

Campos JSON

Creación de un nuevo json de segmento de polígono geográfico

Campo	Tipo	Descripción
`code`	string	Código definido por el usuario para llamar al segmento de polígono geográfico. Por ejemplo: `"GEO123"`
`description`	string	Descripción de este segmento de polígono geográfico
`short_name`	string	Nombre corto que se usa para describir el segmento de polígono geográfico Obligatorio activado: `POST`
`regional_centers`	matriz de objetos	Identificador o código de la región en la que está disponible el segmento de polígono geográfico. Valores posibles: - Identificador: 1, 2 o 3 - código: "americas", "emea", "apac"

`CSV` formato de archivo

El archivo CSV tiene los nombres de columna como Polygon y Name y contienen los valores de los polígonos geográficos definidos.

Nota:

Los nombres de columna distinguen mayúsculas de minúsculas y no tienen espacio. Debe especificar los nombres de columna en el archivo CSV.

Ejemplo

`add-polygons.csv`

Polygon,Name
"POLYGON((-73.79619781688602 40.926119268030504,-73.96923248485477 40.95931402310335,-74.09008209422977 
40.52648176879785,-73.23864166454227 
40.62870062738066,-73.38421051219852 40.926119268030504,-73.79619781688602 40.926119268030504))",FirstPolygon

Nota:

Los polígonos deben especificarse dentro de comillas, según lo requiera el estándar de archivo CSV.

Una vez que cargue el archivo CSV correctamente, la API envía la respuesta con los campos siguientes:

geo_segment_polygon_id: identificador generado automáticamente del polígono geográfico almacenado en el sistema de Xandr.
name: nombre del polígono geográfico.
apd_id: el identificador de trabajo de la carga. Debe realizar un seguimiento de esto en caso de que desee realizar un seguimiento del estado de la carga.

Nota:

Debe mantener un registro de las respuestas de carga, ya que será necesario para solucionar problemas.

Ejemplos

Creación de un nuevo segmento de polígono geográfico

$ cat new-geo-polygon-segment.json

{
  "short_name": "New Geo Polygon Segment",
  "description": "Creating a new geo polygon segment example",
  "regional_centers": [
    {
      "id": 1
    }
  ]
}

Alternatively

$ cat new-geo-polygon-segment.json
{
  "short_name": "New Geo Polygon Segment",
  "description": "Creating a new geo polygon segment example",
  "regional_centers": [
    {
      "code": "emea"
    }
  ]
}

$ curl -b cookies -d @new-geo-segment.json -X POST "https://api.appnexus.com/geo-polygon-segment"
{
 "id": 35619,
 "segment_id": 27258480,
 "created_on": "2021-08-04 03:17:41",
 "updated_on": "2021-08-04 03:17:41"
}

Ver todos los centros regionales admitidos

$ curl -b cookies "https://api.appnexus.com/regional-center"
{
 "regional_centers": [
   {
     "id": 1,
     "code": "emea",
     "name": "Europe, Middle East, Africa"
   },
  {
     "id": 2,
     "code": "americas",
     "name": "North, Central and South America"
  },
  {
     "id": 3,
     "code": "apac",
     "name": "Asia and Pacific"
  }
 ]
}

Carga de polígonos en el segmento recién creado

Punto de conexión

POST /geo-polygon-segment/<segment_id>/upload-polygon

Parámetros

Campo	Description
`segment_id` (en la ruta de acceso)	Identificador del segmento.

Ejemplo

Solicitud

POST https://api.appnexus.com/geo-polygon-segment/36039750/upload-polygon

Cuerpo

Un archivo CSV que contiene polígonos.

Respuesta

{
    "objects": {
        "polygons": [
            {
                "id": 54684042,
                "name": "FirstPolygon"
            },
            {
                "id": 54684043,
                "name": "SecondPolygon"
            }
        ],
        "apd_ids": {
            "americas": "b5fa59ea-a9a7-11ee-8c12-3cfdfed1a940"
        }
    },
    "job_id": 268,
    "segment_id": 36039750,
    "workflow": "UPLOAD_GEO_SEGMENT_POLYGON",
    "offset": 1, 
    "total": 2, 
  }

Visualización de todos los segmentos de polígono geográfico de un miembro


$ curl -b cookies -c cookies -X POST -d '{"criteria":{},"ordering":{"direction":"desc","by":"id"}}'
"<https://api.appnexus.com/geo-polygon-segment/select>"

Visualización de todas las definiciones de polígono geográfico en un segmento


 curl -b cookies -c cookies -X POST -d '{"criteria":{},"ordering":{"direction":"desc","by":"id"}}'
 "<https://api.appnexus.com/geo-polygon-segment/27258480/polygon/select>"

Visualización de cargas recientes


curl -b cookies "<https://api.appnexus.com/apd-status>"

Visualización del estado de una carga específica


curl -b cookies "<https://api.appnexus.com/apd-status?id=4d362ab8-f94d-11eb-a5ee-3cfdfec8e950>"

Visualización del estado de carga de la carga del polígono geográfico

  curl -b cookies -c cookies -X GET "<https://api.appnexus.com/geo-segment-processor/job-status?geoSegmentId=86831>"

Eliminación de un segmento de polígono geográfico

Punto de conexión

DELETE /geo-polygon-segment/<segment_id>

Parámetros

Campo	Description
`segment_id` (en la ruta de acceso)	Identificador del segmento.

Ejemplo

Solicitud

DELETE https://api.appnexus.com/geo-polygon-segment/36039750

Respuesta


{ 
    "job_id": 332, 
    "apd_ids": { 
        "americas": "98acb9c8-aa4b-11ee-b336-40a6b7543210" 
    }, 
    "segment_id": 36039750, 
    "workflow": "DELETE_GEOPOLYGON_SEGMENT" 
}

Eliminación de una característica específica de un segmento de polígono geográfico

Punto de conexión

POST /geo-polygon-segment/<segment_id>/polygon/delete

Parámetros

Campo	Description
`segment_id` (en la ruta de acceso)	Identificador del segmento del que se va a eliminar un polígono.

Ejemplo

Solicitud

POST https://api.appnexus.com/geo-polygon-segment/36039750/polygon/delete

Cuerpo

JSON


{
    "criteria": {
        "id": {
            "in": [54684042]
        }
    }
}

Respuesta

JSON


{
    "job_id": 329,
    "segment_id": 36039750,
    "objects": {
        "polygons": [
            {
                "name": "FirstPolygon",
                "id": 54684042,
                "polygon_wkt": "POLYGON((-73.796197816886 40.9261192680305,-73.9692324848548 40.9593140231034,-74.0900820942298 40.5264817687979,-73.2386416645423 40.6287006273807,-73.3842105121985 40.9261192680305,-73.796197816886 40.9261192680305))"
            }
        ],
        "apd_ids": {
            "americas": "b5fa59ea-a9a7-11ee-8c12-3cfdfed1a940"
        }
    },
    "workflow": "DELETE_GEO_SEGMENT_POLYGON"
}

Comprobar el estado del trabajo

Para comprobar el estado de cualquier trabajo, use la job_id proporcionada en la respuesta para realizar una solicitud al punto de conexión de estado del trabajo.

Punto de conexión

GET /geo-segment-processor/job-status

Parámetros

Campo	Description
`jobId`	Identificador del trabajo.
`geoSegmentId`	Identificador del segmento geográfico.
`segmentId`	Identificador de segmento.
`numJobsToRetrieve`	Número de trabajos que se van a recuperar.

Para supervisar el progreso de las solicitudes de carga o eliminación, puede consultar el estado de un trabajo mediante parámetros específicos.

Campo	Tipo	Descripción
`job_state`	string	Indica el estado actual del trabajo general. Los valores posibles de los estados de trabajo son los siguientes: - creado : el trabajo se ha programado, pero aún no se ha ejecutado. activo : actualmente se está procesando un trabajo relacionado con el trabajo general. cancelado : el trabajo se ha cancelado manualmente o debido a un error. reintento : el trabajo se puede reintentar una vez si se ha producido un error en alguna solicitud interna. completed : el trabajo se ha completado correctamente. expirado : el trabajo no se ha seleccionado para su procesamiento después de 12 horas, por lo que ha expirado y no se procesará. error : se produjo un error en algún momento y se produjo un error en el trabajo. en curso : el trabajo general se está procesando, con sub jobs programados y procesados para comprobar continuamente si el trabajo de APD se completará antes de que se pueda completar el trabajo de cola de trabajos.
`job_id`	número	Identificador del trabajo general.
`workflow`	string	Flujo de trabajo asociado al trabajo. Los siguientes flujos de trabajo están asociados al trabajo. - DELETE_GEOPOLYGON_SEGMENT - DELETE_GEO_SEGMENT - UPLOAD_GEO_SEGMENT_POLYGON - DELETE_GEO_SEGMENT_POLYGON - CREATE_GEO_SEGMENT_FEATURE - DELETE_GEO_SEGMENT_FEATURE
`geo_segment_id`	número	Identificador de segmento geográfico asociado a la solicitud. Nota: Normalmente, un identificador interno. Aunque este identificador se usa para solicitudes relacionadas con el radio geográfico.
`segment_id`	string	Identificador de segmento asociado a la solicitud. Nota: Este identificador se usa para solicitudes relacionadas con polígonos geográficos.
`job_results`	objeto	Objeto que contiene información sobre el trabajo, actualizado una vez que el trabajo comienza a procesarse. `apdJobStatus` - Contiene los resultados actuales del trabajo de APD por el identificador de trabajo. `apdJobIds` : contiene el identificador de trabajo de cada región. `initialJobRecordId` - El identificador del trabajo. Debe coincidir con el parámetro jobId especificado en esta solicitud. `jobCount` - El número de sub jobs que componen el trabajo general. `jobErrors` - Contiene cualquier error relacionado con el motivo por el que se produjo un error en el trabajo, se canceló o se reintentó.
`job_name`	string	Especifica el nombre de la cola de trabajos. Hay dos tipos de trabajo: - `apd status check` - `apd job complete`. También indica el entorno desde el que se originó la solicitud (desarrollo, ensayo o producción). - `bff_apd_status_check_queue_<env>` - `bff_apd_job_complete_queue_<env>` Nota: `<env>` puede ser `dev`, `staging`o `prod`.
`created_on`	string	Fecha y hora en que se creó el trabajo.
`num_records`	número	Número de polígonos o características asociados al trabajo. Por ejemplo, si acaba de realizar una solicitud para cargar 500 polígonos, num_records será 500.

Respuesta


{
    "jobs":
    [
        {
            "job_state": "completed",
            "job_id": 270,
            "workflow": "DELETE_GEOPOLYGON_SEGMENT",
            "geo_segment_id": 36039750,
            "segment_id": 36039750,
            "job_results": {
                "jobCount": 1
            },
            "job_name": "bff_apd_status_check_queue_prod",
            "created_on": "2024-01-02 04:37:19",
            "num_records": 1
        }
    ]
}

Puntos importantes a tener en cuenta

El servicio de segmento de polígono geográfico no acepta actualmente definiciones de polígonos geográficos con agujeros (en geometría, un polígono con agujeros es un polígono plana conectado al área con un límite externo y uno o más límites interiores). Si una definición de polígono contiene un taladro, el servicio omitirá el taladro.
El número máximo de definiciones de polígono que se pueden hospedar en un segmento es de 50 000.
Cuando la carga del archivo CSV se realiza correctamente, el servicio devuelve apd_id y geo_segment_polygon_id en respuesta. Debe guardarlos para cualquier solución de problemas en el futuro.
Si el archivo cargado tiene algunos problemas, como el formato no válido, las comillas que faltan, los espacios finales, el segmento que ya tiene 50000 definiciones de polígono etcetera., no habría ninguno geo_segment_polygon_id en la respuesta. Si la respuesta de carga solo apd_idcontiene , significa que el archivo se rechazó debido a cualquiera de los motivos mencionados anteriormente. En tales casos, se recomienda corregir el problema e intentar la carga de nuevo.
Actualmente no se admiten varios polígonos. Divida las definiciones de varios polígonos en definiciones únicas, individuales y de polígono y cargue solo esas.
Un segmento de polígono geográfico se puede conectar a un máximo de un centro regional.

Compartir a través de

Servicio segmento de polígono geográfico

Flujo de proceso

API de REST

Campos JSON

Creación de un nuevo json de segmento de polígono geográfico

`CSV` formato de archivo

Ejemplo

`add-polygons.csv`

Ejemplos

Creación de un nuevo segmento de polígono geográfico

Ver todos los centros regionales admitidos

Carga de polígonos en el segmento recién creado

Visualización de todos los segmentos de polígono geográfico de un miembro

Visualización de todas las definiciones de polígono geográfico en un segmento

Visualización de cargas recientes

Visualización del estado de una carga específica

Visualización del estado de carga de la carga del polígono geográfico

Eliminación de un segmento de polígono geográfico

Eliminación de una característica específica de un segmento de polígono geográfico

Comprobar el estado del trabajo

Puntos importantes a tener en cuenta

Recursos adicionales

Compartir a través de

Servicio segmento de polígono geográfico

Flujo de proceso

API de REST

Campos JSON

Creación de un nuevo json de segmento de polígono geográfico

CSV formato de archivo

Ejemplo

add-polygons.csv

Ejemplos

Creación de un nuevo segmento de polígono geográfico

Ver todos los centros regionales admitidos

Carga de polígonos en el segmento recién creado

Visualización de todos los segmentos de polígono geográfico de un miembro

Visualización de todas las definiciones de polígono geográfico en un segmento

Visualización de cargas recientes

Visualización del estado de una carga específica

Visualización del estado de carga de la carga del polígono geográfico

Eliminación de un segmento de polígono geográfico

Eliminación de una característica específica de un segmento de polígono geográfico

Comprobar el estado del trabajo

Puntos importantes a tener en cuenta

Recursos adicionales

`CSV` formato de archivo

`add-polygons.csv`