Placement

Abstract

Placement objects have a unique code that is required as the key to retrieve ads from the Native Marketplace. Placements are also sometimes referred to as simply ads.

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/rest/placement

Fields

The Placement API contains the following fields:

Name

Description

Type

Add

Update

id

The ID of the placement to retrieve.

long

N/A

Required

status

The status of the placement. Valid input values are: ACTIVE, DELETED.

enum

Required

Optional

siteId

The site Id of the placement.

long

Required

Optional

language

The language of the placement.

enum

Required

Optional

publisherId

The publisher Id of the placement.

enum

Optional

Optional

placementCode

The placementCode of the placement. The system generates a code when not provided.

string

N/A

N/A

name

The name of the placement.

string

Required

Optional

maxAds

The number of ads requested for the placement; the default value is 1. Value sent in the server-to-server ad call will override this value.

long

Optional

Optional

multipaneTemplates

The template(s) can be used for the placement. It can be one or more values. You can get the list of available templates for a particular publisher by calling /multipanepresentationtemplate?publisherId={pubId}.

long[]

Optional

Optional

templateUrl

Template URL required for the website and some apps.

string

Optional

Optional

xpath

XPATH is required for websites.

string

Optional

Optional

policyGroup

The policyGroup associated with this placement. If not provided, it defaults to OATH_NATIVE. You can get a list of tiers by calling list of tiers associated with this publisher /placement/tiers?publisherId={pubId}.

string

Optional

Optional

sourceType

The external Source Type. Can be one of SYNDICATION, RECOMMENDS, FLURRY, SSP.

enum

Required

Optional

sourceId

External source Id. The ID that belongs in the external system for book keeping purposes.

long

Optional

Optional

startPosition

The starting position of the first ad within a stream.

skip

The number of items between each ad within a stream.

imageWidth

Width override on the image property of the ad.

imageHeight

Height override on the image property of the ad.

adType

Supported ad types include static, video, portrait, carousel.

Operations

Create a New Placement

Method: To create one or more placement, make a POST call to the Placement endpoint with the required fields. Batch create is supported; either a placement or a placement array can be passed. The response will be the newly created placement, or a list of multiple new placements if an array is passed.

Example: Create a placement:

POST https://api.gemini.yahoo.com/v3/rest/placement

Data passed
[
  {
             "status": "ACTIVE",
             "policyGroup": "APPLE_NATIVE",
             "siteId": 153540,
             "publisherId": 1534310,
             "language": "en_US",
             "name": "IF"
  }
]

Example response

  {
    "errors": null,
    "dataObject": [{
      "id": 5605348,
      "status": "ACTIVE",
      "createdDate": 1561425064919,
      "policyGroup": "APPLE_NATIVE",
      "publisherId": 1534310,
      "lastUpdatedByUser": "edwardsu",
      "lastUpdated": 1561425064989,
      "siteId": 153540,
      "placementCode": "11796734-1837-IF",
      "language": "en_US",
      "createdByUser": "edwardsu",
      "name": "IF"
    }]
  }

Update an Existing Placement

Method: To update one or more existing placements, make a PUT call to the placement endpoint with one or more placement objects. Specify the fields to update; please note that id is the only required parameter, all other fields are optional. The result will be the list of updated placements. Partial update is supported; fields that are either not passed or passed as null will be ignored for the update.

Example: Update placement with ID=5605348

PUT https://api.gemini.yahoo.com/v3/rest/placement

Data passed
{
 "id": 5605348,
 "name": "IF"
}

Example response
 {
      "errors": null,
      "dataObject": {
      "status": "ACTIVE",
      "placementCode": "11796734-1837-IF",
      "id": 5605348,
      "lastUpdatedByUser": "edwardsu",
      "createdByUser": "edwardsu",
      "createdDate": 1561425064919,
      "language": "en_US",
      "lastUpdated": 1561425192988,
      "siteId": 153540,
      "publisherId": 1534310,
      "maxAds": 1,
      "name": "IF"
      }
}

Read Specific Placement Data

Method: To retrieve data for a specific placement, make a GET call with the ID parameter.

For example: GET call to retrieve a placement with ID=5605348

GET https://api.gemini.yahoo.com/v3/rest/placement/5605348

Response:
 {
      "status": "ACTIVE",
      "policyGroup": "APPLE_NATIVE",
      "placementCode": "11796734-1837-IF",
      "id": 5605348,
      "lastUpdatedByUser": "edwardsu",
      "createdByUser": "edwardsu",
      "createdDate": 1561425064919,
      "language": "en_US",
      "lastUpdated": 1561425192988,
      "siteId": 153540,
      "publisherId": 1534310,
      "maxAds": 1,
      "name": "IF"
      }

Response: The placement associated with the given ID.

Read Data for a Filtered list of placement

Method: To retrieve data for a filtered list of sites, make a GET call using the following parameters:

Name

Description

Type

publisherId

The ID of the publisher to filter sites by. One will be accepted.

long

mr

The maximum number of rows to retrieve.

int

si

The start index or the first element to retrieve.

int

status

The status of the placement to filter by.

enum

name

The name of the placement.

string

siteId

The siteId of the placement.

long

Example: Retrieve all the placements under the publisher account ID 1534310 and limit the maximum number of rows to 2.

GET https://api.gemini.yahoo.com/v3/rest/placement/publisherId=1534310&mr=2

Response:

[
  {
      "status": "ACTIVE",
      "createdByUser": "edwardsu",
      "lastUpdatedByUser": "edwardsu",
      "lastUpdated": 1561425192988,
      "siteId": 153540,
      "placementCode": "11796734-1837-IF",
      "createdDate": 1561425064919,
      "publisherId": 1534310,
      "language": "en_US",
      "id": 5605348,
      "maxAds": 1,
      "policyGroup": "APPLE_NATIVE",
      "name": "IF"
  },
  {
      "status": "ACTIVE",
      "createdByUser": "flurry_ffa",
      "lastUpdatedByUser": "flurry_ffa",
      "lastUpdated": 1561382092069,
      "siteId": 153540,
      "placementCode": "02323-1233-IA",
      "createdDate": 1561382091971,
      "publisherId": 1534310,
      "language": "en_US",
      "id": 5605341,
      "maxAds": 1,
      "policyGroup": "APPLE_NATIVE",
      "name": "IA"
  }
]