Introducing the Bing Ads Python SDK
We are excited to announce the availability of the Bing Ads Python SDK Beta today. This SDK client library will improve your Bing Ads developer experience by providing high-level access to features such as:
This post is an overview of the main features available within the Bing Ads Python SDK. You can find more details about these and other features on our MSDN page. Our Bing Ads Python SDK is distributed through pypi and the open source code can be downloaded from github.
Since its first announcement, the Bulk API has offered an efficient way to manage your campaigns, keywords and other entities, transferring large amounts of data up to ten times faster than traditional SOAP APIs. However, as a text-based API, the Bulk API requires a lot of work on the client side to parse and process the files containing the Bing Ads entities. On the other hand, traditional SOAP APIs can be easily accessed using an automatically generated object model.
The Bing Ads SDK closes this gap by providing an infrastructure for accessing the Bulk API using the same object model as our SOAP APIs.
Our SDK makes it very easy now to migrate your existing code working with the SOAP API objects to take advantage of the Bulk API. For example, one of the most popular requests from advertisers is the ability to quickly update keyword bids under their account based on their performance. Here’s how it can be done using the Bing Ads SDK:
First we instantiate a BulkServiceManager object:
Then download the keywords including their performance data during the last month:
data_scope=[ 'EntityData' , 'EntityPerformanceData' ],
entities=[ 'Keywords' ],
And finally upload the keywords back, while increasing the bids by 10 for the keywords that had received more than 100 clicks:
for entity in bulk_entities:
if isinstance(entity, BulkKeyword) \
and hasattr(entity.performance_data, 'clicks') \
and entity.performance_data.clicks > 100:
entity.keyword.Bid.Amount=entity.keyword.Bid.Amount * 1.10
if keywords.count > 0:
# output the uploaad results
for entity in bulk_entities:
if isinstance(entity, BulkKeyword):
The SDK also provides an easy way to write your objects to the bulk files or parse existing bulk files. Please check out the MSDN documentation for the BulkFileReader and BulkFileWriter.
As you may already know, Bing Ads is now actively transitioning to the OAuth Authorization model, a better and more secure way to handle user authentication than the traditional username/password authentication. To make this transition easier for our customers, the Bing Ads SDK includes high-level implementations of standard OAuth 2.0 grant flows, including the authorization code grant flow for both web and desktop applications and the implicit grant flow for desktop applications.
For example, to start using the OAuth authorization code grant flow, you have to first instantiate the corresponding OAuth object. If you are building a web app:
oauth_web_auth_code_grant = OAuthWebAuthCodeGrant(
Or if you are working on a desktop app:
oauth_desktop_mobile_auth_code_grant = OAuthDesktopMobileAuthCodeGrant(
Then you can get the url to direct the user to the Microsoft Account authorization page:
And once you are called back by the Microsoft Account authorization server, you can request the OAuth tokens by using the received authorization response uri:
oauth_tokens = oauth_web_auth_code_grant.oauth_tokens
access_token = oauth_tokens.access_token
When using the OAuth objects with the ServiceClient class (described in the next section), your access and refresh tokens will be automatically refreshed upon the access token expiration. Optionally you can register a callback function to automatically save the refresh token anytime it is refreshed. For example if you defined have a save_refresh_token() method that securely stores your refresh token, set the
authentication token_refreshed_callback property.
One of our goals in the Bing Ads SDK is to make sure it’s easy to access the SOAP APIs without doing any additional work. We have included a wrapper ServiceClient class that provides uniform access to all of our SOAP services. It also handles common request header fields for you, allowing to specify the values for fields such as CustomerId, AccountId, DeveloperToken etc. in the AuthorizationData object only once.
Here is an example of initializing the AuthorizationData object using the OAuthWebAuthCodeGrant instance defined above:
# IDs not required for Customer Management service
The Authentication property can hold one of the OAuth Authorization objects (for authorization code grant flow or implicit grant flow also described in the previous section) or the PasswordAuthentication object (if you want to use the user name/password authentication).
Now that we have the AuthorizationData object, we can create the ServiceClient and call API operations without passing the same information with every request:
# Set to an empty user identifier to get the current authenticated Bing Ads user
Note that we only set the UserId field on the GetUserRequest. All other fields will be taken from the AuthorizationData object that we provided earlier.
Whenever the current access token expires, ServiceClient and BulkServiceManager will request a new set of access and refresh tokens from the Microsoft Account authorization server on your behalf. To ensure you always have the latest refresh token, you should listen for new tokens received by registering a callback function. For example if you have a save_refresh_token that stores a refresh token securely, register it with the token_refreshed_callback authentication property.
Please check our MSDN pages for more information about working with the Bing Ads SDK:
- Configuring Sandbox access for web applications and desktop applications
- Register an application to use OAuth authentication
- Bing Ads Python SDK source code in github
- Python docs in github
- Python SDK Code Samples:
Our Java SDK will be out of beta and released for general availability later this week.
Please let us know what you think about the Bing Ads SDK by sending an email to email@example.com or leaving a comment below. We want to know about your experience coding with the Bing Ads SDK and what we can do to help you minimize your coding time and maximize conversions.