API Call Structure

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

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

Google Ads API is a gRPC API, with REST bindings. This means that there are two ways of making calls to the API.

  1. [Preferred] Create the body of the request as a protocol buffer, send it to the server using HTTP/2, deserialize the response to a protocol buffer, and interpret the results.

  2. [Optional] Create the body of request as a JSON object, send it to the server using HTTP 1.1, deserialize the response as a JSON object, and interpret the results.

Endpoint

This is the Google Ads API server endpoint where all requests are sent:

https://googleads.googleapis.com

Request URL

The request URL has two parts: an endpoint and a URL suffix. Constructing a request URL for a method consists of:

  1. Getting the HTTP method name and URL template suffix from the service proto file.
  2. Appending the URL template suffix to the server endpoint.
  3. Making necessary parameter substitutions to the suffix.

Example

In order to get the URL of the resource, go to the resource_name of the of the resource. For example, for CampaignBudget, the resource_name description has the path

customers/{customer_id}/campaignBudgets/{budget_id}

If you wanted to call the CampaignBudgetService.MutateCampaignBudgets method with an HTTP POST, you would transform that URL to look like:

/v0/customers/{customer_id}/campaignBudgets:mutate

The full URL endpoint for this method can be constructed by substituting {customer_id} with the Google Ads customer ID and appending it to the Google Ads API server endpoint.

So for a customer with ID 123-456-7890, the full URL endpoint would look like this:

https://googleads.googleapis.com/v0/customers/1234567890/campaignBudgets:mutate

Composite ID

If the ID of an object is not globally unique, a composite ID for that object is constructed by prepending its parent ID and an underscore character.

For example, since an ad group ad ID is not globally unique, we prepend its parent object (ad group) ID to it to make a unique composite ID:

  • AdGroupId of 123 + _ + AdGroupAdId of 45678 = composite ad group ad ID of 123_45678.

Request header

These are the HTTP headers (or grpc metadata) that accompany the 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.

developer-token

A developer token is a 22-character string that uniquely identifies a Google Ads API developer. An example developer token string is ABcdeFGH93KL-NOPQ_STUv. The developer token should be included in the form of developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

This is the customer ID of the authorized customer to use in the request, without hyphens (-). If your access to the customer account is through a manager account, this header is required and must be set to the customer ID of the manager account.

Setting the login-customer-id is equivalent to choosing an account in the Google Ads UI after signing in or clicking on your profile image at the top right. If you do not include this header, it defaults to the operating customer.

Response headers

The following headers (or grpc trailing-metadata) are returned with the response body. We recommend that you log these values for debugging purposes.

request-id

The request-id is a string that uniquely identifies this request.

API call example

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

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

  2. Enable Google Ads API in your Google Cloud project. Follow the instructions in the OAuth2 guide.

  3. Get an OAuth2 access token. To request your access token from OAuth2, enter your OAuth2 client ID in the following URL, and paste it into 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=AUTHORIZATION CODE \
      -d client_id=CLIENT ID \
      -d client_secret=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 returns your OAuth2 access token. The access token (shown in bold after "access_token" :) is what you need when sending requests to Google Ads API services.

    {
      "access_token" : "ya29.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/Ixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
    
  4. Create a REST request. The following JSON defines a request that adds a budget. Save this JSON as create_budget.json.

    {
      operations:
      [
        {
          create:
          {
            name: "new budget 234",
            amount_micros: "60000000"
          }
        }
      ]
    }
    
  5. Use cURL to send this request to CampaignBudgetService. Replace 1234567890 with your Google Ads advertiser account's customer ID, without the hyphens.

    curl --request POST \
         --header "Content-Type: application/json" \
         --header "Authorization: Bearer ACCESS TOKEN" \
         --header "developer-token: DEVELOPER TOKEN" \
         --data @create_budget.json \
         https://googleads.googleapis.com/v0/customers/1234567890/campaignBudgets:mutate
    

Response

After the Google Ads API server processes your request, it returns a response that contains the JSON data representing the newly-added budget.

{
  "results": [
    {
      "resourceName": "customers/1234567890/campaignBudgets/1xxxxxxxx1"
    }
  ]
}

What's next

Send feedback about...

Google Ads API Beta
Google Ads API Beta
Need help? Visit our support page.