Site service

  • Article

A site (also called a placement group) provides a way of grouping placements for management purposes. Ad quality and inventory categorization can be set at the site level, so it doesn't have to be duplicated across placements. Each site belongs to a publisher, and each placement must belong to a site.

When you create a publisher, a site is automatically created. You can then modify that site however you wish or create more sites.

REST API

HTTP Method Endpoint Description
POST https://api.appnexus.com/site?publisher_id=PUBLISHER_ID
(site JSON)		 Add a site.
PUT https://api.appnexus.com/site?id=SITE_ID&publisher_id=PUBLISHER_ID

https://api.appnexus.com/site?id=SITE_ID
(site JSON)		 Modify an existing site.
DELETE https://api.appnexus.com/site?id=SITE_ID&publisher_id=PUBLISHER_ID

https://api.appnexus.com/site?code=SITE_CODE&publisher_code=PUBLISHER_CODE		 Delete a site.
GET https://api.appnexus.com/site View all sites for your publishers.
GET https://api.appnexus.com/site?publisher_id=PUBLISHER_ID View all of the sites for one of your publishers.
GET https://api.appnexus.com/site?id=SITE_ID&publisher_id=PUBLISHER_ID

https://api.appnexus.com/site?id=SITE_ID		 View a specific site for one of your publishers.
GET https://api.appnexus.com/site?id=1,2,3 View multiple sites by ID using a comma-separated list.

Note

publisher_code and code can be used interchangeably with publisher_id and id, respectively.

JSON fields

Field Type Description
id int Xandr ID assigned by the API to reference this site.

Required On: PUT, in query string
code string (100) Optional code for this site.
name string (100) Name associated with the site.

Required On: PUT, POST
state enum State of this site. Possible values: active or inactive.

Default: active
url string (255) URL of this site.
publisher_id int ID of the publisher that this site belongs to.

Required On: POST/PUT, in query string
primary_content_category_id int Users can optionally specify a primary content category for a placement (see examples below). This category can be used for targeting and will appear in reports. Content categories can be set either at the Site level or the Placement level, but not both.
last_modified timestamp The timestamp of last activity to this placement.
placements array of objects The IDs of placements associated with this site. See Placements below for more details.
content_categories array Users can optionally specify one or more content categories for a placement. These categories can be used for targeting, and can be set at both the Site and Placement level. At most 20 categories can be set on a site. See Content Categories below for more details.
intended_audience enum The intended audience of the site. Must not be null if 'audited' is true. Possible values:
- children
- young_adult
- general
- mature

Default: null
inventory_attributes array The sensitive attributes contained by the site; if set at the site level, inventory_attributes will also influence objects at the placement level. The mapping of IDs to attributes can be found below. The format of the array is also contained below.

Default: null
audited boolean Whether the site has been audited.
publisher_join array
publisher_name string (100) Name of the publisher the site is under
supply_type string Deprecated. While this field will continue to default to "web", its value is ignored as the supply type is detected automatically by Xandr in each auction. Users must rely on Xandr’s automatic detection rather than specifying the supply type manually.

Default: web
creative_format_action string - exclude: Allow all creative formats to serve on this site except those specified in the creative_formats array
- include: Only all creatives to serve whose format is included in the list specified in creative_formats

Default: exclude.
Some mobile application supply sources do not support all creative formats available on Xandr.
creative_formats array of strings The creative formats to be excluded or included in this site.

Default: text
allowed_click_actions array of strings Tells the buyer what types of click actions on creatives are supported. Mobile web and apps often allow additional click actions beyond click to a website, such as click-to-call, click-to-sms, click-to-email, and click-to-map.

Default: click-to-web only
marketplace_map object Informs the buyer which types of marketplaces are accessible (performance, RTB, deals). See Marketplace Map below for internal field definitions.
mobile_app_instance multi-object The Mobile App Instance associated with this site. This field can only be set when supply_type is mobile_app. See Mobile App Instance below for the internal field definitions.

Required On: POST, for sites with a supply_type of mobile_app.
mobile_app_instance_id int The ID of the mobile app instance associated with this site. This field is only associated with sites with a supply_type of mobile_app.

Marketplace map

Parameter Type Description
an_audit_perf_only Boolean Read-only. Whether the site is only eligible for CPA/CPC demand based on our auditing. If true, then yes.

Default: false
rtb Boolean Designates whether the inventory associated with the site (and all of its placements) is part of the RTB Marketplace (i.e., eligible for CPM demand).
- If true, all inventory associated with this site's placements is to be resold within the RTB Marketplace.
- The field cannot be set to true if any of the placements within the site support the expandable media type. See the Placement Service for more information about media types and subtypes fields.
- If false, expandable placements within the site cannot be moved to a site where the field is true.
- If set to false all inventory associated with this site's placements is only available to direct campaigns. No inventory associated with this placement group's placements will be resold.

Default: true
performance Boolean Whether the site is eligible for CPA/CPC demand using the updated performance marketplace. If true, then yes.

Default: false
deals_allowed Boolean Specifies whether deals are allowed to serve on this site.

Default: true
rtb_suspended Boolean Read-only. Indicates that all inventory associated with this site and its placements is blocked from participating in the RTB Marketplace.

Default: false
deals_suspended Boolean Read-only. Indicates that all deals are suspended from serving on this site.

Default: false

Mobile app instance

Parameter Type Description
id int The unique ID of this app instance. This field is optional on POST; if sent, it will be used to look up the bundle_id and os_family_id. If this field is not set on a PUT or POST, you must pass in the bundle_id and os_family_id fields, and a new mobile app instance ID will be created.
bundle_id int If no id field is passed on POST, this field is required. This field represents the bundle ID of the mobile app instance, and it's used to look up the mobile app instance ID. If there is no app instance ID associated with this bundle ID, a new one will be created.
os_family_id int If no id field is passed in on PUT or POST, this field is required. This field represents the unique ID of the operating system family this app instance is associated with. If there is no app instance ID associated with this OS family ID, a new one will be created.

