Connection Targeting

This article describes resources that enable you to read and define connection targeting.

Overview

Oath Ad Platforms DSP mobile targeting enables you to target consumers based on their Internet connection type (Wi-Fi, Cellular, or both), Internet Service Providers (isps), or mobile carriers (mobileCarriers):

  • If you target Wi-Fi customers, you can also target consumers connected through particular ISPs.
  • If you target cellular users, you can also target consumers connected through particular mobile carriers.
  • If you target all connection types, you can target both ISPs and mobile carriers.

If you target both ISPs and mobile carriers, the platform targets consumers who are connected through either the ISPs or the mobile carriers specified.

The Oath Ad Platforms DSP supports CONNECTION targeting for lines serving display and video ads.

Mobile & Location Targeting Rules

The mobile carriers and ISP available for targeting depend on locations targeted. You must specify GEOGRAPHIC targeting before you can target ISPs or carriers.

The Oath Ad Platforms DSP enables you to target countries, states, cities, or designated marketing areas (DMAs). To learn more, see Geography Targeting.

  • If GEOGRAPHY-based targeting (geo or geoFencing) is expanded and CONNECTION-based targeting is not updated, CONNECTION-based targeting is unchanged.
  • If GEOGRAPHY-based targeting (geo or geoFencing) is narrowed, the platform validates the existing CONNECTION-based targeting paramerers. If valid, CONNECTION-based targeting is unchanged. If invalid, no change is made, but an error is returned.
  • If GEOGRAPHY-based targeting is changed from geo to geoFencing or vice versa, the platform validates the existing CONNECTION-based targeting paramerers. If valid, CONNECTION-based targeting is unchanged. If invalid, no change is made, but an error is returned.
  • If GEOGRAPHY-based targeting is disabled, CONNECTION targeting is disabled as well.

Endpoint

/traffic/lines/{id}/targeting
  • A GET request enables you to view connections targeted by the specified line.
  • A POST request enables you to target connections with the specified line.

Resources

The targeting resource is the standard Oath Ad Platforms DSP resource for targeting consumers based on their profiles, behaviors, and ad content.

This resource comprises multiple fields that enable you to specify line targeting across many types of targets including the SEGMENT, EXCHANGES, and CONNECTION target types.

The targeting resource is defined by the following CONNECTION targeting type-specific fields:

Note

Connection targeting parameters can only be specified if CONNECTION targeting is enabled.

Field Description Data Type
id Specifies the line ID. integer
mobileCarriers

Specifies the mobile carriers to target.

Note: To target a mobile carrier, you need only specify the id field only.

array
isps

Specifies an array of ISPs to target. All available ISPs can be specified using ["ALL"].

To get a list of available ISPs by country or geo-fencing address, see read-isps-country.

array

Note

For a complete list of targeting resource fields, see Targeting Object.

Read Mobile Carrier Targets

Returns a filtered list of mobile carriers available for targeting.

POST /traffic/targeting/carriers

Parameters

The resource takes the following parameters:

Parameter Parameter Type Description Data Type Required?
countries body Specifies an array of ISO 3166 country codes. If not specified, defaults to usa. array Y
locations body Specifies an array of geofencing addresses. array N

Example Request

{
  "countries": ["isl"],
  "locations": []
}

Example Response

The response returns a list of matching carriers.

{
  "response": [
    {
      "id": "5",
      "name": "Voxbone"
    },
    {
      "id": "371",
      "name": "Nova"
    },
    {
      "id": "372",
      "name": "Siminn"
    }
  ],
  "errors": null,
  "timeStamp": "2018-01-10T21:30:42Z"
}

Read ISPs by Country

Returns a list of ISPs available in the specified countries or geofencing addresses.

Parameters

All parameters are specified in the body of the application/json payload.

Table 138 Read ISPS
Parameter Parameter Type Description Data Type Required?
countries body Specifies an array of ISO 3166 country codes. If not specified, defaults to usa. array Y
locations body Specifies one or more locations identified by geofencing address strings. array N

Example Requests

To filter ISPs by country, specify one or more ISO 3166 country codes:

{
  "countries": [
    "isl"
  ],
  "locations": []
}

To filter ISPs by geofencing location, specify one or more location string:

