{"id":24626654,"url":"https://github.com/chrisalvares/node-adwords","last_synced_at":"2025-04-05T00:10:23.610Z","repository":{"id":16838237,"uuid":"19597801","full_name":"ChrisAlvares/node-adwords","owner":"ChrisAlvares","description":"Adwords SDK for NodeJS","archived":false,"fork":false,"pushed_at":"2022-12-30T22:36:16.000Z","size":289,"stargazers_count":151,"open_issues_count":32,"forks_count":92,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-02-04T09:35:48.895Z","etag":null,"topics":["adwords","adwords-api","adwords-sdk","node-adwords","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"12moons/ec2-tags-env","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChrisAlvares.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-05-09T03:33:02.000Z","updated_at":"2023-10-26T09:53:24.000Z","dependencies_parsed_at":"2023-01-13T19:02:52.058Z","dependency_job_id":null,"html_url":"https://github.com/ChrisAlvares/node-adwords","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisAlvares%2Fnode-adwords","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisAlvares%2Fnode-adwords/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisAlvares%2Fnode-adwords/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisAlvares%2Fnode-adwords/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisAlvares","download_url":"https://codeload.github.com/ChrisAlvares/node-adwords/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266565,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adwords","adwords-api","adwords-sdk","node-adwords","nodejs"],"created_at":"2025-01-25T04:49:28.612Z","updated_at":"2025-04-05T00:10:23.591Z","avatar_url":"https://github.com/ChrisAlvares.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node Adwords Api\n\nThis is an unofficial Adwords sdk for NodeJS \u003e 6.0. This Api mirrors the official\napi pretty well so you can always look at the\n[Adwords documentation](https://developers.google.com/adwords/api/docs/reference/)\nand even the PHP sdk if something doesn't stand out.\n\nThis API is the first feature complete Adwords Api for Node.\n\nYou will need an Adwords developer token. Apply [here](https://developers.google.com/adwords/api/docs/guides/signup)\n\n## Getting Started\n\nThe main adwords user object follows the [auth](https://github.com/googleads/googleads-php-lib/blob/19.0.0/src/Google/Api/Ads/AdWords/auth.ini) parameters\nof the PHP library.\n\n```js\nconst AdwordsUser = require('node-adwords').AdwordsUser;\n\nlet user = new AdwordsUser({\n    developerToken: 'INSERT_DEVELOPER_TOKEN_HERE', //your adwords developerToken\n    userAgent: 'INSERT_COMPANY_NAME_HERE', //any company name\n    clientCustomerId: 'INSERT_CLIENT_CUSTOMER_ID_HERE', //the Adwords Account id (e.g. 123-123-123)\n    client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE', //this is the api console client_id\n    client_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE',\n    refresh_token: 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'\n});\n```\n\n## Usage\n\nThe following shows how to retrieve a list of campaigns. The biggest difference\nfrom the PHP library is the node library does not have special objects for\n`Selector` and `Page` and other entity types. It uses standard object notation.\n\n\n```js\nconst AdwordsUser = require('node-adwords').AdwordsUser;\nconst AdwordsConstants = require('node-adwords').AdwordsConstants;\n\nlet user = new AdwordsUser({...});\nlet campaignService = user.getService('CampaignService', 'v201809')\n\n//create selector\nlet selector = {\n    fields: ['Id', 'Name'],\n    ordering: [{field: 'Name', sortOrder: 'ASCENDING'}],\n    paging: {startIndex: 0, numberResults: AdwordsConstants.RECOMMENDED_PAGE_SIZE}\n}\n\ncampaignService.get({serviceSelector: selector}, (error, result) =\u003e {\n    console.log(error, result);\n})\n\n```\n\n## Reporting\n\nThe Adwords SDK also has a reporting endpoint, which is separate from\nthe `user.getService` endpoint since the reporting api is not part of the\nregular api.\n\n```js\nconst AdwordsReport = require('node-adwords').AdwordsReport;\n\nlet report = new AdwordsReport({/** same config as AdwordsUser above */});\nreport.getReport('v201809', {\n    reportName: 'Custom Adgroup Performance Report',\n    reportType: 'CAMPAIGN_PERFORMANCE_REPORT',\n    fields: ['CampaignId', 'Impressions', 'Clicks', 'Cost'],\n    filters: [\n        {field: 'CampaignStatus', operator: 'IN', values: ['ENABLED', 'PAUSED']}\n    ],\n    dateRangeType: 'CUSTOM_DATE', //defaults to CUSTOM_DATE. startDate or endDate required for CUSTOM_DATE\n    startDate: new Date(\"07/10/2016\"),\n    endDate: new Date(),\n    format: 'CSV' //defaults to CSV\n}, (error, report) =\u003e {\n    console.log(error, report);\n});\n```\n\nYou can also pass in additional headers in case you need to remove the header rows\n\n```js\nreport.getReport('v201809', {\n    ...\n    additionalHeaders: {\n        skipReportHeader: true,\n        skipReportSummary: true\n    }\n}, (error, report) =\u003e {\n    console.log(error, report);\n});\n```\n\n\n## Adwords Query Language (AWQL)\n\nIf you do not want to use the reporting / getters, you can also get the data via\nAWQL.\n\n```js\nconst AdwordsUser = require('node-adwords').AdwordsUser;\nconst AdwordsConstants = require('node-adwords').AdwordsConstants;\n\nlet user = new AdwordsUser({...});\nlet campaignService = user.getService('CampaignService')\n\nlet params = {\n    query: 'SELECT Id, Name WHERE Status = \"ENABLED\" ORDER BY Name DESC LIMIT 0,50'\n};\n\ncampaignService.get(params, (error, result) =\u003e {\n    console.log(error, result);\n})\n```\n\nYou can also use AWQL with Performance Reports\n\n```js\nlet report = new AdwordsReport({/** same config as AdwordsUser above */});\nreport.getReport('v201809', {\n    query: 'SELECT Criteria FROM KEYWORDS_PERFORMANCE_REPORT DURING 20170101,20170325',\n    format: 'CSV'\n});\n\n\n```\n## Authentication\nInternally, the node-adwords sdk use the [official google api client](https://github.com/google/google-api-nodejs-client)\nfor authenticating users. Using the `https://www.googleapis.com/auth/adwords` scope.\nThe node-adwords sdk has some helper methods for you to authenticate if you do not\nneed additional scopes.\n\n```js\nconst AdwordsAuth = require('node-adwords').AdwordsAuth;\n\nlet auth = new AdwordsAuth({\n    client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE', //this is the api console client_id\n    client_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE'\n}, 'https://myredirecturlhere.com/adwords/auth' /** insert your redirect url here */);\n\n//assuming express\napp.get('/adwords/go', (req, res) =\u003e {\n    res.redirect(auth.generateAuthenticationUrl());\n})\n\napp.get('/adwords/auth', (req, res) =\u003e {\n    auth.getAccessTokenFromAuthorizationCode(req.query.code, (error, tokens) =\u003e {\n        //save access and especially the refresh tokens here\n    })\n});\n\n```\n\n# Troubleshooting\n\n## Adwords.Types\nSometimes, in the Adwords documentation, you will see \"Specify xsi:type instead\".\nAs of version 201609.1.0, you can specify this in the request as another attribute.\n\n```js\nlet operation = {\n    operator: 'ADD',\n    operand: {\n        campaignId: '1234567',\n        criterion: {\n            type: 'IP_BLOCK',\n            'xsi:type': 'IpBlock',\n            ipAddress: '123.12.123.12',\n        },\n        'xsi:type': 'NegativeCampaignCriterion'\n    }\n}\n```\n\n## Ordering\nBecause the Adwords Api uses a non-standard SOAP implementation, the order of the\nelements are required to be in the order of the elements in the documentation.\nWhen drafting api calls, make sure the order matches the order in the documentation.\nFor more information, see [issue #20](https://github.com/ChrisAlvares/node-adwords/issues/20)\n\n```js\n//this will work\nlet operation = {\n    operator: 'ADD',\n    operand: {\n     ....\n    }\n}\n```\n\n```js\n//this will not work\nlet operation = {\n    operand: {\n     ....\n    },\n    operator: 'ADD',\n}\n```\n\n\n## Testing\nFor testing, you will need a refresh token as well as a developer token.\nThese should be placed as environmental variables:\n\n```\n$ ADWORDS_API_TEST_DEVTOKEN=123453152342352352\n$ ADWORDS_API_TEST_REFRESHTOKEN=INSERT_OAUTH2_REFRESH_TOKEN_HERE\n$ ADWORDS_API_TEST_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE\n$ ADWORDS_API_TEST_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE\n$ ADWORDS_API_TEST_CLIENT_CUSTOMER_ID=INSERT_CLIENT_CUSTOMER_ID_HERE\n\n$ npm test\n```\n\n## Credits\nWhile this is not a fork of\nthe [googleads-node-lib library](https://github.com/ErikEvenson/googleads-node-lib/), it\ndid help with some debugging while creating this one.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisalvares%2Fnode-adwords","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrisalvares%2Fnode-adwords","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisalvares%2Fnode-adwords/lists"}