achselschweisz / google-ads-api

Google Ads API Client Library for JavaScript

Google Ads API

Unofficial Google Ads API client library for Node

Features

• Simple and easy to use API
• Uses gRPC and Protocol Buffers internally (recommended by Google)
• Typescript definitions for all Google Ads API resources, enums and errors

The Google Ads API is the new replacement to the AdWords API. Google will deprecate the AdWords API sometime in 2020.

Installation

$ yarn add google-ads-api

Documentation

You can find the full documentation here.

The documentation is divided into two main sections:

• General concepts for general usage of this library.
• Core resources for the specific fields and methods available per resource.

You can improve the documentation by sending pull requests with edits to these files. More instructions here. All help and feedback welcome!

Basic Example

import { GoogleAdsApi, types, enums } from 'google-ads-api'

// 1. Create a new client with your credentials
const client = new GoogleAdsApi({
    client_id: '<CLIENT_ID>',
    client_secret: '<CLIENT_SECRET>',
    developer_token: '<DEVELOPER_TOKEN>',
})

// 2. Load a customer with a valid CID & authentication
const customer = client.Customer({
    customer_account_id: '<CUSTOMER_ACCOUNT_ID>',
    refresh_token: '<REFRESH_TOKEN>',
})

// 3. Use the query method for querying customer data
const response = await customer.query(`
    SELECT 
        ad_group.id,
        ad_group.name,
        metrics.clicks,
        segments.device
    FROM 
        ad_group
    WHERE 
        metrics.impressions > 10
        AND segments.date DURING LAST_30_DAYS
    LIMIT 5
`)

// 4. Inspect the data and benefit from ts definitions
for (const row of response) {
    const { ad_group, metrics } = row
    if (ad_group.status === enums.AdGroupStatus.ENABLED) {
        console.log(`Ad group "${ad_group.name}" had ${metrics.clicks} clicks.`)
    }
}

// 5. Create a new campaign
const campaign = {
    name: 'New Campaign',
    campaign_budget: 'customers/123/campaignBudgets/123',
    advertising_channel_type: enums.AdvertisingChannelType.SEARCH,
    status: enums.CampaignStatus.PAUSED,
}

const { results } = await customer.campaigns.create(campaign)

const new_campaign_resource_name = results[0]

// 6. ...modify it...
await customer.campaigns.update({
    resource_name : new_campaign_resource_name,
    name : 'New Campaign EDITED' 
})

// 7. ...and delete it.
await customer.campaigns.delete(new_campaign_resource_name)

More examples

There are many more examples in the full documentation.

You can also find a couple ready-to-run examples in the /examples directory.