{
  "countries": [],
  "locations": ["2 Waters Park Dr, San Mateo, CA 94403", "One Infinite Loop, Cupertino, CA 95014"]
}

Example Response

{
    "response": [
        {
            "id": "124",
            "name": "Bell Canada"
        },
        {
            "id": "193",
            "name": "Orange"
        },
        {
            "id": "181",
            "name": "Mediacom"
        },
        {
            "id": "228",
            "name": "The Planet"
        }
    ],
    "errors": null,
    "timeStamp": "2018-01-12T01:07:13Z"
}

Read Mobile Carriers by Country

Returns a list of mobile carriers available in the specified countries or geofencing addresses.

Parameters

All parameters are specified in the body of the application/json payload.

Table 139 Read Mobile Carriers
Parameter Parameter Type Description Data Type Required?
countries body Specifies an array of ISO 3166 country codes. If not specified, defaults to usa. array Y
locations body Specifies one or more locations identified by geofencing address strings. array N

Example Requests

To filter mobile carriers by country, specify one or more ISO 3166 country codes:

{
  "countries": [
    "usa",
    "ind"
  ],
  "locations": []
}

To filter mobile carriers by geofencing location, specify one or more location string:

{
  "countries": [],
  "locations": ["2 Waters Park Dr, San Mateo, CA 94403", "One Infinite Loop, Cupertino, CA 95014"]
}

Example Response

{
  "response": [
    {
      "id": "525",
      "name": "Inland Cellular Telephone Company"
    },
    {
      "id": "358",
      "name": "Jio"
    },
    {
      "id": "2",
      "name": "Verizon"
    },
    {
      "id": "518",
      "name": "Carolina West Wireless"
    }
  ],
  "errors": null,
  "timeStamp": "2018-01-03T02:50:44Z"
}

Add/Update Connection Targets

Adds or updates connection targets for the specified line. Consumers may be targeted based on their ISPs or mobile carriers.

POST /traffic/lines/{id}/targeting

The CONNECTION targeting type must be enabled in the body of the application/json payload.

Parameters

The line ID is specified in the path of the URL. All other parameters are specified in the body of the application/json payload.

Parameter Parameter Type Description Data Type Required?
id path Specifies the line ID. integer Y
mobileCarriers body

Specifies an array of mobile carrier IDs to target. All available mobile carriers can be specified using ["ALL"].

To get a list of available mobile carriers by country or geo-fencing address, see Read Mobile Carriers by Country.

Note: Only valid if the types object enables CONNECTION targeting.

array Y
isps body

Specifies an array of ISPs to target. All available ISPs can be specified using ["ALL"].

To get a list of available ISPs by country or geo-fencing address, see read-isps-country.

Note: Only valid if the types object enables CONNECTION targeting.

array Y
types body

Specifies an array of targeting types to update, enable, or disable.

To target connections, the CONNECTION targeting type must be enabled.

To learn more, see Targeting Types.

object Y

Example Request

The line ID is specified in the path of the resource endpoint:

POST traffic/lines/365277/targeting/

All other parameters are specified in the body of the application/json payload. The line targets mobile carriers 1 and 532 and all ISPs.

{
  "mobileCarriers": [1,532],
  "isps": ["ALL"],
  "types": [
    {
      "name": "CONNECTION",
      "isTargeted": true
    }
  ]
}

Example Response

{
  "response": {
      "types": [
          {
            "name": "CONNECTION",
            "id": 16,
            "isTargeted": true
          }
      ],
      "mobileCarriers":[
        "AT&T"
      ],
      "geosIncluded": [
          {
              "id": "####usa",
              "name": "United States",
              "description": "united states of america/usa",
              "level": "Country",
              "key": "usa",
              "excluded": false
          }
      ],
      "geosExcluded": [],
      "frequencyCapValue": 0,
      "serveUnknownUser": true
  },
  "errors": null,
  "timeStamp": "2017-12-29T21:59:10Z"
}

Status and Error Codes

Field Description
200 Error converting response
400 Payload is missing.
422 Required field [mobileCarriers] is missing.
422 Required field [isps] is missing.
422 Connection targeting and Geo targeting are not compatible
400 Field types has invalid value.

See also

About Targeting