Placements

Parameter Type Description
id int The unique identifier of the placement. You can use the Placement Service to find placement IDs.
code string The internal code for the placement.

Content categories

Parameter Type Description
id int ID of the content category. You can use the Content Category Service to find category IDs.
is_system Boolean Whether or not the content category is a system ("universal") category.
name string (100) The name of the category.
site array List of IDs which fall under this content category.
primary Boolean Whether the category is the primary category for the site. Only one category can be primary.

Inventory attributes

Parameter Type Description
inventory_attribute_id int The ID of the inventory attribute.
name string (50) Read-only. The name of the inventory attribute.

Inventory attributes ID

Id Attribute Name
2 Political
4 Social Media
6 Photo & video sharing
8 Forums (moderated)
10 Forums (unmoderated)
12 Incentivized clicks
14 Non-English languages
16 Streaming Media
17 Toolbars, plugins, or extensions

Examples

Adding content categories to a site

$ cat site

{
    "site": {
        "content_categories": [
            {
                "id": 2561,
                "primary": true
            },
            {
                "id": 2558
            }
        ],
        "name": "Site 1"
    }
}

$ curl -b cookies -c cookies -X PUT -d @site 'https://api.appnexus.com/site?id=5822'

Viewing all sites for your publishers

$ curl -b cookies -c cookies 'https://api.appnexus.com/site'

{
   "response":{
      "status":"OK",
      "sites":[
         {
            "id":2411,
            "code":null,
            "name":"[Default RTB Media Buy] - ROS",
            "state":"active",
            "url":"",
            "primary_content_category_id":null,
            "last_modified":"2010-05-12 22:46:42",
            "intended_audience":"general",
            "inventory_attributes":[
                {
                    "id":2,
                    "name":"Political"
                }
            ]
            "placements":[

            ],
            "content_categories": [
                {
                    "id": 2561,
                    "primary": true
                },
                {
                    "id": 2558
                }
            ],
         },
         {
            "id":2412,
            "code":null,
            "name":"[Weekdays Only] - ROS",
            "state":"active",
            "url":"",
            "media_buy_id":1559,
            "primary_content_category_id": 2561,
            "last_modified":"2010-05-12 23:28:40",
            "placements":[

            ],
            "content_categories":null
         },
         {
            "id":2413,
            "code":null,
            "name":"[Weekends Only] - ROS",
            "state":"active",
            "url":"",
            "media_buy_id":1560,
            "primary_content_category_id":null,
            "last_modified":"2010-05-12 23:28:52",
            "placements":[

            ],
            "content_categories":null
         },
         {
            "id":5775,
            "code":null,
            "name":"[Conversion Test] - ROS",
            "state":"active",
            "url":"",
            "media_buy_id":4732,
            "primary_content_category_id":null,
            "last_modified":"2010-06-15 20:09:38",
            "placements":[
               {
                  "id":"57851"
               }
            ],
            "content_categories":null
         }
      ],
      "count":4,
      "start_element":null,
      "num_elements":null
   }
}

Create a site with a mobile app supply type

In this example we create a site designed for mobile app supply. We'll use it in our next example as well:

$ cat the-site.json
 
{"site":{"name":"One site to rule them all", "supply_type":"mobile_app"}}
 
$ curl -b cookies -X POST -d @the-site.json 'https://api.appnexus.com/site?publisher_id=102306'
 
{
    "response":{,
         "site":{
            "allowed_click_actions":[
                "click-to-web"
            ],
             "creative_formats":[
                "text"
            ],
             "inventory_attributes":null,
             "content_categories":null,
             "placements":null,
             "mobile_app_instance":null,
             "member_id":1309,
             "creative_format_action":"exclude",
             "supply_type":"mobile_app",
             "publisher_name":"RICH'S CRAZY RESELLER",
             "audited":false,
             "intended_audience":null,
             "last_modified":"2014-02-20 20:56:03",
             "primary_content_category_id":null,
             "publisher_id":102306,
             "url":"",
             "state":"active",
             "name":"One site to rule them all",
             "code":null,
             "id":273205
        },
         "num_elements":100,
         "start_element":0,
         "id":273205,
         "count":1,
         "status":"OK"
    }
}

Add a mobile app instance to a site

In this example, we have a pre-existing site with the required mobile app supply type. We make a PUT call to associate our site with an existing mobile app instance, and we can see that it worked by viewing the updated object in the response. For more details on mobile app instances, see the Mobile App Instance Service.

$ cat update.json

{"site":{"supply_type":"mobile_app", "mobile_app_instance":{"id":62}}}
 
$ curl -b cookies -X PUT -d @update.json
 
{
    "response":{
        "site":{
            "allowed_click_actions":[
                "click-to-web"
            ],
            "creative_formats":[
                "text"
            ],
            "inventory_attributes":null,
            "content_categories":null,
            "placements":null,
            "mobile_app_instance":{
                "os_family_id":3,
                "bundle_id":"2342342345566666",
                "id":62
            },
            "member_id":1309,
            "creative_format_action":"exclude",
            "supply_type":"mobile_app",
            "publisher_name":"RICH'S CRAZY RESELLER",
            "audited":false,
            "intended_audience":null,
            "last_modified":"2014-02-20 21:18:15",
            "primary_content_category_id":null,
            "publisher_id":102306,
            "url":"",
            "state":"active",
            "name":"One site to rule them all",
            "code":null,
            "id":273205
        },
        "num_elements":100,
        "start_element":0,
        "id":"273205",
        "count":1,
        "status":"OK"
    }
}