import Header from './_source-info-header.md';

Google ads#

Google Ads is a digital advertising service by Google that allows advertisers to display ads across Google's search results, websites, and other platforms.

:::warning Alert!
Please note that we are unable to conduct regular testing on the specified source due to difficulties in obtaining the necessary credentials. We confirmed this source works at creation, and it is being used by the community. We anticipate that the source should operate smoothly over time given Google's best practices in versioning APIs.
:::

This Google Ads dlt verified source and pipeline example loads data using the "Google Ads API" to the destination of your choice.

Resources that can be loaded using this verified source are:

Setup guide#

Grab credentials#

To access Google Ads verified sources, you'll need a developer token. For instructions on obtaining one, you can search online or ask GPT.

Next, there are two methods to get authenticated for using this verified source:

• OAuth credentials
• Service account credentials

Let's go over how to set up both OAuth tokens and service account credentials. In general, OAuth tokens are preferred when user consent is required, while service account credentials are better suited for server-to-server interactions. You can choose the method of authentication as per your requirement.

Grab Google service account credentials#

You need to create a GCP service account to get API credentials if you don't have one. To create one, follow these steps:

1. Sign in to console.cloud.google.com.

2. Create a service account if needed.

3. Enable the "Google Ads API". Refer to the Google documentation for comprehensive instructions on this process.

4. Generate credentials:

   1. Navigate to IAM & Admin in the console's left panel, and then select Service Accounts.
   2. Identify the service account you intend to use, and click on the three-dot menu under the "Actions" column next to it.
   3. Create a new JSON key by selecting "Manage Keys" > "ADD KEY" > "CREATE".
   4. You can download the ".json" file containing the necessary credentials for future use.

Grab Google OAuth credentials#

You need to create a GCP account to get OAuth credentials if you don't have one. To create one,
follow these steps:

1. Ensure your email used for the GCP account has access to the GA4 property.

2. Open a GCP project in your GCP account.

3. Enable the Google Ads API in the project.

4. Search for credentials in the search bar and go to Credentials.

5. Go to Credentials -> OAuth client ID -> Select Desktop App from the Application type and give an
   appropriate name.

6. Download the credentials and fill in "client_id", "client_secret", and "project_id" in
   "secrets.toml".

7. Go back to credentials and select the OAuth consent screen on the left.

8. Fill in the App name, user support email (your email), authorized domain (localhost.com), and dev
   contact info (your email again).

9. Add the following scope:

   ⧉

   "https://www.googleapis.com/auth/adwords"
   

10. Add your email as a test user.

After configuring "client_id", "client_secret", and "project_id" in "secrets.toml", to generate the
refresh token, run the following script from the root folder:

python google_ads/setup_script_gcp_oauth.py

Once you have executed the script and completed the authentication, you will receive a "refresh
token" that can be used to set up the "secrets.toml".

Share the Google Ads account with the API:#

1. Log into your Google Ads account.

2. Select the Google Ads account you want to access.

3. Click on the "Tools & Settings" icon in the upper right corner of the screen.

4. Under ‘Setup’, choose 'Account access' from the menu.

5. Click the blue “+” icon to add a new user.

6. Enter the email address associated with either the service account (for service account authentication)
   or the email used during app creation and refresh token generation (for OAuth authentication).

7. Assign the appropriate access level; for API purposes, 'Read-only' access might suffice if you only need data
   retrieval capabilities. However, if using a service account, you might need to give 'Admin' access since service
   accounts usually perform tasks requiring higher privileges.

8. Conclude the process by clicking the “Send invitation” button.

Initialize the verified source#

To get started with your data pipeline, follow these steps:

1. Enter the following command:

   ⧉

   dlt init google_ads duckdb
   

   This command will initialize
   the pipeline example
   with Google Ads as the source and
   duckdb as the destination.

2. If you'd like to use a different destination, simply replace duckdb with the name of your
   preferred destination.

3. After running this command, a new directory will be created with the necessary files and
   configuration settings to get started.

Add credentials#

