APT from Yahoo!'s open platform helps simplify the process of buying and selling ads and inventory online for advertisers, publishers, ad networks, and agencies of all sizes. Web Services provides programmatic access to buy and sell publishers' inventory and advertisers' ads on the Exchange.
Accounts for members of the Exchange (such as self-managed advertisers, self-managed publishers, and networks) cannot be created using the API.
All Web Services requests must be sent to the URL that identifies the colocation for the account (on whose behalf the operation is performed) with the current Web Services version and the name of the service (such as SiteService). To retrieve the account colocation URL, use the LocationService getAccountLocation operation.
We recommend that you make regular queries to LocationService, typically at the start of each session or whenever you switch accounts. If a colocation is offline for maintenance or otherwise unavailable, your account data will still be available at one or more alternate locations.
Your Web Services license specifies the command groups you have access to and the quota you have been granted. A command group is a set of one or more operations. Quota is the total number of requests you can make in a 24-hour period using any of the operations in a command group. To determine the usage of quota, use the LicenseService getQuotaUsage operation.
- Create and manage folders for ads, creatives, and templates in the respective library.
- Add and manage creatives (image, Flash, customizable Flash, and video files) in the creative library.
- Add and manage ads in the ad library. You can add standard graphical ads, video ads (clickable video ads, bumper video ads, click-to-site overlay video ads, click-to-video overlay video ads, and interactive four stage video ads), simple Flash ads and customizable Flash ads, HTML-based ads, and third-party supported ads.
- For customizable Flash ads, upload the customizable SWF files (CSWF) and define the Flash variables, add the customizable Flash templates (based on the CSWF files), and generate the customizable Flash ads using the templates. The customizable Flash template allows you to create customizable Flash ads with similar look and feel by replacing image and text components.
- For video ads, get the upload token and URL for uploading the video creative, upload the video creative using HTTP POST to the URL, add the video creative to the creative library using the token, and then generate the clickable, bumper, interactive four stage, or (click-to-site and/or click-to-video) overlay video ads. Please note that the upload URL will only accept multi-part requests.
Note: When you upload a video file to the creative library, encoding starts as soon as uploading is done. Encoding may take a while depending on the quality and duration of your video file. Because of this, it's best to upload the files to the creative library before you start building ads. You can upload during ad creation, but you will have to wait for encoding to finish before you can use the video file to create an ad.
- Create and manage a network template with some predefined values. Templates cover a wide range of ads including many ad sizes, ad formats, and ad behaviors.
- Assign ads (in the ad library) to placements and define the ad flight dates, content and audience targeting attributes, and preferred buying type (including price settings) in the placement. Placements contain ads that share common content and audience targeting preferences. When you assign an ad to a placement, the ads undergo a thorough editorial review and editorial tags are set on ads and/or URLs if there is a problem with the ads and/or URLs.
Tip: Use the operations in AdService to manage ads assigned to placements.
- Add comments to ads in the ad library.
Inventory is the collection of ad space and audience that publishers offer for sale over a specified period of time. You can:
- Add and manage sites.
- Create and manage custom sections, custom content categories, referral segments, custom geographical areas (based on ZIP codes or postal codes), custom ad delivery modes, custom data (names and values), and ad markers. You can also create and manage custom audience segment categories.
- Create and manage palettes that define the (background, border, title, URL, and description) colors for the text ads displayed on your inventory.
- Create and manage inventory identifiers (that contain a core group of preferences saved as ad call presets), reporting tags (to track inventory performance), and ad tags (that specify the types of ads to display) for your inventory. Create and manage inventory forecast adjustments to adjust (increase or decrease) your site's available amount of impressions for a non-forecasted change in the available inventory.
- Create and manage rate cards (that define floor, target, and list prices for your inventory based on different sets of targeting attributes), rate tags (that define different rates on the same inventory for different partners), booking limits (that define the total percentage of bookable inventory), inventory opt-ins (that defines the attributes to restrict the inventory availability for booking), and inventory holdbacks (that allows you to reserve or hold back a certain percentage or absolute number of impressions of opted-in inventory for a certain date range).
- Create and manage audience sharing rules to use (target) your own custom segments and geographical areas on your partner's inventory, targeting rules to control the targeting options a buyer has available when booking orders, inventory contribution rules to identify a subset of inventory and opt that inventory group from contributing to certain types of inventory booking, and inventory selling rules (for preferred (internal) and standard (external) sales) for the sales teams.
- Create and manage inventory packages (to allow inventory and audience to be booked as a single unit) and inventory package placements (that define the ad, content, and audience targeting attributes for the inventory package).
Set up filters (to protect customers) and workflows (to ensure that order processes adhere to company guidelines). You can:
- Set up universal filters that apply to all customers and conditional filters that apply to only specified customers. Filters contain criteria for protecting advertisers from serving their ads to undesirable sites and publishers from displaying inappropriate or unwanted ads.
- Create (in-network and/or cross-network) approval workflows to ensure that the processing of ad placements and orders adhere to your company guidelines, and allow approval requests for ad placements and orders that do not strictly follow the guidelines. Approval workflows define the trigger and approvers for an approval request. When an approval request is created (as a result of an approval workflow trigger), a corresponding approval task is created and assigned (to one or more approvers) for the approval request. The approver(s) can evaluate the approval and take action (approve or deny) on the approval request.
- Create and manage pixels to track conversions. The pixel code on the advertiser's website can be used to track user action that the advertiser considers a conversion.
Create business relationships with other members to buy and sell inventory on the Exchange. Create profiles to help advertisers, publishers, and networks understand what kinds of inventory is available to buy and sell on the Exchange. Advertisers, publishers, and networks can:
- Create and manage profiles on the exchange.
- Propose and accept/reject links and (guaranteed and/or non-guaranteed) deals for buying and selling inventory.
The services that allow you to define targeting preferences accept one or more of these targeting attribute types. To retrieve the IDs and values of these targeting attributes, use the operations in TargetingDictionaryService, CommonTargetingService and/or AttributeTypeService. To retrieve the standard targeting attributes, use the operations in StandardTargetingAttributeService. To retrieve the targeting attribute types that are supported by a service, use the service-specific getSupportedTargetingAttributeTypes operation.
An order is the aggregation of ad placements and ads, as well as administrative information, such as the sales team, ad operations team, and contacts.
When you first set up an order, include financial details (such as availabe, net, and total budget, and gross cost), ad operations team (for billing, media, creative, and so on), contact, and sales team. You can associate an agency with the order and set up the agency to be billed instead of the advertiser.
Before you can place an order to run ads on a website, you must find the inventory you want for your order. You can search for inventory with various criteria including the buying type (of guaranteed or non-guaranteed), when you want ads to run (the flight dates), what your ads look like (ad formats and sizes), and how often you want ads to run (frequency cap and day parting). Additionally, you can include audience and content targeting.
For guaranteed delivery, search for inventory based on (the advertiser) currency, flight (start and end) date, ad attributes (such as the ad behavior, ad size, ad format), the target audience (such as demographic, geographic, behavioral, and technographic), ad delivery mode, and ad frequency. To find the highest number of impressions you can book for a given price, filter by maximumPrice, or to find the lowest price you need to obtain a given number of impressions, filter by minimumImpressions. When inventory matching your search criteria is found, activate your order. For non-guaranteed delivery, place your bid on available inventory, and, if your bid gets accepted, your ads may run on the non-guaranteed inventory.
When you activate an order, the system evaluates ad placements for the order and tries to validate the pricing (or bid, if the placement is a buying type of non-guaranteed delivery), the amount of available and bookable inventory, and the placement settings. If necessary, get your order approved and booked. When an order commits (has been booked), it begins to run on the flight start date.
- Compare the relative performance between creatives and placements.
- Target different creatives to different buckets of users so that you can view relative performance either from system-provided click data or pixeled conversion data.
Create experiments and test groups, assign test groups to an experiment, and associate an experiment with an order. After associating an experiment with an order, you can associate the test groups (in the experiment) with the ads (associated with the placements) in the order. If the order includes a mix of ads that have associated test groups and ads that do not have test groups, the ads with no test groups are, by default, assigned a combination of all test groups. You can use the experiments to evaluate the effectiveness of the ads inside and outside the test groups.
Cost feed is a mechanism by which the APT platform provides data (cost and revenue of the advertising activity) in electronic format. CostFeedService includes operations for downloading the feeds which are generated on a periodic basis, typically monthly.
You can reconcile delivery statistics collected by the platform with similar statistics collected by a third-party source by uploading data feeds for reconciliation. Once a serving feed is uploaded, it is associated with the reference feed, then manually or automatically reconciled (on a month-by-month basis), and finally certified. It is then converted to an outbound feed and can be downloaded using the AdjustmentService APIs.
You can also generate reports to view data that can help you compare actual online advertising delivery and performance with your business objectives. You can:
- Schedule reports to automatically run on a daily, weekly, monthly, or quarterly basis.
- Generate a report ad hoc for a date range.
For advertiser and publisher reports, you can specify a view and dimension for your report. The view determines the metrics that will be shown in the report and the dimension defines how the metrics are aggregated.
Performance reports include data such as impressions and clicks delivered, the percentage of click through rate (CTR), and the effective revenue per thoursand impressions (eRPM). Delivery reports include data such as the gross amount, amount delivered, projected, and at risk, and detailed impression information such as gross, booked, projected, delivered, and clicks delivered. You can generate reports that show currency values in company currency (the default currency for your company), deal currency (as set for each transaction), or exchange currency (always USD). While period data show pro-rated bookings and delivery numbers for the object of the report, for the dates specified for the report, lifetime data include total bookings and delivery numbers for the object of the report, irrespective of the dates specified for the report.
Tip: For more information on how to run a report, see ReportService Overview.