Geo Polygon Segment service

發行項
07/16/2024

Note

This service is in Alpha. This feature is subject to change without notice and is only available to select clients. If you would like to participate in the Alpha test, please contact your account manager.

The Geo Polygon Segment Service lets you create, configure, and export geo polygon segments. A geo polygon segment is a list of user locations specified by Well-known text (WKT) polygon coordinates. Well-known text (WKT) is a text markup language for representing vector geometry objects on a map using coordinates. After you create a geo polygon segment, you can use the segment automatically associated with it for geographical targeting of multiple user locations. The Geo Polygon Segment Service lets you to upload CSV files of geo polygon WKT into a geo segment. You can use the same geo segment for targeting at the line item level.

Warning

Geo Polygon Segment Service is based on Well-known text (WKT) polygon coordinates. This indicates that the geo polygons must be uploaded in longitude and latitude (long, lat) format instead of latitude and longitude (lat, long) format.

Process flow

To create a segment with geo polygons, follow below steps:

Create a shell segment. To create the shell segment, make a POST call to the /geo-polygon-segment endpoint.
Upload polygons to the shell segment. You can create a CSV file with polygons in it and make a POST call to the /geo-polygon-segment/{segmentID}/upload-polygon endpoint.
To verify if the upload was successful, check the job status through the /geo-segment-processor/job-status endpoint after submitting an upload request for the polygons.

REST API

HTTP Method	Endpoint	Description
`POST`	`https://api.appnexus.com/geo-polygon-segment` (new-geo-polygon-segment JSON)	Create a new geo polygon segment
`POST`	`https://api.appnexus.com/geo-polygon-segment/{segmentID}/upload-polygon` (add-polygons.csv)	Add polygons to a segment
`POST`	`https://api.appnexus.com/geo-polygon-segment` (new-geo-polygon-segment JSON)	Create a new geo polygon segment
`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"`	View all geo polygon segments for a member
`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"`	View a specific geo polygon segment's details
`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"`	View all geo polygon definitions in a segment
`GET`	`https://api.appnexus.com/apd-status`	View recent uploads
`GET`	`https://api.appnexus.com/apd-status?id=%7Bapd_id%7D`	View status of a specific upload
`GET`	`https://api.appnexus.com/geo-segment-processor/job-status`	View status of a geo polygon upload
`DELETE`	`https://api.appnexus.com/geo-polygon-segment/{segmentID}`	Delete a geo polygon segment
`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"`	Delete a specific feature from a geo polygon segment

JSON fields

Create new geo polygon segment JSON

Field	Type	Description
`code`	string	User-defined code for calling the geo polygon segment. For example, `"GEO123"`
`description`	string	Description for this geo polygon segment
`short_name`	string	Short name used to describe the geo polygon segment Required On: `POST`
`regional_centers`	array of objects	ID or code of the region in which the geo polygon segment is available. Possible values: - ID: 1, 2 or 3 - code: "americas", "emea", "apac"

`CSV` file format

The CSV file has the column names as Polygon and Name and they hold the values for the defined geo-polygons.

Note

Column names are case-sensitive and without any space. You must specify the column names in your CSV file.

Example

