Skip to main content
Version: 1.4.0 (latest)

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.

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:

NameDescription
customersBusinesses or individuals who pay to advertise their products
campaignsStructured sets of ad groups and advertisements
change_eventsModifications made to an account's ads, campaigns, and related settings
customer_clientsAccounts that are managed by a given account

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:​

note

For service account authentication, use the client_email. For OAuth authentication, use the email associated with the app creation and refresh token generation.

  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.

For more information, read the guide on how to add a verified source.

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)

Additional Setup guides​

This demo works on codespaces. Codespaces is a development environment available for free to anyone with a Github account. You'll be asked to fork the demo repository and from there the README guides you with further steps.
The demo uses the Continue VSCode extension.

Off to codespaces!

DHelp

Ask a question

Welcome to "Codex Central", your next-gen help center, driven by OpenAI's GPT-4 model. It's more than just a forum or a FAQ hub – it's a dynamic knowledge base where coders can find AI-assisted solutions to their pressing problems. With GPT-4's powerful comprehension and predictive abilities, Codex Central provides instantaneous issue resolution, insightful debugging, and personalized guidance. Get your code running smoothly with the unparalleled support at Codex Central - coding help reimagined with AI prowess.