1. In the .dlt folder, there's a file called secrets.toml. It's where you store sensitive
   information securely, like access tokens. Keep this file safe. In this file, set up the "developer
   token", "customer ID", and "impersonated_email" as follows:

   ⧉

   [sources.google_ads]
   dev_token = "please set me up!"
   customer_id = "please set me up!"
   impersonated_email = "please set me up"
   

   • dev_token is the developer token that lets you connect to the Google Ads API.
   • customer_id in Google Ads is a unique three-part number (formatted as XXX-XXX-XXXX) that identifies
     and helps manage individual Google Ads accounts. It is used for API access and account operations, and
     is visible in the top right corner of your Google Ads dashboard.
   • impersonated_email enables secure access to Google Ads accounts through the API using a service account,
     while leveraging the permissions of a specific user within the Ads platform.

2. Next, for service account authentication:

   ⧉

   [sources.google_ads.credentials]
   project_id = "project_id" # please set me up!
   client_email = "client_email" # please set me up!
   private_key = "private_key" # please set me up!
   

3. From the ".json" that you
   downloaded earlier,
   copy project_id, private_key,
   and client_email under [sources.google_ads.credentials].

4. Alternatively, if you're using OAuth credentials, replace the fields and values with those
   you grabbed for OAuth credentials.

5. The secrets.toml for OAuth authentication looks like:

   ⧉

   [sources.google_ads.credentials]
   client_id = "client_id" # please set me up!
   client_secret = "client_secret" # please set me up!
   refresh_token = "refresh_token" # please set me up!
   project_id = "project_id" # please set me up!
   

6. Finally, enter credentials for your chosen destination as per the docs.

Run the pipeline#

1. Before running the pipeline, ensure that you have installed all the necessary dependencies by
   running the command:
   ⧉

   pip install -r requirements.txt
   

2. You're now ready to run the pipeline! To get started, run the following command:
   ⧉

   python google_ads_pipeline.py
   

3. Once the pipeline has finished running, you can verify that everything loaded correctly by using
   the following command:
   ⧉

   dlt pipeline <pipeline_name> show
   

   For example, the pipeline_name for the above pipeline example is
   dlt_google_ads_pipeline, you may also use any custom name instead.

For more information, read the guide on how to run a pipeline.

Sources and resources#

dlt works on the principle of sources and
resources.

Source google_ads#

This function returns a list of resources including metadata, fields, and metrics data from
the Google Ads API.

@dlt.source()
def google_ads(
    credentials: Union[
        GcpOAuthCredentials, GcpServiceAccountCredentials
    ] = dlt.secrets.value,
    impersonated_email: str = dlt.secrets.value,
    dev_token: str = dlt.secrets.value,
) -> List[DltResource]:
   """
   Initializes a client with the provided credentials and development token to
   load default tables from Google Ads into the database. This function returns
   various resources such as customers, campaigns, change events, and customer
   clients.
   """

credentials: GCP OAuth or service account credentials.

impersonated_email: enables secure access to Google Ads accounts through the API using a service account,
while leveraging the permissions of a specific user within the Ads platform.

dev_token: A developer token, which is required to access the Google Ads API.

Resource customers#

This function retrieves all dimensions for a report from a Google Ads project.

@dlt.resource(write_disposition="replace")
def customers(
    client: Resource, customer_id: str = dlt.secrets.value
) -> Iterator[TDataItem]:
    """
    Fetches customer data from the Google Ads service and
    yields each customer as a dictionary.
    """

client: Refers to a Google API Resource object used to interact with Google services.

customer_id: Individual identifier for a Google Ads account.

Similarly, there are resource functions called campaigns, change_events, and customer_clients that populate
respective dimensions.

Customization#

Create your own pipeline#

If you wish to create your own pipelines, you can leverage source and resource methods from this
verified source.

1. Configure the pipeline by specifying the pipeline name, destination, and dataset as follows:

   ⧉

   pipeline = dlt.pipeline(
       pipeline_name="dlt_google_ads_pipeline", # Use a custom name if desired
       destination="duckdb", # Choose the appropriate destination (e.g., duckdb, redshift, post)
       dataset_name="full_load_google_ads" # Use a custom name if desired
   )
   

   To read more about pipeline configuration, please refer to our
   documentation.

2. To load all the dimensions from Google Ads:

   ⧉

   data_default = google_ads()
   info = pipeline.run(data=[data_default])
   print(info)
   

3. To load the data from customers and campaigns:

   ⧉

   data_selected = google_ads().with_resources("customers", "campaigns")
   info = pipeline.run(data=[data_default])
   print(info)