Skip to main content

Google Ads

This page contains the setup guide and reference information for the Google Ads source connector.

Prerequisites

Google Ads registered account with

  • Customer ID
  • Login Customer ID (you can find more information about this field in Google Ads docs)
  • Custom GAQL Queries (if needed)

Also:

  • Start Date
  • End Date
  • Conversion Window

For Airbyte OSS: Google Ads Account with an approved Developer Token. (note: In order to get API access to Google Ads, you must have a "manager" account; standard accounts cannot generate a Developer Token. This manager account must be created separately from your standard account. You can find more information about this distinction in the Google Ads docs.) You'll also need to find these values. See the setup guide for instructions.

  • Client ID
  • Client Secret
  • Refresh Token

Setup guide

Step 1: Set up Google Ads

This guide will provide information as if starting from scratch. Please skip over any steps you have already completed.

  1. Create a Google Ads Account. Here are Google's instructions on how to create one.
  2. Create a Google Ads MANAGER Account. Here are Google's instructions on how to create one.
  3. You should now have two Google Ads accounts: a normal account and a manager account. Link the Manager account to the normal account following Google's documentation.
  4. Select your customer_id. The customer_id refers to the id of each of your Google Ads accounts. This is the 10 digit number in the top corner of the page when you are in Google Ads UI. The source will only pull data from the accounts for which you provide an id. If you are having trouble finding it, check out Google's instructions.

