Google Ads

This connector captures data from resources in one or more Google Ads accounts into Flow collections via the Google Ads API.

ghcr.io/estuary/source-google-ads:dev provides the latest connector image. You can also follow the link in your browser to see past image versions.

This connector is based on an open-source connector from a third party, with modifications for performance in the Flow system. You can find their documentation here, but keep in mind that the two versions may be significantly different.

Supported data resources

The following data resources are supported. Resources ending in _report represent legacy resources from the Google Adwords API.

• ad_group_ads
• ad_group_ad_label
• ad_groups
• ad_group_label
• campaigns
• campaign_labels
• click_view
• customer
• geographic_view
• keyword_view
• user_location_view
• account_performance_report
• ad_performance_report
• display_keyword_performance_report
• display_topics_performance_report
• shopping_performance_report

By default, each resource is mapped to a Flow collection through a separate binding.

You may also generate custom resources using GAQL queries.

Prerequisites

There are two ways to authenticate with Google when capturing data into Flow: using OAuth2, and manually, using tokens and secret credentials. Their prerequisites differ.

OAuth is recommended for simplicity in the Flow web app; the manual method is the only supported method using the command line.

Customer Id & Login Customer Id

The Login Customer Id setting refers to your MCC Google Ads account Id. One can easily find this number by accessing their Google Ads Dashboard and look to the far right corner of their screen.

Example:

In the above example, my login_customer_id would be 1234567890.

The Customer Id setting refers to your Client Accounts under a MCC account. One can easily find this number by accessing their Google Ads Dashboard and look to the far left corner of their screen, after selecting a client account.

Example:

In the above example, my customer_id would be 9876543210.

Multiple Customer Ids

This Source allows for multiple Customer Ids to be selected. To allow this, simply add your customer_id followed by a comma.

Example:

Customer1 = 1234567890 Customer2 = 9876543210

customer_id = 1234567890,9876543210

Using OAuth2 to authenticate with Google in the Flow web app

• One or more Google Ads accounts.

  • Note each account's customer ID

• A Google Account that has access to the Google Ads account(s).

  • This account may be a manager account. If so, ensure that it is linked to each Google Ads account and make note of its customer ID.

Configuring the connector specification manually

• One or more Google Ads accounts.

  • Note each account's customer ID

• A Google Ads manager account that has been linked to each Google Ads account

• A Google Ads developer token. Your Google Ads manager account must be configured prior to applying for a developer token.

caution

Developer token applications are independently reviewed by Google and may take one or more days to be approved. Be sure to carefully review Google's requirements before submitting an application.

• A refresh token, which fetches a new developer tokens for you as the previous token expires.

• A generated Client ID and Client Secret, used for authentication.

Configuration

You configure connectors either in the Flow web app, or by directly editing the Flow specification file. See connectors to learn more about using connectors. The values and specification sample below provide configuration details specific to the Google Ads source connector.

Properties

Endpoint

The properties in the table below reflect the manual authentication method. If you're working in the Flow web app, you'll use OAuth2, so many of these properties aren't required.

Property	Title	Description	Type	Required/Default
/conversion_window_days	Conversion Window (Optional)	A conversion window is the period of time after an ad interaction (such as an ad click or video view) during which a conversion, such as a purchase, is recorded in Google Ads. For more information, see Google's docs.	integer	14
/credentials	Google Credentials		object	Required
/credentials/client_id	Client ID	The Client ID of your Google Ads developer application.	string	Required
/credentials/client_secret	Client Secret	The Client Secret of your Google Ads developer application.	string	Required
/credentials/developer_token	Developer Token	Developer token granted by Google to use their APIs.	string	Required
/credentials/refresh_token	Refresh Token	The token for obtaining a new access token.	string	Required
/custom_queries	Custom GAQL Queries (Optional)		array
/custom_queries/-/query	Custom Query	A custom defined GAQL query for building the report. Should not contain segments.date expression. See Google's query builder for more information.	string
/custom_queries/-/table_name	Destination Table Name	The table name in your destination database for chosen query.	string
/customer_id	Customer ID(s)	Comma separated list of (client) customer IDs. Each customer ID must be specified as a 10-digit number without dashes. More instruction on how to find this value in our docs. Metrics streams like AdGroupAdReport cannot be requested for a manager account.	string	Required
/end_date	End Date (Optional)	UTC date in the format 2017-01-25. Any data after this date will not be replicated.	string
/login_customer_id	Login Customer ID for Managed Accounts (Optional)	If your access to the customer account is through a manager account, this field is required and must be set to the customer ID of the manager account (10-digit number without dashes).	string
/start_date	Start Date	UTC date in the format 2017-01-25. Any data before this date will not be replicated.	string	Required

Bindings

Property	Title	Description	Type	Required/Default
/stream	Stream	Google Ad resource from which a collection is captured.	string	Required
/syncMode	Sync Mode	Connection method.	string	Required

Sample

This sample specification reflects the manual authentication method.

captures:
  ${PREFIX}/${CAPTURE_NAME}:
    endpoint:
      connector:
        image: ghcr.io/estuary/source-google-ads:dev
        config:
          conversion_window_days: 7
          credentials:
            client_id: {secret_client_ID}
            client_secret: {secret_secret}
            developer_token: {access_token}
            refresh_token: {refresh_token}
          customer_id: 0123456789, 1234567890
          login_customer_id: 0987654321
          end_date: 2022-01-01
          start_date: 2020-01-01
          custom_queries:
            - query:
                SELECT
                  campaign.id,
                  campaign.name,
                  campaign.status
                FROM campaign
                ORDER BY campaign.id
              table_name: campaigns_custom
    bindings:
      - resource:
          stream: campaign
          syncMode: incremental
        target: ${PREFIX}/campaign
      {...}

Custom queries

You can create custom resources using Google Analytics Query Language (GAQL) queries. Each generated resource will be mapped to a Flow collection. For help generating a valid query, see Google's query builder documentation.

If a query fails to validate against a given Google Ads account, it will be skipped.

Stream Limitations

ClickView

Due to Google Ads API limitations, ClickView stream queries are executed with a time range limited to one day. Also, data can only be requested for periods 90 days before the time of the request.

In pratical terms, this means that you can only search ClickView data limited to 3 months ago, anything before this is not returned.

For more information, check Google's Ads API documentation