Node Adwords Api

This is an unofficial Adwords sdk for NodeJS > 6.0. This Api mirrors the official api pretty well so you can always look at the Adwords documentation and even the PHP sdk if something doesn't stand out.

This API is the first feature complete Adwords Api for Node.

You will need an Adwords developer token. Apply here

Getting Started

The main adwords user object follows the auth parameters of the PHP library.

constAdwordsUser=require('node-adwords').AdwordsUser;letuser=newAdwordsUser({developerToken: 'INSERT_DEVELOPER_TOKEN_HERE',//your adwords developerTokenuserAgent: 'INSERT_COMPANY_NAME_HERE',//any company nameclientCustomerId: 'INSERT_CLIENT_CUSTOMER_ID_HERE',//the Adwords Account id (e.g. 123-123-123)client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE',//this is the api console client_idclient_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE',refresh_token: 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'});

Usage

The following shows how to retrieve a list of campaigns. The biggest difference from the PHP library is the node library does not have special objects for Selector and Page and other entity types. It uses standard object notation.

constAdwordsUser=require('node-adwords').AdwordsUser;constAdwordsConstants=require('node-adwords').AdwordsConstants;letuser=newAdwordsUser({...});letcampaignService=user.getService('CampaignService','v201710')//create selectorletselector={fields: ['Id','Name'],ordering: [{field: 'Name',sortOrder: 'ASCENDING'}],paging: {startIndex: 0,numberResults: AdwordsConstants.RECOMMENDED_PAGE_SIZE}}campaignService.get({serviceSelector: selector},(error,result)=>{console.log(error,result);})

Reporting

The Adwords SDK also has a reporting endpoint, which is separate from the user.getService endpoint since the reporting api is not part of the regular api.

constAdwordsReport=require('node-adwords').AdwordsReport;letreport=newAdwordsReport({/** same config as AdwordsUser above */});report.getReport('v201710',{reportName: 'Custom Adgroup Performance Report',reportType: 'CAMPAIGN_PERFORMANCE_REPORT',fields: ['CampaignId','Impressions','Clicks','Cost'],filters: [{field: 'CampaignStatus',operator: 'IN',values: ['ENABLED','PAUSED']}],dateRangeType: 'CUSTOM_DATE',//defaults to CUSTOM_DATE. startDate or endDate required for CUSTOM_DATEstartDate: newDate("07/10/2016"),endDate: newDate(),format: 'CSV'//defaults to CSV},(error,report)=>{console.log(error,report);});

You can also pass in additional headers in case you need to remove the header rows

report.getReport('v201710',{
...
additionalHeaders: {skipReportHeader: true,skipReportSummary: true}},(error,report)=>{console.log(error,report);});

Adwords Query Language (AWQL)

If you do not want to use the reporting / getters, you can also get the data via AWQL.

constAdwordsUser=require('node-adwords').AdwordsUser;constAdwordsConstants=require('node-adwords').AdwordsConstants;letuser=newAdwordsUser({...});letcampaignService=user.getService('CampaignService')letparams={query: 'SELECT Id, Name WHERE Status = "ENABLED" ORDER BY Name DESC LIMIT 0,50'};campaignService.get(params,(error,result)=>{console.log(error,result);})

You can also use AWQL with Performance Reports

letreport=newAdwordsReport({/** same config as AdwordsUser above */});report.getReport('v201710',{query: 'SELECT Criteria FROM KEYWORDS_PERFORMANCE_REPORT DURING 20170101,20170325',format: 'CSV'});

Authentication

Internally, the node-adwords sdk use the official google api client for authenticating users. Using the https://www.googleapis.com/auth/adwords scope. The node-adwords sdk has some helper methods for you to authenticate if you do not need additional scopes.

constAdwordsAuth=require('node-adwords').AdwordsAuth;letauth=newAdwordsAuth({client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE',//this is the api console client_idclient_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE'},'https://myredirecturlhere.com/adwords/auth'/** insert your redirect url here */);//assuming expressapp.get('/adwords/go',(req,res)=>{res.redirect(auth.generateAuthenticationUrl());})app.get('/adwords/auth',(req,res)=>{auth.getAccessTokenFromAuthorizationCode(req.query.code,(error,tokens)=>{//save access and especially the refresh tokens here})});

Troubleshooting

Adwords.Types

Sometimes, in the Adwords documentation, you will see "Specify xsi:type instead". As of version 201609.1.0, you can specify this in the request as another attribute.

letoperation={operator: 'ADD',operand: {campaignId: '1234567',criterion: {type: 'IP_BLOCK','xsi:type': 'IpBlock',ipAddress: '123.12.123.12',},'xsi:type': 'NegativeCampaignCriterion'}}

Ordering

Because the Adwords Api uses a non-standard SOAP implementation, the order of the elements are required to be in the order of the elements in the documentation. When drafting api calls, make sure the order matches the order in the documentation. For more information, see issue #20

//this will workletoperation={operator: 'ADD',operand: {
....}}

//this will not workletoperation={operand: {
....},operator: 'ADD',}

Testing

For testing, you will need a refresh token as well as a developer token. These should be placed as environmental variables:

$ ADWORDS_API_TEST_DEVTOKEN=123453152342352352
$ ADWORDS_API_TEST_REFRESHTOKEN=INSERT_OAUTH2_REFRESH_TOKEN_HERE
$ ADWORDS_API_TEST_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
$ ADWORDS_API_TEST_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
$ ADWORDS_API_TEST_CLIENT_CUSTOMER_ID=INSERT_CLIENT_CUSTOMER_ID_HERE
$ npm test

Credits

While this is not a fork of the googleads-node-lib library, it did help with some debugging while creating this one.