Google Ads

API Call Structure  |  AdWords API  |  Google Developers

This guide describes the elements of an API call and demonstrates making
a basic call using cURL.

If you’re using a client library or a
SOAP library to interact with the API, you probably won’t need to worry
about the underlying SOAP and XML. However, knowing a bit about them can
come in handy when testing and debugging.

Making calls to the API involves sending HTTPS POST requests to a
service and interpreting the response. The body of the request and response is
comprised of XML defined by a
WSDL.
You can print the WSDL by appending a ?wsdl to the service URL:

https://adwords.google.com/api/adwords/cm/v201809/CampaignService?wsdl.

HTTP headers accompany the SOAP+XML body in the request:

Authorization
You need to include an
OAuth2 access token
in the form of Authorization : Bearer YOUR_ACCESS_TOKEN
that identifies either a manager account acting on behalf of a client, or an
advertiser directly managing their own account. Directions for retrieving an
access token can be found in the
OAuth2 guide. An access
token is valid for an hour after you acquire it; when it expires, refresh the
access token to retrieve a new one. Note that our client libraries automatically
refresh expired tokens.
developerToken
A 22-character string that uniquely identifies an AdWords API developer.
An example developer token string is ABcdeFGH93KL-NOPQ_STUv.
userAgent
A user-specified string that defines the sender and purpose of the
request. Set this to your application name and version in order to help us
find your requests when diagnosing a problem, for example, example.com:ReportDownloader:V7.18.
clientCustomerId
Customer ID of the target Google Ads account, typically in the form of
123-456-7890. Required for all calls to all services except
CustomerService and
ReportDefinitionService.
validateOnly (optional)
If set to true, the request is validated but not performed.
You can use this header to validate user-provided data.
partialFailure (optional and available for only some services)
If set to true, the service will perform all operations that are free of errors, and return
the errors for the failing operations. This header is ignored for non-mutate operations.

The following headers are returned with the response XML. We recommend that you
log these values for debugging purposes.

requestId
String that uniquely identifies this request.
operations
Number of operations performed in this request.
responseTime
Elapsed time in milliseconds between the web service receiving the request
and sending the response.

API call example

This example demonstrates how to interact with the API using
cURL. Although cURL and SOAP+XML would be impractical
for building a real-world application, the example demonstrates how the AdWords API
functions at the lowest level.

Request

  1. Get your OAuth2 client ID and client secret (if you haven’t done so already).
    Follow the instructions in the OAuth2 guide.

  2. Get an OAuth2 access token. To request your access token from OAuth2, enter your OAuth2
    client ID in the following URL, and paste it in your browser:

    https://accounts.google.com/o/oauth2/auth?client_id=your-client-id&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords&redirect_uri=urn:ietf:wg:oauth:2.0:oob&access_type=offline&prompt=consent
    

    A screen appears where you grant your application access to your Google Ads data:

    After you accept the request, you’ll receive an authorization code that can be exchanged for an access token.

    Finally, make the request to exchange the authorization code for an access token:

    curl 

    -d code=your-authorization-code

    -d client_id=your-client-id

    -d client_secret=your-client-secret

    -d redirect_uri=urn:ietf:wg:oauth:2.0:oob

    -d grant_type=authorization_code https://accounts.google.com/o/oauth2/token

    If you’ve made a proper request, Google will return your OAuth2 access token.
    The access token (shown in bold after access_token :) is what you need when
    sending requests to AdWords API services.

    {
    "access_token" : "ya29.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type" : "Bearer",
    "expires_in" : 3600,
    "refresh_token" : "1/Ixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  3. Create a SOAP request.
    The following XML defines a SOAP request that adds a budget. Save this XML (with
    your authentication token and account login replacing the placeholders) as
    hello_world.xml.

    
    
      
        
          xxx-xxx-xxxx
          YOUR_DEVELOPER_TOKEN
          YOUR_APPLICATION_NAME
          false
          false
        
      
      
        
          
            ADD
            
              Hello World
              PAUSED
              
                YOUR_BUDGET_ID
              
              
                DONT_CARE
              
              SEARCH
              
                true
                true
                false
              
              
                
                  false
                
              
            
          
        
      
    
    
  4. Send the request.
    Use cURL to send this SOAP request to CampaignService. You can send your access
    token by including it in the HTTP header like this:

    curl --header "Content-Type: application/soap+xml" 
         --header "Authorization : Bearer YOUR_ACCESS_TOKEN" 
         --data @hello_world.xml 
           https://adwords.google.com/api/adwords/cm/v201809/CampaignService
    

Response

After the AdWords API server processes your request, it returns a response that
contains the XML data representing the newly-added campaign:



  
    
      00053282f54911280ac10da199076e99
      CampaignService
      mutate
      1
      269
    
  
  
    
      
        CampaignReturnValue
        
          123456789
          Hello World
          PAUSED
          SUSPENDED
          20160510
          20371230
          
            YOUR_BUDGET_ID
            ...
            
              Money
              50000000
            
            STANDARD
            true
            ENABLED
          
          
            false
            NOT_ENOUGH_CONVERSIONS
          
          OPTIMIZE
          
            GeoTargetTypeSetting
            DONT_CARE
          
          SEARCH
          
            true
            true
            false
            false
          
          
            MANUAL_CPC
            
              ManualCpcBiddingScheme
              false
            
          
          BASE
          123456789
        
      
    
  

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button
Close