CData Python Connector for Google Ad Manager

Build 24.0.9060

LineItems

Create, update, delete, and query DoubleClick for Publishers Line Items.

Select

The following queries are processed server side by the Google Ad Manager APIs.

Retrieve a list of LineItems. For example:

SELECT * FROM [LineItems]

Additionally, you can specify the Id or filter by any other column.

SELECT * FROM [LineItems] WHERE Id = '4377540922'

Insert

To create a new LineItem, the following fields are required: OrderId, Name, LineItemType, CurrencyCode, MicroAmount, CostType, CreativePlaceholdersAggregate, GoalType, GoalUnits, and InventoryTargetingAggregate. Note that other columns could be required depending on data chosen for certain columns.

INSERT INTO [LineItems] (OrderId, Name, StartDateTimeType, EndDateTime, EndTimeZoneId, CreativeRotationType, LineItemType, CurrencyCode, MicroAmount, CostType, CreativePlaceholdersAggregate, AllowOverbook, GoalType, GoalUnitType, GoalUnits, GeoTargetingAggregate, InventoryTargetingAggregate) VALUES ('2108997295', 'line item 233', 'IMMEDIATELY', '2017-09-01', 'America/New_York', 'EVEN', 'STANDARD', 'USD', '200000', 'CPM', '<size><width>1</width><height>1</height><isAspectRatio>false</isAspectRatio></size><creativeTemplateId>10004520</creativeTemplateId><expectedCreativeCount>1</expectedCreativeCount><creativeSizeType>NATIVE</creativeSizeType>', 'true', 'LIFETIME', 'IMPRESSIONS', '500000', '<geoTargeting><targetedLocations><id>2840</id><type>COUNTRY</type><displayName>United States</displayName></targetedLocations><targetedLocations><id>20123</id><type>PROVINCE</type><canonicalParentId>2124</canonicalParentId><displayName>Quebec</displayName></targetedLocations><excludedLocations><id>1016367</id><type>CITY</type><canonicalParentId>21147</canonicalParentId><displayName>Chicago</displayName></excludedLocations><excludedLocations><id>200501</id><type>DMA_REGION</type><canonicalParentId>2840</canonicalParentId><displayName>New York NY</displayName></excludedLocations></geoTargeting>', '<inventoryTargeting><targetedPlacementIds>28544791</targetedPlacementIds></inventoryTargeting>')

Update

You can update any field not marked as read-only by specifying the Id column.

UPDATE [LineItems] SET DeliveryRateType = 'EVENLY' WHERE Id = '4377540922'

Delete

You can delete a LineItem row by specifying the Id column.

DELETE FROM [LineItems] WHERE Id = '4377865094'

Columns

Name Type ReadOnly Description
OrderId Long False

The ID of the Order to which the LineItem belongs. This attribute is required.

Id [KEY] Long True

Uniquely identifies the LineItem. This attribute is read-only and is assigned by Google when a line item is created.

Name String False

The name of the line item. This attribute is required and has a maximum length of 255 characters.

ExternalId String False

An identifier for the LineItem that is meaningful to the publisher. This attribute is optional and has a maximum length of 255 characters.

OrderName String True

The name of the Order. This value is read-only.

StartDateTime Datetime False

The date and time on which the LineItem is enabled to begin serving. This attribute is required unless LineItem.StartDateTimeType is set to IMMEDIATELY or ONE_HOUR_FROM_NOW.

StartTimeZoneId String False

The start date time timezone id of the LineItem. The timezone ID must be in tz database format (e.g. America/Los_Angeles).

StartDateTimeType String False

Specifies whether to start serving to the LineItem right away, in an hour, etc. This attribute is optional and defaults to StartDateTimeType.USE_START_DATE_TIME.

EndDateTime Datetime False

The date and time on which the LineItem will stop serving. This attribute is required unless LineItem.unlimitedEndDateTime is set to true. If specified, it must be after the LineItem.startDateTime. This end date and time does not include auto extension days.

EndTimeZoneId String False

The end date time timezone id of the LineItem. The timezone ID must be in tz database format (e.g. America/Los_Angeles).

AutoExtensionDays Int False

The number of days to allow a line item to deliver past its endDateTime. A maximum of 7 days is allowed. This feature is only available for Ad Manager 360 accounts.

UnlimitedEndDateTime Bool False

Specifies whether or not the LineItem has an end time. This attribute is optional and defaults to false. It can be be set to true for only line items of type LineItemType.SPONSORSHIP, LineItemType.NETWORK, LineItemType.PRICE_PRIORITY and LineItemType.HOUSE.

CreativeRotationType String False

The strategy used for displaying multiple Creative objects that are associated with the LineItem. This attribute is required.

DeliveryRateType String False

The strategy for delivering ads over the course of the line item's duration. This attribute is optional and defaults to DeliveryRateType.EVENLY or DeliveryRateType.FRONTLOADED depending on the network's configuration.

DeliveryForecastSource String False

Strategy for choosing forecasted traffic shapes to pace line items. This field is optional and defaults to DeliveryForecastSource.HISTORICAL.

