You can extract performance data from the Bing Ads API for metrics such as cost, impressions, and clicks etc. The simplest way to do it is using the report service: It enables you to pull down similar reports to that which you can find on the Reports tab of the web interface. This article provides a basic tutorial showing you how to use the service with PHP.
The Bing Ads API Client Library
The adCenter API currently doesn’t have a client library available for PHP, so you need to construct the SOAP calls yourself; this makes using the API a little bit more challenging, but it’s not too hard once you get the hang of it. I’m using the standard PHP 5 SOAP extension for this tutorial.
The Bing Ads Report Service Location
You need to supply PHP with the location of the service WSDL and its XML namespace. Here are some constants to do this for version 8:
Authentication in the Bing Ads API
When you access the API, you need to supply a developer token together with the username and password of the account you wish to access; you also need the id of the account that you want to download data from:
The account ID can be found by looking for the
aid query parameter in the URL when you go to the Accounts & Billing tab on the web UI.
The username, password, and developer token need to be encoded into SOAP headers to be sent along with the service request later:
Defining Reports in the Bing Ads API
You request reports by sending SOAP objects of the specific type for the report you want to produce: For example, to produce a keyword report you would use the
KeywordPerformanceReportRequest, and for an ad report you would use the
AdPerformanceReportRequest etc. All of the request types derive from a base type called
ReportRequest that has the following properties:
- Format – To specify if you want the report in a CSV or XML file type.
- Language – The language of the heading rows.
- ReportName – A descriptive name for the report.
- ReturnOnlyCompleteData – Specifies if you want to see any data at all if the books aren’t closed for the chosen period of the report: For example, if you specify a time period of
Today, then the data won’t be fully processed yet; so if you supply
falsefor this parameter, then you'll get what’s currently available; alternatively, if you specify
true, then the report won’t be produced.
In addition to these, most of the derived types also have the following properties:
- Aggregation – The grouping of data according to time; valid values include
Summary. There are constraints on what values can be used in each report; one example is that some reports don’t allow
Hourlyaggregation. There’s also constraints about which time periods and columns can be combined with specific aggregation types: you can only use the
Custom Date Rangetimes with
Hourlyaggregation; and you can’t use the
- Columns – The fields you want to see in the report. These are specific to each report. For example, the keyword performance report has columns such as
TimePeriodcolumn can be included in most reports to show the date of a row.
- Filter – For removing specific rows from a report. Most reports have filters available, but they are specific to each one.
- Scope – Similar to the filter, it enables you to reduce the number of rows in the report. This is based on id’s of specific accounts, campaigns, and ad groups etc; if the scope is empty then the report will include all accounts for which the users has access.
- Time – The date range of stats to include in the report: Either use a preset value by specifying a
PredefinedTime, or use the
CustomDateRangeEndproperties. If you use the predefined time, then the value should be one of
LastSixMonths; for custom dates, you need to supply a
Dateobject with appropriate
Here’s an example of a simple request for a keyword performance report:
Scheduling Reports in the Bing Ads API
Once you’ve put together your report request, it first needs to be encoded as the type of report you want to create, then sent to the report service. If the report is scheduled without any errors, then the service will return an id for the report.
Polling a Scheduled Report
The adCenter API uses a similar method to the old AdWords and Yahoo API report services: An asynchronous method is used where you schedule a report, then periodically polling the API and wait for status updates.
You use the
PollGenerateReport action to request the status; it returns either
Success. You keep polling until the
Error status is returned. Note that polling the report uses API quota so you shouldn’t call it too often.
Here’s some code for polling a report:
Downloading the Report from the API
When the report is successfully produced, the
PollGenerateReport response also contains a
ReportDownloadUrl parameter that tells you the location where you can download the report.
The download is zipped up, so you need to decompress it before further processing.
Full Example Code: Downloading a Bing Ads API Report
Here's a complete script that downloads a report from the Bing Ads API: