JSON Mappings

AI-generated Key Takeaways

• The Search Ads 360 Reporting API's REST interface uses JSON to represent the resources and types defined in its .proto descriptor files, adhering to the canonical JSON encoding scheme.

• Top-level messages in REST are single JSON objects, and search responses contain a results array holding the query's result set.

• Identifiers are generally transformed from snake_case in protocol buffers to lowerCamelCase in JSON, except within Search Ads 360 Query Language queries which retain snake_case.

• Although Search Ads 360 Query Language uses snake_case, the results returned via REST are standard JSON objects with lowerCamelCase identifiers.

When using the Search Ads 360 Reporting API's REST interface, you're working with JSON representations of the same resources and types defined in the Search Ads 360 Reporting 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. 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 Search Ads 360 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 /v0/customers/CUSTOMER_ID/searchAds360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_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"
          }
        }
      },
      ...
    ]
  }
]