CustomPacingCurve String False

The curve that is used to pace the line item's delivery. This field is required if and only if the delivery forecast source is DeliveryForecastSource.CUSTOM_PACING_CURVE.

RoadblockingType String False

The strategy for serving roadblocked creatives, i.e. instances where multiple creatives must be served together on a single web page. This attribute is optional and defaults to RoadblockingType.ONE_OR_MORE.

SkippableAdType String False

The nature of the line item's creatives' skippability. This attribute is optional, only applicable for video line items, and defaults to SkippableAdType.NOT_SKIPPABLE.

FrequencyCaps String False

The set of frequency capping units for this LineItem. This attribute is optional.

LineItemType String False

Indicates the line item type of a LineItem. This attribute is required. The line item type determines the default priority of the line item. More information can be found on the Ad Manager Help Center.

Priority Int False

The priority for the line item. Valid values range from 1 to 16. This field is optional and defaults to the default priority of the LineItemType. Each line item type has a default, minimum, and maximum priority value. This field can only be edited by certain networks, otherwise a PermissionError will occur.

CurrencyCode String False

Three letter currency code in string format.

MicroAmount Long False

Money values are always specified in terms of micros which are a millionth of the fundamental currency unit. For US dollars, $1 is 1,000,000 micros.

ValueCostPerUnit String False

An amount to help the adserver rank inventory. LineItem.valueCostPerUnit artificially raises the value of inventory over the LineItem.costPerUnit but avoids raising the actual LineItem.costPerUnit. This attribute is optional and defaults to a Money object in the local currency with Money.microAmount 0.

CostType String False

The method used for billing this LineItem. This attribute is required.

DiscountType String False

The type of discount being applied to a LineItem, either percentage based or absolute. This attribute is optional and defaults to LineItemDiscountType.PERCENTAGE.

Discount Double True

The number here is either a percentage or an absolute value depending on the LineItemDiscountType. If the LineItemDiscountType is LineItemDiscountType.PERCENTAGE, then only non-fractional values are supported.

ContractedUnitsBought Long True

This attribute is only applicable for certain line item types and acts as an 'FYI' or note, which does not impact adserving or other backend systems. For LineItemType.SPONSORSHIP line items, this represents the minimum quantity, which is a lifetime impression volume goal for reporting purposes only. For LineItemType.STANDARD line items, this represent the contracted quantity, which is the number of units specified in the contract the advertiser has bought for this LineItem. This field is just a 'FYI' for traffickers to manually intervene with the LineItem when needed. This attribute is only available for LineItemType.STANDARD line items if you have this feature enabled on your network.

CreativePlaceholdersAggregate String False

Details about the creatives that are expected to serve through this LineItem. This attribute is required and replaces the creativeSizes attribute.

ActivityAssociations String False

This attribute is required and meaningful only if the LineItem.costType is CostType.CPA.

EnvironmentType String False

The environment that the LineItem is targeting. The default value is EnvironmentType.BROWSER. If this value is EnvironmentType.VIDEO_PLAYER, then this line item can only target AdUnits that have AdUnitSizes whose environmentType is also VIDEO_PLAYER.

AllowedFormats String False

The set of allowedFormats that this programmatic line item can have. If the set is empty, this line item allows all formats.

CompanionDeliveryOption String False

The delivery option for companions. Setting this field is only meaningful if the following conditions are met: the Guaranteed roadblocks feature is enabled on your network, and environmentType is EnvironmentType.VIDEO_PLAYER or roadblockingType is RoadblockingType.CREATIVE_SET. This field is optional and defaults to CompanionDeliveryOption.OPTIONAL if the conditions are met. In all other cases it defaults to CompanionDeliveryOption.UNKNOWN and is not meaningful.

AllowOverbook Bool False

The flag indicates whether overbooking should be allowed when creating or updating reservations of line item types LineItemType.SPONSORSHIP and LineItemType.STANDARD. When true, operations on this line item will never trigger a ForecastError, which corresponds to an overbook warning in the UI. The default value is false. Note: this field will not persist on the line item itself, and the value will only affect the current request.

SkipInventoryCheck Bool False

The flag indicates whether the inventory check should be skipped when creating or updating a line item. The default value is false. Note: this field will not persist on the line item itself, and the value will only affect the current request.

SkipCrossSellingRuleWarningChecks Bool False

True to skip checks for warnings from rules applied to line items targeting inventory shared by a distributor partner for cross selling when performing an action on this line item. The default is false.

ReserveAtCreation Bool False

The flag indicates whether inventory should be reserved when creating a line item of types LineItemType.SPONSORSHIP and LineItemType.STANDARD in an unapproved Order. The default value is false.

Stats String True

Contains trafficking statistics for the line item. This attribute is readonly and is populated by Google. This will be null in case there are no statistics for a line item yet.

DeliveryIndicator String True

Indicates how well the line item has been performing. This attribute is readonly and is populated by Google. This will be null if the delivery indicator information is not available due to one of the following reasons: The line item is not delivering, has an unlimited goal or cap or has a percentage based goal or cap.

