JSON Mappings

When using the Google Ads API's REST interface, you're working with JSON representations of the same resources and types defined in the Google Ads API's .proto descriptor files. The JSON encoding scheme follows the canonical encoding scheme described in the JSON Mapping section of the protocol buffers Language Guide.

In general, all top-level messages to and from services are single JSON objects. Most mutate requests contain an operations array that itself contains many create, update, or delete operations. Similarly, search responses are JSON objects containing a results array with your query's result set.

Identifiers are transformed from snake_case (in protocol buffers) to lowerCamelCase in JSON. One notable caveat to this rule is when using search or searchStream to send Google Ads Query Language queries. The query language itself uses snake case, regardless of which interface you're using. However, the results of a query in REST are returned as normal JSON objects and have their identifiers in lowerCamelCase.

For example, a query to fetch a list of active keywords in an account uses snake case inside the query itself (ad_group_criterion, not adGroupCriterion):

POST /v21/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "query": "SELECT ad_group_criterion.keyword.text
            FROM ad_group_criterion
            WHERE ad_group_criterion.type = 'KEYWORD'
            AND ad_group_criterion.status = 'ENABLED'"
}

However, the response is a JSON representation of the objects (wrapped in a JSON array since this request uses searchStream) and uses the camelCase identifier adGroupCriterion instead:

[
  {
    "results": [
      {
        "adGroupCriterion": {
          "resourceName": "customers/1842689525/adGroupCriteria/55771861891~10003060",
          "keyword": {
            "text": "pay per click"
          }
        }
      },
      ...
    ]
  }
]