# Google Ads (AdWords)

The tap-adwords extractor pulls data from the Google AdWords API.

Repository: https://gitlab.com/meltano/tap-adwords
Maintainer: Meltano community
Maintenance status: Active

# Getting Started

# Prerequisites

If you haven't already, follow the initial steps of the Getting Started guide:

# Installation and configuration

# Using the Command Line Interface

Add the tap-adwords extractor to your project using meltano add:
```
meltano add extractor tap-adwords
```
Configure the settings below using meltano config.

# Using Meltano UI

Start Meltano UI using meltano ui:
```
meltano ui
```
Open the Extractors interface at http://localhost:5000/extractors.
Click the "Add to project" button for "Google Ads".
Configure the settings below in the "Configuration" interface that opens automatically.

# Next steps

Follow the remaining steps of the Getting Started guide:

If you run into any issues, learn how to get help.

# Settings

tap-adwords requires the configuration of the following settings:

Developer Token
OAuth Client ID
OAuth Client Secret
Refresh Token
Customer ID(s)
Start Date

These and other supported settings are documented below. To quickly find the setting you're looking for, use the Table of Contents in the sidebar.

# Minimal configuration

A minimal configuration of tap-adwords in your meltano.yml project file will look like this:

plugins:
  extractors:
  - name: tap-adwords
    variant: meltano
    config:
      customer_ids: 1234567890,1234567891
      start_date: '2020-10-01T00:00:00Z'

Sensitive values are most appropriately stored in the environment or your project's .env file:

export OAUTH_GOOGLE_ADWORDS_DEVELOPER_TOKEN=my_access_developer_token
export OAUTH_GOOGLE_ADWORDS_CLIENT_ID=my_oauth_client_id
export OAUTH_GOOGLE_ADWORDS_CLIENT_SECRET=my_oauth_client_secret
export TAP_ADWORDS_REFRESH_TOKEN=my_refresh_token

# Developer Token

Name: developer_token
Environment variable: OAUTH_GOOGLE_ADWORDS_DEVELOPER_TOKEN, alias: TAP_ADWORDS_DEVELOPER_TOKEN

See https://developers.google.com/adwords/api/docs/guides/first-api-call#request_a_developer_token.

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set developer_token <token>

export OAUTH_GOOGLE_ADWORDS_DEVELOPER_TOKEN=<token>

# OAuth Client ID

Name: oauth_client_id
Environment variable: OAUTH_GOOGLE_ADWORDS_OAUTH_CLIENT_ID, alias: TAP_ADWORDS_OAUTH_CLIENT_ID

See https://developers.google.com/adwords/api/docs/guides/first-api-call#set_up_oauth2_authentication.

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set oauth_client_id <client_id>

export OAUTH_GOOGLE_ADWORDS_OAUTH_CLIENT_ID=<client_id>

# OAuth Client Secret

Name: oauth_client_secret
Environment variable: OAUTH_GOOGLE_ADWORDS_OAUTH_CLIENT_SECRET, alias: TAP_ADWORDS_OAUTH_CLIENT_SECRET

See https://developers.google.com/adwords/api/docs/guides/first-api-call#set_up_oauth2_authentication.

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set oauth_client_secret <client_secret>

export OAUTH_GOOGLE_ADWORDS_OAUTH_CLIENT_SECRET=<client_secret>

# Refresh Token

Name: refresh_token
Environment variable: TAP_ADWORDS_REFRESH_TOKEN

See https://developers.google.com/adwords/api/docs/guides/first-api-call#get_an_oauth2_refresh_token_and_configure_your_client.

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set refresh_token <token>

export TAP_ADWORDS_REFRESH_TOKEN=<token>

# Customer ID(s)

Name: customer_ids
Environment variable: TAP_ADWORDS_CUSTOMER_IDS

One or more comma-separated Google Ads Account IDs to extract data from.

# How to get

To get your Account ID(s):