DeliveryData String True

Delivery data provides the number of clicks or impressions delivered for a LineItem in the last 7 days. This attribute is readonly and is populated by Google. This will be null if the delivery data cannot be computed due to one of the following reasons: The line item is not deliverable, has completed delivering more than 7 days ago or has an absolute-based goal.

Budget String True

The amount of money allocated to the LineItem. This attribute is readonly and is populated by Google. The currency code is readonly.

Status String True

The status of the LineItem. This attribute is readonly.

ReservationStatus String True

Describes whether or not inventory has been reserved for the LineItem. This attribute is readonly and is assigned by Google.

IsArchived Bool True

The archival status of the LineItem. This attribute is readonly.

WebPropertyCode String False

The web property code used for dynamic allocation line items. This web property is only required with line item types LineItemType.AD_EXCHANGE and LineItemType.ADSENSE.

AppliedLabels String False

The set of labels applied directly to this line item.

EffectiveAppliedLabels String True

Contains the set of labels inherited from the order that contains this line item and the advertiser that owns the order. If a label has been negated, only the negated label is returned. This field is readonly and is assigned by Google.

DisableSameAdvertiserCompetitiveExclusion Bool False

If a line item has a series of competitive exclusions on it, it could be blocked from serving with line items from the same advertiser. Setting this to true will allow line items from the same advertiser to serve regardless of the other competitive exclusion labels being applied.

LastModifiedByApp String True

The application that last modified this line item. This attribute is read only and is assigned by Google.

Notes String False

Provides any additional notes that may annotate the LineItem. This attribute is optional and has a maximum length of 65,535 characters.

CompetitiveConstraintScope String False

The CompetitiveConstraintScope for the competitive exclusion labels assigned to this line item. This field is optional, defaults to CompetitiveConstraintScope.POD, and only applies to video line items.

LastModifiedDateTime Datetime True

The date and time this line item was last modified.

CreationDateTime Datetime True

This attribute may be null for line items created before this feature was introduced.

IsMissingCreatives Bool True

Indicates if a LineItem is missing any creatives for the creativePlaceholders specified. Creatives can be considered missing for several reasons including: Not enough creatives of a certain size have been uploaded or The Creative.appliedLabels of an associated Creative do not match the CreativePlaceholder.effectiveAppliedLabels of the LineItem.

ProgrammaticCreativeSource String False

Indicates the ProgrammaticCreativeSource of the programmatic line item. This is a read-only field. Any changes must be made on the ProposalLineItem.

ThirdPartyMeasurementSettings String False

YoutubeKidsRestricted Bool False

Designates this line item as intended for YT Kids app. If true, all creatives associated with this line item must be reviewed and approved. See the Ad Manager Help Center for more information.

VideoMaxDuration Long True

The max duration of a video creative associated with this LineItem in milliseconds. This attribute is only meaningful for video line items. For version v202011 and earlier, this attribute is optional and defaults to 0. For version v202102 and later, this attribute is required for video line items and must be greater than 0.

GoalType String False

The type of the goal for the LineItem. It defines the period over which the goal for LineItem should be reached.

GoalUnitType String False

The type of the goal unit for the LineItem.

GoalUnits Int False

If this is a primary goal, it represents the number or percentage of impressions or clicks that will be reserved for the LineItem.

SecondaryGoals String False

The secondary goals that this LineItem is associated with. It is required and meaningful only if the LineItem.costType is CostType.CPA or if the LineItem.lineItemType is LineItemType.SPONSORSHIP and LineItem.costType is CostType.CPM.

GrpSettings String False

Contains the information for a line item which has a target GRP demographic.

DealInfo String False

The deal information associated with this line item, if it is programmatic.

ViewabilityProviderCompanyIds String False

Optional IDs of the Company that provide ad verification for this line item. Company.Type.VIEWABILITY_PROVIDER.

ChildContentEligibility String True

Child content eligibility designation for this line item. This field is optional and defaults to ChildContentEligibility.DISALLOWED.

CustomVastExtension String True

Custom XML to be rendered in a custom VAST response at serving time.

GeoTargetingAggregate String False

Specifies what geographical locations are targeted by the LineItem. This attribute is optional.

InventoryTargetingAggregate String False

Specifies what inventory is targeted by the LineItem. This attribute is required. The line item must target at least one ad unit or placement.

CustomTargetingAggregate String False

Specifies the collection of custom criteria that is targeted by the LineItem.

CreativeTargetings String False

A list of CreativeTargeting objects that can be used to specify creative level targeting for this line item. Creative level targeting is specified in a creative placeholder's CreativePlaceholder.targetingName field by referencing the creative targeting's name. It also needs to be re-specified in the LineItemCreativeAssociation.targetingName field when associating a line item with a creative that fits into that placeholder.

CustomFieldName String True

This is the name of the custom field. There will be as many custom columns as custom fields are related to LineItems.

Copyright (c) 2024 CData Software, Inc. - All rights reserved.
Build 24.0.9060