Developer's Guide

This document describes how to use the Google™ AdSense™ for Audio API, which provides a programming interface for the AdSense for Audio system. This API is typically used by broadcast system manufacturers who are enhancing the systems they provide to radio stations by adding support for the AdSense for Audio program.

The documentation is intended for developers. It assumes that you are familiar with web services, XML, Simple Object Access Protocol (SOAP), and the programming language that your broadcast system is written in. It also assumes that you are familiar with AdSense for Audio.

Important: This API is not intended for radio stations that are interested in enrolling in the AdSense for Audio program. Radio stations that want to join the AdSense for Audio program can click here for more information.

Contents

1. API Overview
2. How to Implement the API
3. Implementation Requirements
4. SOAP and WSDL Information
5. Sandbox Information
6. Coding Best Practices

API Overview

The AdSense for Audio API provides a programming interface to a single web service named BroadcasterService. By implementing the AdSense for Audio API within your broadcast system you enable your broadcast system to:

• Notify the AdSense for Audio system about a radio station's available commercial inventory (known as designated inventory).
• Determine which units of designated inventory Google wants to fill with Google audio ads.
• Download audio files for each unit of designated inventory that Google is filling with audio ads.
• Report broadcast status to the AdSense for Audio system before, during, and after an ad is scheduled to air.

To implement the AdSense for Audio API within your broadcast system, you create a web service client that uses SOAP to exchange XML messages between your broadcast system and the BroadcasterService web service. SOAP is a widely-used, industry-standard protocol that uses HTTP as the service transport protocol. The BroadcasterService web service uses the SOAP 1.1 namespace (that is, SOAP version 1.1) with document/literal message style. Typically, you use a SOAP toolkit to create the web service client. The toolkit provides a framework for connecting to the web service and creating and interpreting the XML messages that are exchanged between the web service and your broadcast system.

The current version of the AdSense for Audio API provides five operations, although one of the operations has been deprecated and should not be used. The operations are listed in the order in which they are typically implemented.

• publishAvails

  The publishAvails operation is the first operation that you implement during a daily traffic cycle. You use this operation to designate available commercial inventory for the AdSense for Audio system, and determine which units of designated inventory Google wants to claim (reserve) for audio ads. You can also use the publishAvails operation to update designated inventory during the broadcast day. You typically implement this operation after the traffic log has been closed and available commercial inventory is known for the next day.

• acquireAds

  The acquireAds operation enables you to obtain information about the Google audio ads that the AdSense for Audio system is assigning to a station's designated inventory. You typically implement this operation throughout the broadcast day as you fill designated inventory with Google audio ads.

• getCreatives

  The getCreatives operation enables you to obtain information about an ad as well as a link (URL) to an ad's audio file. Although this information is provided by the acquireAds operation, there are instances where you might have to get this information again for a specific ad prior to broadcast. Therefore, this is an optional operation.

• updateAdStatuses

  The updateAdStatuses operation enables you to provide the AdSense for Audio system with the status of an ad. You must implement this operation before an ad is scheduled to air and after an ad airs or fails to air.

• releaseAds

  The releaseAds operation enables you to release (rescind) designated inventory that has been claimed (reserved) by the AdSense for Audio system. This operation has been deprecated and should not be used. Instead, you should use the publishAvails operation to release claimed inventory.

The BroadcasterService web service also provides numerous data objects, which are implemented as complex data types in the SOAP messages that are exchanged between your broadcast system and the BroadcasterService web service. For detailed information about each data type, see the Reference Guide.

Back to top

How to Implement the API

The AdSense for Audio API is designed to be integrated into a broadcast system, such as a radio automation system. To use the API, your broadcast system must support the daily traffic cycle that a typical radio station uses to schedule ads, merge ads and music, and automate the play-out of audio files.

Integrating the AdSense for Audio API into your broadcast system involves four implementation phases:

• Inventory identification

  During this phase you identify units of unsold commercial inventory that a radio station wants to make available to Google. These available units of inventory are referred to as designated inventory. To identify designated inventory you typically need to interpret various elements in the traffic log.

