List Google Ads search terms

Changed on

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Returns the search terms that triggered the account's ads, ordered by impressions.

Pass either date_range or both start_date and end_date. Sending only one of the two dates is rejected with a 400, as is a start_date after end_date. Explicit dates win over date_range.

date_range accepts TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_WEEK_MON_TODAY, THIS_WEEK_SUN_TODAY, LAST_WEEK_MON_SUN, LAST_WEEK_SUN_SAT, LAST_BUSINESS_WEEK, THIS_MONTH, and LAST_MONTH, and defaults to LAST_30_DAYS. LAST_7_DAYS, LAST_30_DAYS and LAST_90_DAYS count back from today in the account's own time zone and include today; the other values are Google Ads' windows, which end yesterday.

At most 100 terms come back and there is no paging, so a busy account returns only its top 100. Terms are gathered from every campaign type on the account and merged into one list. When one of those reads fails the rest are still returned, under a 200 and with nothing in the response to say some terms are missing.

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>

get/api/apps/{app_id}/google-ads/analytics/search-terms

Request

  • Base URL: https://app.base44.com
  • URL: https://app.base44.com/api/apps/{app_id}/google-ads/analytics/search-terms
  • Auth: HTTP bearer

Path parameters

app_idstring required

ID of the app whose Google Ads reporting you want to read.

Query parameters

date_rangestring

A preset window, for example LAST_7_DAYS or LAST_MONTH. Ignored when start_date and end_date are both set.

start_datestring

First day of an explicit window, as YYYY-MM-DD. Requires end_date.

end_datestring

Last day of an explicit window, as YYYY-MM-DD. Requires start_date.

Response

Up to 100 search terms, highest impressions first.

search_termstring required

The term the user searched for.

campaignstring required

Name of the campaign whose ad the term matched.

impressionsinteger required

Impressions the term drove in the window.

clicksinteger required

Clicks the term drove in the window.

cost_microsinteger required

Amount spent on the term in the window, in micros of the account's currency.

conversionsnumber required

Conversions attributed to the term in the window.

Example response

[
  {
    "search_term": "oak dining table",
    "campaign": "Spring sale - Search",
    "impressions": 980,
    "clicks": 17,
    "cost_micros": 24500000,
    "conversions": 2
  }
]

Changes

  • c23775445de2Revision changes
    • breaking

      query request parameter end_date list-of-types was narrowed by removing types null

    • breaking

      query request parameter start_date list-of-types was narrowed by removing types null

    • info

      for the query request parameter end_date, the type was generalized from no type to string

    • info

      for the query request parameter start_date, the type was generalized from no type to string

  • b92cc2f13639Revision changes
    • info

      the security scope read_only was added to the endpoint's security scheme PersonalAccessTokenAuth

    • info

      the security scope full_access was removed from the endpoint's security scheme PersonalAccessTokenAuth