Airbyte Open Source additional setup steps

  1. Apply for a developer token (make sure you follow our instructions on your Manager account. This token allows you to access your data from the Google Ads API. Here are Google's instructions. The docs are a little unclear on this point, but you will not be able to access your data via the Google Ads API until this token is approved. You cannot use a test developer token, it has to be at least a basic developer token. It usually takes Google 24 hours to respond to these applications. This developer token is the value you will use in the developer_token field.
  2. Fetch your client_id, client_secret, and refresh_token. Google provides instructions on how to do this.

How to apply for the developer token

Google is very picky about which software and which use case can get access to a developer token. The Airbyte team has worked with the Google Ads team to whitelist Airbyte and make sure you can get one (see issue 1981 for more information). When you apply for a token, you need to mention:

  • Why you need the token (eg: want to run some internal analytics...)
  • That you will be using the Airbyte Open Source project
  • That you have full access to the code base (because we're open source)
  • That you have full access to the server running the code (because you're self-hosting Airbyte)

Step 2: Set up the Google Ads connector in Airbyte

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. In the top-right corner, click +new source.
  3. On the Set up the source page, enter the name for the Google Ads connector and select Google Ads from the Source type dropdown.
  4. Click Authenticate your Google Ads account to sign in with Google and authorize your account.
  5. Get the customer ID for your account. Learn how to do that here
  6. If your access to the account is through a manager account, get the customer ID of the manager account.
  7. Fill out a start date, and optionally, a conversion window, and custom GAQL.
  8. You're done.

For Airbyte OSS:

  1. Create a new Google Ads source with a suitable name.
  2. Get the customer ID for your account. Learn how to do that here
  3. If your access to the account is through a manager account, get the customer ID of the manager account.
  4. Fill out a start date, and optionally, end date and a conversion window, and custom GAQL.
  5. Fill out the Client ID, Client Secret, Access Token(if any), Refresh Token and the Developer Token from Step 1)
  6. You're done

Supported sync modes

The Google Ads source connector supports the following sync modes:

  • Full Refresh | Overwrite
  • Full Refresh | Append
  • Incremental Sync | Append
  • Incremental Sync | Deduped History

Supported Streams

This source is capable of syncing the following tables and their data:

Main Tables

Note that ad_groups, ad_group_ads, and campaigns contain a labels field, which should be joined against their respective *_labels streams if you want to view the actual labels. For example, the ad_groups stream contains an ad_group.labels field, which you would join against the ad_group_labels stream's label.resource_name field.

Report Tables

Note: Due to constraints from the Google Ads API, the click_view stream retrieves data one day at a time and can only retrieve data newer than 90 days ago

Note: Due to constraints from the Google Ads API, metrics cannot be requested for a manager account. Therefore, report streams are only available when pulling data from a non-manager account.

Note: For incremental streams data is synced up to the previous day using your Google Ads account time zone. The reason is that Google Ads can filter data only by date without time. Also, some reports cannot load data in real time due to Google Ads limitations.

Understanding Google Ads Query Language

The Google Ads Query Language can query the Google Ads API. Check out Google Ads Query Language and the query builder. You can add these as custom queries when configuring the Google Ads source.

Note: Each custom query in the input configuration must work for all the customer account IDs. Otherwise, the customer ID will be skipped for every query that fails the validation test. For example, if your query contains metrics fields in the select clause, it will not be executed against manager accounts.

Note: Please take into account Google's note on Selectability between segments and metrics when editing custom queries or default stream schemas (which will also be turned into GAQL queries by the connector). Fields like segments.keyword.info.text, segments.keyword.info.match_type, segments.keyword.ad_group_criterion in the SELECT clause tell the query to only get the rows of data that have keywords, and remove any row that is not associated with a keyword. This is often not obvious and undesired behaviour and can lead to missing data records. If you do need this field in the stream, please choose adding a new stream instead of editing existing ones.

Performance considerations

This source is constrained by whatever API limits are set for the Google Ads that is used. You can read more about those limits in the Google Developer docs.

Changelog

VersionDatePull RequestSubject
0.1.422022-06-0813624Update google-ads to 15.1.1, pin protobuf==3.20.0 to work on MacOS M1 machines (AMD)
0.1.412022-06-0813618Add missing dependency
0.1.402022-06-0213423Fix the missing data issue
0.1.392022-05-1812914Fix GAQL query validation and log auth errors instead of failing the sync
0.1.382022-05-1212807Documentation updates
0.1.372022-05-0612651Improve integration and unit tests
0.1.362022-04-1912158Fix *_labels streams data type
0.1.352022-04-189310Add new fields to reports
0.1.342022-03-2911602Add budget amount to campaigns stream.
0.1.332022-03-2911513When end_date is configured in the future, use today's date instead.
0.1.322022-03-2411371Improve how connection check returns error messages
0.1.312022-03-2311301Update docs and spec to clarify usage
0.1.302022-03-2311221Add *_labels streams to fetch the label text rather than their IDs
0.1.292022-03-2210919Fix user location report schema and add to acceptance tests
0.1.282022-02-2510372Add network fields to click view stream
0.1.272022-02-1610315Make ad_group_ads and other streams support incremental sync.
0.1.262022-02-1110150Add support for multiple customer IDs.
0.1.252022-02-049812Handle EXPIRED_PAGE_TOKEN exception and retry with updated state.
0.1.242022-02-049996Use Google Ads API version V9.
0.1.232022-01-258669Add end date parameter in spec.
0.1.222022-01-249608Reduce stream slice date range.
0.1.212021-12-289149Update title and description
0.1.202021-12-229071Fix: Keyword schema enum
0.1.192021-12-148431Add new streams: Geographic and Keyword
0.1.182021-12-098225Include time_zone to sync. Remove streams for manager account.
0.1.162021-11-228178clarify setup fields
0.1.152021-10-076684Add new stream click_view
0.1.142021-10-016565Fix OAuth Spec File
0.1.132021-09-276458Update OAuth Spec File
0.1.112021-09-22#6373Fix inconsistent segments.date field type across all streams
0.1.102021-09-13#6022Annotate Oauth2 flow initialization parameters in connector spec
0.1.92021-09-07#5302Add custom query stream support
0.1.82021-08-03#5509allow additionalProperties in spec.json
0.1.72021-08-03#5422Correct query to not skip dates
0.1.62021-08-03#5423Added new stream UserLocationReport
0.1.52021-08-03#5159Add field login_customer_id to spec
0.1.42021-07-28#4962Support new Report streams
0.1.32021-07-23#4788Support main streams, fix bug with exception DATE_RANGE_TOO_NARROW for incremental streams
0.1.22021-07-06#4539Add AIRBYTE_ENTRYPOINT for Kubernetes support
0.1.12021-06-23#4288Bugfix: Correctly declare required parameters