• Inventory publication

  During this phase you notify the AdSense for Audio system about the designated inventory, and determine which units of designated inventory Google wants to reserve for an audio ad. When designated inventory is reserved by the AdSense for Audio system it is referred to as claimed inventory.

• Ad acquisition

  During this phase you acquire Google audio ads for the designated inventory that has been claimed. Acquiring an ad gives you the association between a unit of claimed inventory and a specific ad as well as the URL to the ad's audio file.

• Status reporting

  During this phase you report the status of each ad (for example, whether it played or whether it failed to play).

The following figure shows where each of these implementation phases fit into the daily traffic and broadcast cycle. It also shows the software components that must be modified during each phase, and the required and optional BroadcasterService operations that are implemented during each phase.

Inventory Identification Phase

During the inventory identification phase you need to ensure that the broadcast system can identify the units of unsold inventory that the radio station wants to make available to the AdSense for Audio system. If your broadcast system is not tightly integrated with a specific traffic system (most aren't), inventory identification can be done by analyzing a station's traffic log.

When radio stations participate in the AdSense for Audio system they will have to use specific indicators in their traffic log to designate which spots they want to make available to the AdSense for Audio system. This inventory designation process is done as part of the station's daily operations (see previous figure) and is known as tagging. How you identify designated inventory depends on how the inventory was tagged.

Radio stations can tag their traffic log in a number of ways. The most common method of tagging is known as implicit tagging. In this case, the system responsible for merging the traffic and program logs uses existing elements in the station's traffic log to tag the spots that are being made available to the AdSense for Audio system. To support implicit tagging, a user interface is usually needed so that the station can specify which attributes in the traffic log are being used to tag Google designated inventory.

A common example of implicit tagging occurs when a station uses a radio automation system's audio category (that is, COM) to indicate Google designated inventory. In this case, a station configures the merge utility so that COM is understood to be a Google tag. The merge utility will then understand that all traffic log line items that contain audio from the COM category needs to be made available to the AdSense for Audio system.

Another form of implicit tagging is commonly used to support the AdSense for Audio closed-log avail (CLA) program. Stations participating in the CLA program make a percentage of their unsold inventory available to Google. In this case, the merge utility must understand what an unsold spot looks like in the station's traffic log format. Most modern traffic systems are capable of exporting their unsold inventory as part of the traffic log, although some have this functionality turned off by default. To support this type of implicit tagging, a station needs to configure the merge utility so that unsold spots are understood to be Google designated inventory, and they need to configure their traffic system to include such spots as necessary. The station also sets a percentage of the unsold inventory that it wants to make available to Google. The merge utility then identifies all unsold spots, up to the specified percentage, and makes them available to the AdSense for Audio system.

Explicit tagging can also be used as an alternate to the more passive implicit tagging. Explicit tagging makes use of the Title field in the station's traffic log by allowing stations to enter tags in the Title field for various traffic orders. Explicit tagging is often an effective method of specifying a fixed number of spots that a station wants to make available to the AdSense for Audio system or when implicit tagging strategies are not supported by a given traffic system.

To explicitly tag a spot, a station includes a keyword (for example, GOOGLE-AD) in the title of a traffic order. The station then configures the merge utility so that GOOGLE-AD exists in the list of keyword tags. When this is done, the merge utility makes all traffic orders with the keyword GOOGLE-AD in the title field available to the AdSense for Audio system. In order for explicit tagging to be effective it's important that the keywords be unique and not commonly used words. This helps prevent the merge utility from mistaking inventory that is not intended for Google.

At the end of the inventory identification phase, you should have identified all inventory that the station designated for a Google audio ad—whether through implicit tagging or explicit tagging—and your broadcast system should be ready to publish the designated inventory to the AdSense for Audio system.

Back to top

Inventory Publication Phase

During the inventory publication phase you need to provide the AdSense for Audio system with information about the designated inventory that is available for each radio station. In return, the AdSense for Audio system notifies you about which units of designated inventory it wants to claim (reserve) for Google audio ads and which units of designated inventory it does not want to claim for Google audio ads. To do this, you need to implement the publishAvails operation. This operation's request message consists of an AvailList array, which identifies each radio station, the broadcast date, and the specific units of designated inventory that are available for the AdSense for Audio system. Information about each unit of designated inventory is contained in a Spot array within the AvailList array. The operation's response message consists of an AvailClaimStatus, which contains a ClaimStatus that indicates whether or not the AdSense for Audio system is claiming (reserving) designated inventory for a Google audio ad.

You should implement the publishAvails operation as part of the merge process. At a typical station, the merge process takes place after the traffic manager closes the traffic log for the following day, usually around 4:00 PM station time. However, the merge can occur more frequently, or prior to the broadcast day, or even on the broadcast day itself. The frequency and timing depends on how active the station's traffic department is. As a consequence, you must implement the publishAvails operation whenever a station wants to make inventory available to the AdSense for Audio system.

During the merge process, before the traffic and program logs come together, you must notify the AdSense for Audio system about the designated inventory. The AdSense for Audio system then responds synchronously with information about which units of designated inventory it intends to claim. Claimed inventory should then be set aside for Google audio Ads. Unclaimed inventory should be merged out and replaced with content. In certain instances, stations may prefer to have unclaimed inventory remain on the log (this is true for both implicitly tagged and explicitly tagged inventory). You should make this a configuration option in the merge utility so that a station may specify which implicit and explicit tags correspond to inventory that should not be merged out.

It is important that you implement the publishAvails operation at least once before 9:00 PM station time for the following day's log. This is when the inventory management system (IMS) end-of-day processing typically occurs. The IMS is responsible for managing the allocation of ads and also handles forecasting, auctioning, and campaign optimization for the AdSense for Audio system. Implementing the publishAvails operation before 9:00 PM station time ensures that all designated inventory is eligible for the auction.

Also, you can implement the publishAvails operations for only a single day. If you are publishing designated inventory for more than one day (for example, the weekend), then you must implement publishAvails separately for each day. This functionality reflects the standard practices of radio stations whereby traffic managers often prepare several days worth of logs in advance of weekends and holidays. The publishAvails operation supports logs with dates up to five days in the future.

Note: You can also implement the publishAvails operation any time throughout the broadcast day if the broadcast schedule changes and you want to make new inventory available or you want to release (rescind) claimed inventory. For more information, see Managing Schedule Changes.

During this phase you also need to generate a unique identifier for each unit of designated inventory. This identifier is known as a partnerSpotId. The partnerSpotId maps a unit of designated inventory to the adSpotId, which is generated by the AdSense for Audio system when you first use the publishAvails operation. A partnerSpotId is of type long, and you can use any method that you want to generate it. It must be unique for a given radio station and for a given day.

Back to top

Ad Acquisition Phase

The acquireAds operation enables you to obtain ads for the designated inventory that has been claimed by the AdSense for Audio system. The request message for the acquireAds operation consists of an AcquireAdRequest array, which contains the list of claimed inventory that you want to obtain ads for. The response message consists of an AcquireAdResponse array, which contains information about each unit of claimed inventory that is being filled with an ad, including the URL to the ad's audio file (for security reasons this URL is transient and will be invalid after 24hours). The AcquireAdReponse also contains an AdSpotStatus, which indicates whether the AdSense for Audio system is ready to allocate an ad to a unit of claimed inventory. Some units of claimed inventory will not have ads allocated to them when you implement the acquireAds operation. To provide advertisers with scheduling flexibility, Google might not allocate an ad until 15 minutes before the claimed inventory is scheduled to air. Therefore, you need to evaluate AdSpotStatus every time you implement the acquireAds operation, even for claimed inventory that has been filled.

In general, AdSpotStatus provides one of three responses:

• NOT_READY indicates that the AdSense for Audio system has not determined which ad it wants to air. You must implement the acquireAds operation again to obtain an ad for the claimed inventory.
• NOT_FINAL indicates that the AdSense for Audio system has determined which ad it wants to air, but the AdSense for Audio system reserves the right to change the ad until 15 minutes prior to the scheduled air time. You should download the media files for all ads that have a status of NOT_FINAL, create a cart for each ad, and add each cart to the local cart library. Also, you must implement the acquireAds operation again to determine whether a different ad has been allocated for the claimed inventory.
• COMPLETE indicates that the AdSense for Audio system considers the ad allocation to be complete and the ad ready to air. You should download the media files for all ads that have a status of COMPLETE, create a cart for each ad, and add each cart to the local cart library. You do not need to implement the acquireAds operation again for ads that are COMPLETE.

The ad acquisition phase is an interactive process. You usually start implementing the acquireAds operation after approximately 10:00 PM station time the day before any claimed inventory is scheduled to air. Because Google reserves the right to fill claimed inventory with ads up until 15 minutes prior to broadcast, most of the claimed inventory will have AdSpotStatus values of NOT_READY or NOT_FINAL. You must implement the acquireAds operation again for this claimed inventory approximately two hours prior to the scheduled broadcast time, and continue implementing the acquireAds operation every 15 minutes until the AdSpotStatus is COMPLETE.

Acquiring Audio Files

To acquire audio files the broadcast system must programmatically download audio files from the URLs that are provided in the acquireAds response message or in the optional getCreatives response message. The audio files that Google provides are 30-second or 60-second WAV encoded MPEG2 files with a 44.1kHz sample rate. The files have also been volume normalized and pitch adjusted, with any leading and trailing silence removed. When you download an audio file, your broadcast system should use it to create a cart, or air-ready audio file. If the audio provided by Google does not meet the air-ready specifications of your broadcast system, you must programmatically convert the audio file into a suitable format. If an audio file needs to be programmatically converted to a different format, you must perform the conversion immediately after you download the audio file because Google may be providing the final audio file only 15 minutes prior to the scheduled air time.

We strongly suggest that you maintain the carts associated with Google audio files in a segregated portion of a station's cart library. Carts should be stored locally until they go unused for an extended period of time (for example, two weeks), after which they should be removed programmatically to free up space on the station's system. Maintaining a library of Google carts at the station dramatically reduces the amount of network traffic required by the AdSense for Audio system. This also greatly reduces the potential for play failures caused by network latency or the inability to get audio files to the station before a unit of claimed inventory is scheduled to air.

Note: The conversion of Google-provided audio files into air-ready cart files must be automated. AdSense for Audio requires that there be no manual touch points (that is, user interface elements) that block Google audio ads from being broadcast. A manual conversion process would be considered such a blockage.

Readying Ads for Play-out

The acquireAds response message tells your broadcast system which Google audio ad to play for each unit of claimed inventory. To fulfill this instruction, your broadcast system should look up the audio file in the local Google cart library. If the cart exists, it should be associated with the unit of claimed inventory. If the cart does not exist, the audio should be downloaded from Google, converted as necessary, made into a cart, and added to the local Google cart library. When the new audio has been added to the library, your broadcast system should schedule the cart into the appropriate unit of claimed inventory.

Back to top

Status Reporting Phase

The updateAdStatuses operation enables you to provide the AdSense for Audio system with the status of an ad before, during, and after the scheduled broadcast time. The request message for the updateAdStatuses operation consists of an UpdateAdStatusRequest array, which contains a list of ads that you want to provide status for. UpdateAdStatusRequest also contains a PlayStatus for each ad, which contains the specific type of ad status that you are reporting to the AdSense for Audio system. Radio stations are contractually obligated to report ad status before, during, and after an ad's scheduled broadcast time, and you use the PlayStatus to indicate what type of status you are reporting. The following table shows the sequence and timing of the PlayStatus flags that you must implement during the status reporting phase. The table shows an idealized situation for a single ad. The table does not show all of the request parameters that are necessary (for example, spot identifiers, ad identifiers, spot time, and spot duration); it shows only the PlayStatus request parameters that are required for ad status reporting under the AdSense for Audio API Terms of Service.

At this time...	Set PlayStatus to this...	Description
One minute prior to air time	AD_PLAY_QUEUED	Use this to indicate that an ad is queued and ready to play. This enables Google to digitally record ad play in context, which is an important feature of the Google Audio Ads™ program.
Exactly at air time	AD_PLAY_STARTED	Use this to indicate that an ad has started to play.
One minute after an ad aired	AD_PLAYED	Use this to indicate that an ad played. Ideally, you should provide this status one minute after an ad airs; however, you can provide this status up to one hour after an ad airs. Providing this status more than 24 hours after an ad airs is unacceptable and will result in a late-reporting error in the UpdateAdStatusErrorCode.
One minute after an ad failed to air	AD_PLAY_FAILED	Use this to indicate that an ad failed to play. Ideally, you should provide this status one minute after an ad's scheduled air time; however, you can provide this status up to one hour after an ad's scheduled air time. Providing this status more than 24 hours after an ad's scheduled air time is unacceptable and will result in a late-reporting error in the UpdateAdStatusErrorCode.

In addition, you can use the following optional PlayStatus flags to report status conditions:

• AD_PLAYED_PARTNER_VERIFIED Use this if the radio station has a secondary verification mechanism or uses a third-party entity to verify broadcasts. This is a supplemental status flag and has precedence over AD_PLAYED and AD_PLAY_FAILED. For example, if you first report a status of AD_PLAY_FAILED for an ad, and later you report AD_PLAYED_PARTNER_VERIFIED, the AdSense for Audio system will assume that the ad played and was verified by a secondary system.
• AD_PLAY_FAILED_PARTNER_VERIFIED Use this if the radio station has a secondary verification mechanism or uses a third-party entity to verify broadcasts. This is a supplemental status flag and has precedence over AD_PLAYED and AD_PLAY_FAILED. For example, if you first report a status of AD_PLAYED for an ad, and later you report AD_PLAY_FAILED_PARTNER_VERIFIED, the AdSense for Audio system will assume that the ad failed to play and was verified by a secondary system.
• AD_ACCEPTED Use this to indicate that an ad's cart is registered with the broadcast system and that the audio file for the ad has been downloaded and locally cached. You are not required to provide this notification. However, providing this notification can be useful for troubleshooting purposes.

Late reporting adversely affects the user experience for advertisers and must be avoided. In the event that you report ad status later than 24 hours, and you receive a late-reporting error, you must indicate in your error log that the ad played but Google does not consider the ad play payable.

Also, ad status can be changed only within one hour of an ad's scheduled air time. For example, if you provide ad status of AD_PLAY_FAILED immediately after an ad aired, and then you provide an ad status of AD_PLAYED_PARTNER_VERIFIED two hours later, the AdSense for Audio system will ignore the AD_PLAYED_PARTNER_VERIFIED status message.

In addition to PlayStatus, you need to provide an error number and an error message in the UpdateAdStatusRequest message if an ad failed to air. Google logs the values you provide for these fields, but it is up to you to create the error number and the text message that describes the error condition. Also, be sure to keep a record of each error that you report.

The response message for the updateAdStatuses operation consists of an UpdateAdStatusResponse, which contains an UpdateAdStatusCode and an UpdateAdStatusError array. The UpdateAdStatusCode indicates whether the AdSense for Audio system successfully received all of your ad statuses. The UpdateAdStatusError provides information about each of the ads that did not have their ad statuses updated.

Note: If the AdSense for Audio system is down for maintenance when you report ad status you will receive a SERVICE_UNAVAILABLE SOAP fault. In this event, the 24-hour status reporting requirement will be waived and you should report ad status until you receive a SUCCESS response message.

Back to top

Managing Schedule Changes

You can use the publishAvails operation throughout the broadcast day to make new designated inventory available to the AdSense for Audio system or release designated inventory that has already been claimed. You may need to do this if the broadcast schedule changes (for example, a radio station decides to run a local ad instead of a Google ad, or a program change causes new inventory to open up). Implementing the publishAvails operation is the only way to release designated inventory that has already been claimed. Do not use the releaseAds operation to do this; the releaseAds operation has been deprecated.

When you implement the publishAvails operation during the broadcast day you must republish all claimed inventory that has not aired, including claimed inventory that you do not want to change. In other words, you cannot incrementally release individual units of claimed inventory or incrementally publish individual units of designated inventory with the publishAvails operation; instead, you must republish the changes along with the existing claimed inventory.

To make new designated inventory available to the AdSense for Audio system you simply add the designated inventory to the new AvailList that you are submitting to the AdSense for Audio system. To release claimed inventory you simply omit it from the new AvailList that you are submitting to the AdSense for Audio system.

You can only publish designated inventory that is scheduled to air more than two hours in the future. Any changes to claimed inventory that is scheduled to air less than two hours in the future (or in the past) will be ignored. For example:

• If you are releasing claimed inventory that is scheduled to air less than two hours in the future, the request to release the claimed inventory will be ignored. That is, Google will assume that a Google ad will still air and Google will expect you to provide ad status for the ad.
• If you are releasing claimed inventory that is scheduled to air more than two hours in the future, Google will release the claimed inventory and Google will not expect to receive an ad status for the claimed inventory.
• If you are publishing new designated inventory that is scheduled to air less than 2 hours in the future, the designated inventory will be ignored. That is, Google will not claim those units of designated inventory that are scheduled to air less than two hours in the future.

To facilitate schedule changes, your broadcast system must provide a user interface that enables radio stations to add new designated inventory to the broadcast schedule and delete claimed inventory from the broadcast schedule. In addition, you must provide a notification that indicates whether the schedule changes were successful, and you must make sure that any newly-claimed inventory is added to the broadcast schedule and any claimed inventory that is successfully released is removed from the broadcast schedule.

Changes to the broadcast schedule can impact a radio station's contractual obligation to the AdSense for Audio program. For example, if a schedule change forces you to release claimed inventory less than two hours prior to its scheduled air time, and the radio station does not play a Google ad at the scheduled time, then the ad will be considered a failed ad. Although you have no way of knowing what a radio station's contractual obligations are, you might want to provide a user interface warning or some other notification through the broadcast system whenever a schedule change affects the AdSense for Audio system.

In addition, there is no penalty for releasing claimed inventory, however, releasing claimed inventory can have unanticipated consequences if the claimed inventory is released on the last day of an advertising campaign. For example, if a unit of designated inventory is claimed and then released on the last day of its advertising campaign, the IMS will not be able to allocate a make-good ad the following day because the advertising campaign will be closed. Therefore, the radio station might not be able to satisfy its contractual obligations by running a make-good ad. Although you have no control over schedule changes, you might want to provide this information in your user documentation or in any notifications that you generate when a schedule change occurs.

Back to top

Implementation Requirements

To fully integrate AdSense for Audio support into your broadcast system you must adhere to the AdSense for Audio API Terms of Service and you must be certain that you are enabling your customers (that is, radio stations) to meet their AdSense for Audio contractual obligations. To do this, you must meet the following technical implementation requirements:

Fully Automated Integration

You must implement the AdSense for Audio API in such a way that no user interaction is necessary for the delivery and broadcast of ads. In other words, no radio station personnel should be required to interact with your broadcast system or the AdSense for Audio system during the inventory publication phase or the ad acquisition and status reporting phases. Your AdSense for Audio integration must be transparent to the radio stations.

Timely Notification of Available Inventory

You must first notify the AdSense for Audio system about designated inventory between 4:00 PM and 9:00 PM (station time) the day before the inventory is scheduled to air. If you subsequently notify the AdSense for Audio system about available inventory during the broadcast day, you must do it more than two hours in advance of the scheduled air time.

Timely Notification of Released Inventory

You must provide timely notification of released inventory. Released inventory is claimed inventory that the radio station wants to rescind. Claimed inventory that is scheduled to air less than two hours in the future cannot be released. Claimed inventory that is scheduled to air more than two hours in the future can be released.

Timely Status Reporting

You must report the status of each ad at the following times:

• One minute prior to the scheduled air time.
• When the ad airs.
• One minute after the scheduled air time

It is acceptable to report the status of an ad up until the end of the broadcast day, but it is not acceptable to report status more than 24 hours after an ad's scheduled air time.

Inventory Identification

You must provide a way for radio stations to configure the merge utility to recognize designated (tagged) inventory in the traffic log. The method you devise must support both implicit and explicit tagging.

Management of the Broadcast Schedule

You must provide a user interface that enables radio stations to make new inventory available to the AdSense for Audio system and delete claimed inventory from the AdSense for Audio system during the broadcast day. You must also provide notifications that indicate whether the schedule changes were successful, and you must make sure that the schedule changes show up in the broadcast schedule.

Setup

You must provide your customers with a means for setting up your broadcast system for the AdSense for Audio program. At a minimum you must provide a user interface that radio stations can use to enter their authorization token and partnerStationId into your broadcast system.

Clear and Concise Error Handling

You must handle all known AdSense for Audio error conditions and where necessary provide clear and concise error messages to your users.

Pass the Test Criteria

You must implement and pass the test criteria established by the AdSense for Audio API development team. The test criteria determines how well your implementation of the AdSense for Audio API is working.

Customer Documentation

You must provide your customers with documentation, such as a Quick Start Guide or a User Guide, that describes how to set up and operate AdSense for Audio in your broadcast system. Specifically, the documentation must tell users how to:

• Use the Broadcast Management Console to obtain their authorization token and partnerStationId.
• Enter the authorization token and partnerStationId into your broadcast system.
• Tag or designate available inventory in their traffic system. This includes instructions for implicit tagging and explicit tagging.
• Make changes to the broadcast schedule. This includes how to use your broadcast system to make new inventory available to the AdSense for Audio system and how to release claimed inventory.

Back to top

SOAP and WSDL Information

The AdSense for Audio API uses Simple Object Access Protocol (SOAP) to exchange XML messages between your broadcast system and the BroadcasterService web service. SOAP is a widely-used, industry-standard protocol that enables you to exchange XML messages by using HTTP as the service transport protocol. Typically, you use a SOAP toolkit to programmatically interact with a web service. A SOAP toolkit provides code, in your programming language, that you can use to connect to a web service. It also provides code for creating and interpreting the XML messages that are exchanged between the web service and your broadcast system. SOAP toolkits are available for a wide number of programming languages, such as C#, C++, Java, and Python. For more information about SOAP toolkits, see the Getting Started Guide.

SOAP Information

SOAP requests and responses are structured as simple XML messages. XML SOAP request messages are sent as HTTP POST requests, and the XML response messages are sent back as responses to the HTTP POST request. The AdSense for Audio API requires that all messages be encrypted with SSL (that is, with HTTPS).

Each XML message consists of a header and a body. The header specifies metadata about the message. The AdSense for Audio API requires you to include an authorization token in every request header. The authorization token enables you to access the AdSense for Audio sandbox and was issued to you when you registered as an AdSense for Audio development partner. The following example shows how an authorization token appears in a SOAP request header.

<soapenv:Envelope 
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:afa="http://www.google.com/api/afa">
  <soapenv:Header>
    <afa:authtoken>your_authorization_token</afa:authtoken>
  </soapenv:Header>
  <soapenv:Body>
    ...
  </soapenv:Body>
</soapenv:Envelope>

The body specifies the BroadcasterService operation that you are implementing and any applicable parameters that the web service needs to perform the requested operation. The following example shows how the acquireAds operation and its corresponding data parameters appears in the body of a SOAP request message.

<soapenv:Envelope 
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:afa="http://www.google.com/api/afa">
  <soapenv:Header>
    <afa:authtoken>your_authorization_token</afa:authtoken>
  </soapenv:Header>
  <soapenv:Body>
    <afa:acquireAds>
      <afa:acquireAdRequest>
        <afa:AcquireAdRequest>
          <afa:adSpotId>4539302</afa:adSpotId>
          <afa:dateTime>2007-12-06T04:15:30Z</afa:dateTime>
          <afa:duration>30</afa:duration>
          <afa:partnerSpotId>4476</afa:partnerSpotId>
          <afa:partnerStationId>3074</afa:partnerStationId>
        </afa:AcquireAdRequest>
      </afa:acquireAdRequest>
    </afa:acquireAds>
  </soapenv:Body>
</soapenv:Envelope>

The BroadcasterService web service uses the SOAP 1.1 namespace (sometimes known as SOAP version 1.1) with document/literal message style. This corresponds to the following namespace:

http://www.w3.org/2001/XMLSchema

WSDL Information

The requests that a web service can process are defined in a Web Services Description Language (WSDL) file. The WSDL file describes the operations that the web service can perform, the required parameters for each operation, and the response for each operation. It also includes definitions of the SOAP header elements and the faults that are returned when an error condition occurs.

The current version of the WSDL (version 2) is represented by the following XML namespace:

http://www.google.com/api/afa

The WSDL file for version 2 of the BroadcasterService web service is located at:

https://www.google.com/api/afa/v2/BroadcasterService?wsdl

Back to top

Sandbox Information

The AdSense for Audio sandbox is a replica of the live AdSense for Audio system, and provides all of the functionality that the live AdSense for Audio system provides. For example, you can send requests to the BroadcasterService web service and receive responses that contain actual claim information. You can also send acquireAds requests on claimed inventory and receive responses that contain actual URLs to audio files and MD5 checksums for audio files, and you can provide statuses for ads.

To use the sandbox you must put your sandbox authorization token in the header element of each SOAP message. The authorization token was issued to you when you registered as an AdSense for Audio development partner. It is similar to the authorization token that radio stations are issued when they enroll in the AdSense for Audio program.

You were also issued one or more station identifiers that you can use for testing purposes in the sandbox. You can use the station identifiers to populate the partnerStationId fields in your test code. Each station identifier corresponds to a specific radio station in the United States, which means that you must use the radio station's time zone to determine your GMT date and time offsets.

Back to top

Coding Best Practices

Be sure to use the following best practices and coding conventions as you plan, design and implement your AdSense for Audio integration:

• Use retry logic

  You should use standard retry logic whenever you are making requests to a web service over a public network such as the Internet. Network latency and network routing errors can cause your requests to timeout, which can result in sporadic failure. If a request fails, we recommend that you use a retry delay of 30 seconds, 1 minute, 2 minutes, 5 minutes, 10 minutes, and so on up to 3 hours. If you still see errors at 3 hours, then you need to determine whether there is a network problem causing the failure or some other issue.

• Locally cache audio files

  You should download and locally cache an ad's audio file when you obtain the URL to the audio file. The path to an ad's audio file is a transient URL and has a lifetime of 24 hours. After 24 hours the link will be dead and you will have to use the getCreatives operation to obtain a new URL to the audio file.

• Create a cart when you download an audio file

  Be sure to create a cart and register the cart with the local cart library as soon as you download an audio file. Also, we suggest that you maintain the carts associated with Google audio files in a segregated portion of a station's cart library, which will dramatically reduce the network traffic required by the AdSense for Audio system.

• Schedule ads

  Be sure to add ads to the broadcast schedule when you create a cart. This enables the radio station to see which ad is scheduled to play in a given unit of designated inventory.

• Use checksums

  You should always verify the integrity of each audio file by using the MD5 checksums that are provided in the AcquireAdsResponse and CreativeResource data type.

• Update ad statuses often

  The updateAdStatuses operation is the most frequently used operation. Do not be shy about using this operation. It's not unusual for this operation to be implemented a thousand times in one day.

• Always use Greenwich Mean Time (GMT)

  All dates and times must be represented in Greenwich Mean Time (GMT) relative to the local radio station's time. For example, if a unit of designated inventory is scheduled to run on a Los Angeles radio station at 10:20 AM on January 22, 2008, you would represent this time as 2008-01-22T18:20:00Z (that is, GMT= PST + 8 hours). Be sure to take into account Daylight Saving Time when you make this calculation.

• Format times and dates correctly

  Times and dates should be formatted according to the W3C Recommendation, and according to the date and time field descriptions in the Reference Guide.

• Log messages

  In some cases you are responsible for creating error messages and error codes for various error conditions. Be sure to log these errors so that you can reconcile them with the AdSense for Audio logs. This is useful for troubleshooting.

Back to top