Visit the Google Ads management interface: https://ads.google.com/
Log in if you haven't already.
Make sure the correct account is selected in the top left corner.

Screenshot of account selector

You will see the Account ID displayed inside the selector to the right of the account name, with added dashes for readability.

Remove the dashes before you enter the ID in Meltano: 205-667-8813 becomes 2056678813.

If you want to extract data from multiple Ad Accounts, repeat the steps above to find the IDs (without dashes), and enter them in Meltano separated by commas (,).

For example:

One Account ID: 1234567890
Multiple Account IDs: 1234567890,1234567891,1234567892

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set customer_ids <ids>

export TAP_ADWORDS_CUSTOMER_IDS=<ids>

# Start Date

Name: start_date
Environment variable: TAP_ADWORDS_START_DATE

This property determines how much historical data will be extracted.

Please be aware that the larger the time period and amount of data, the longer the initial extraction can be expected to take.

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set start_date YYYY-MM-DDTHH:MM:SSZ

export TAP_ADWORDS_START_DATE=YYYY-MM-DDTHH:MM:SSZ

# For example:
meltano config tap-adwords set start_date 2020-10-01T00:00:00Z

export TAP_ADWORDS_START_DATE=2020-10-01T00:00:00Z

# End Date

Name: end_date
Environment variable: TAP_ADWORDS_END_DATE

Date up to when historical data will be extracted.

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set end_date YYYY-MM-DDTHH:MM:SSZ

export TAP_ADWORDS_END_DATE=YYYY-MM-DDTHH:MM:SSZ

# For example:
meltano config tap-adwords set end_date 2020-10-01T00:00:00Z

export TAP_ADWORDS_END_DATE=2020-10-01T00:00:00Z

# User Agent

Name: user_agent
Environment variable: TAP_ADWORDS_USER_AGENT
Default: tap-adwords via Meltano

User agent to send to Google along with API requests. Typically includes name of integration and an email address you can be reached at, e.g. tap-adwords via Meltano <user@example.com>.

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set user_agent <user_agent>

export TAP_ADWORDS_USER_AGENT=<user_agent>

# Conversion Window Days

Name: conversion_window_days
Environment variable: TAP_ADWORDS_CONVERSION_WINDOW_DAYS
Default: 0

How many Days before the Start Date to fetch data for Performance Reports

# How to use

Manage this setting using Meltano UI, meltano config, or an environment variable:

meltano config tap-adwords set conversion_window_days 7

export TAP_ADWORDS_CONVERSION_WINDOW_DAYS=7

# Primary Keys

Name: primary_keys
Environment variable: TAP_ADWORDS_PRIMARY_KEYS

Default:

{
  "KEYWORDS_PERFORMANCE_REPORT": ["customerID", "campaignID", "adGroupID", "keywordID", "day", "network", "device"],
  "AD_PERFORMANCE_REPORT": ["customerID", "campaignID", "adGroupID", "adID", "day", "network", "device"]
}

Primary Keys for the selected Entities (Streams)

# How to use

Manage this setting directly in your meltano.yml project file:

plugins:
  extractors:
  - name: tap-adwords
    variant: meltano
    config:
      primary_keys:
        <REPORT_NAME>: [<key1>, <key2>]
        # ...

Alternatively, manage this setting using meltano config or an environment variable:

meltano config tap-adwords set primary_keys <REPORT_NAME> '["<key>", ...]'

export TAP_ADWORDS_PRIMARY_KEYS='{"<REPORT_NAME>": ["<key>", ...], ...}'

# Once primary keys have been set in `meltano.yml`, environment variables can be used
# to override specific nested properties:
export TAP_ADWORDS_PRIMARY_KEYS_<REPORT_NAME>=='["<key>", ...]'

# For example:
meltano config tap-adwords set primary_keys KEYWORDS_PERFORMANCE_REPORT '["customerID"]'

export TAP_ADWORDS_PRIMARY_KEYS_KEYWORDS_PERFORMANCE_REPORT='["customerID"]'