`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

Note

The polygons must be specified inside quote marks, as required by the CSV file standard.

Once you upload the CSV file successfully, the API sends response with below fields:

geo_segment_polygon_id: The auto-generated ID of the geo polygon as stored in Xandr's system.
name: The name of the geo-polygon.
apd_id: The job ID of the upload. You must keep track of this in case you want to track down the status of the upload.

Note

You need to keep record of the upload responses as it will be necessary for troubleshooting.

Examples

Create a new geo polygon segment

$ 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"
}

View all supported regional centers

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

Upload polygons to the newly created segment

Endpoint

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

Parameters

Field	Description
`segment_id` (in path)	The ID of the segment.

Example

Request

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

Body

A CSV file containing polygons.

Response

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

View all geo polygon segments for a member


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

View all geo polygon definitions in a segment


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

View recent uploads


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

View status of a specific upload


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

View upload status of geo polygon upload

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

Delete a geo polygon segment

Endpoint

DELETE /geo-polygon-segment/<segment_id>

Parameters

Field	Description
`segment_id` (in path)	The ID of the segment.

Example

Request

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

Response


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

Delete a specific feature from a geo polygon segment

Endpoint

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

Parameters

Field	Description
`segment_id` (in path)	The ID of the segment from which to delete a polygon.

Example

Request

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

Body

JSON


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

Response

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

Check job status

To check the status of any job, use the job_id provided in the response to make a request to the job status endpoint.

Endpoint

GET /geo-segment-processor/job-status

Parameters

Field	Description
`jobId`	The ID of the job.
`geoSegmentId`	The geo segment ID.
`segmentId`	The segment ID.
`numJobsToRetrieve`	Number of jobs to retrieve.

To monitor the progress of your upload or delete requests, you can query the status of a job using specific parameters.

Field	Type	Description
`job_state`	string	Indicates the current state of the overall job. The possible values of job states are as follows: - created - The job has been scheduled, but not yet run. active - A job related to the overall job is currently being processed. cancelled - The job has been cancelled either manually or due to an error. retry - The job may be retried once if some internal request has failed. completed - The job has completed successfully. expired - The job has not been picked up for processing after 12 hours, so it has expired and will not be processed. failed - An error occurred at some point, and the job failed. in-progress - The overall job is being processed, with sub-jobs being scheduled and processed to continuously check for the APD job to complete before the job queue job can complete.
`job_id`	number	The id of the overall job.
`workflow`	string	The workflow associated with the job. The following workflows are associated with the job. - 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`	number	The geo segment id associated with the request. Note: Typically, an internal id. Though this ID is used for geo radius related requests.
`segment_id`	string	The segment id associated with the request. Note: This ID is used for geo polygon related requests.
`job_results`	object	An object containing information about the job, updated once the job begins processing. `apdJobStatus` - Contains the current results of the APD job by the job ID. `apdJobIds` - Contains the job ID for each region. `initialJobRecordId` - The ID of the job. This should match the jobId parameter specified in this request. `jobCount` - The number of sub-jobs that make up the overall job. `jobErrors` - Contains any errors related to why the job failed, was canceled, or was retried.
`job_name`	string	Specifies the name of the job queue. There are two job types: - `apd status check` - `apd job complete`. It also indicates the environment from which the request originated (development, staging, or production). - `bff_apd_status_check_queue_<env>` - `bff_apd_job_complete_queue_<env>` Note: `<env>` can be `dev`, `staging`, or `prod`.
`created_on`	string	Date/time the job was created.
`num_records`	number	Number of polygons or features associated with the job. For example, if you just made a request to upload 500 polygons, num_records will be 500.

Response


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

Important points to note

The Geo Polygon Segment Service does not currently accept geo polygon definitions with holes (In geometry, a polygon with holes is an area-connected planar polygon with one external boundary and one or more interior boundaries). If a polygon definition contains a hole, the service will ignore the hole.
The maximum number of polygon definitions that can be hosted in a segment is 50,000.
When the uploading of the CSV file is successful, the service returns apd_id and geo_segment_polygon_id in response. You need to save them for any troubleshooting in future.
If uploaded file has some issues such as invalid formatting, missing quotes, trailing spaces, segment already having 50000 polygon definitions etc., then there would not be any geo_segment_polygon_id in the response. If the upload response contains only apd_id, that signifies that file was rejected due to any of the reasons mentioned above. In such cases, it is recommended to rectify the issue and attempt the upload again.
Multi-polygons are not supported currently. Please split multi-polygon definitions into unique, individual, polygon definitions and upload only those.
A geo polygon segment can be connected to a maximum of one regional centre.

共用方式為

Geo Polygon Segment service

Process flow

REST API

JSON fields

Create new geo polygon segment JSON

`CSV` file format

Example

`add-polygons.csv`

Examples

Create a new geo polygon segment

View all supported regional centers

Upload polygons to the newly created segment

View all geo polygon segments for a member

View all geo polygon definitions in a segment

View recent uploads

View status of a specific upload

View upload status of geo polygon upload

Delete a geo polygon segment

Delete a specific feature from a geo polygon segment

Check job status

Important points to note

其他資源

共用方式為

Geo Polygon Segment service

Process flow

REST API

JSON fields

Create new geo polygon segment JSON

CSV file format

Example

add-polygons.csv

Examples

Create a new geo polygon segment

View all supported regional centers

Upload polygons to the newly created segment

View all geo polygon segments for a member

View all geo polygon definitions in a segment

View recent uploads

View status of a specific upload

View upload status of geo polygon upload

Delete a geo polygon segment

Delete a specific feature from a geo polygon segment

Check job status

Important points to note

其他資源

`CSV` file format

`add-polygons.csv`