You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies



Google Ads API Report Fetcher (gaarf)

Version published
Weekly downloads
increased by185.89%
Weekly downloads



Google Ads API Report Fetcher (gaarf)

Node.js version of Google Ads API Report Fetcher tool a.k.a. gaarf. Please see the full documentation in the root README.

Supports Ads API v16.

Table of content


You need Node.js to run the tool. v16 should be sufficient.

Command Line

Install globally

npm i ads-api-report-fetcher -g

then you can run the tool with gaarf and gaarf-bq commands:

gaarf <files> [options]

Documentation on available options see in the root

Running from folder

If you cloned the repo into "ads-api-fetcher" folder, then run npm i --production in ads-api-fetcher/js folder, after than we can run the tool directly:

ads-api-fetcher/js/gaarf <files> [options]


node ads-api-fetcher/js/dist/cli.js <files> [options]

Config files

Besides passing options explicitly (see the root for full description) you can use config files. By default the tool will try to find .gaarfrc starting from the current folder up to the root. If found, options from that file will be used if they weren't supplied via command line.

Example of .gaarfrc:

 "ads-config": ".config/google-ads.yaml",
 "output": "bq",
 "csv.destination-folder": "output",
 "macro": {
   "start_date": "2022-01-01",
   "end_date": "2022-02-10"
 "account": 1234567890,
 "bq.project": "myproject",
 "bq.dataset": "mydataset",
 "bq.dump-schema": true

Please note that options with nested values, like 'bq.project', can be specified either as objects (see "macro") or as flatten names ("bq.project").

Besides an implicitly used .rc-files you can specify a config file explicitly via --config option. In that case options from --config file will be merge with a .rc file if one exists. Via --config option you can also provide a YAML file (as alternative to JSON) with a similar structure: gaarf <files> --config=gaarf.yaml

Example of a yaml config:

ads-config: .config/google-ads.yaml
output: bq
csv.destination-folder: output
  start_date: 2022-01-01
  end_date: :YYYYMMDD
account: 1234567890
bq.project: myproject
bq.dataset: mydataset

Similarly a config file can be provided for the gaarf-bq tool:

gaarf-bq bq-queries/*.sql --config=gaarf-bq.yaml

(again it can be either YAML or JSON)

Ads API config

There are two mechanisms for supplying Ads API configuration (developer token, etc ). Either via a separated yaml-file whose name is set in ads-config argument or via separated CLI arguments starting ads.* (e.g. --ads.client_id) or in a config file (ads object):

 "ads": {
   "client_id": "...",
   "developer_token": ".."
 "output": "bq",

Such a yaml-file is a standard way to configure Ads API Python client - see example.

If neither ads-config argument nor ads.* arguments were provider then the tool will search for a local file "google-ads.yaml" and if it exists it will be used.

See more help with --help option.


How to use Gaarf as a library in your own code. First you need to create an instance of GoogleAdsApiClient which represents the Ads API (it's a tiny wrapper around Opteo/google-ads-api library - open-source Ads API client for NodeJS).

NOTE: there is no an official Ads API client for NodeJS from Google, but the Opteo's client is a result of collaboration between Opteo and Google, so it's kinda a semi-official client.

GoogleAdsApiClient expects an object with Ads API access settings (TS-interface GoogleAdsApiConfig). You can construct it manually or load from a yaml or json file (e.g. google-ads.yaml) using loadAdsConfigFromFile function.

import {
  from 'ads-api-report-fetcher';

const adsConfig = await loadAdsConfigFromFile('google-ads.yaml');
const client = new GoogleAdsApiClient(adsConfig);
let customers = await client.getCustomerIds();
let writer = new CsvWriter('.tmp');
let executor = new AdsQueryExecutor(client);
let params = {};
let scriptPaths = ['list of sql files'];
for (let scriptPath of scriptPaths) {
  let queryText = fs.readFileSync(scriptPath, 'utf-8');
  let scriptName = path.basename(scriptPath).split('.sql')[0];
  await executor.execute(scriptName, queryText, customers, params, writer);

If you need to process results from queries (and not just rely on a writer) then use executeGen method (it's a async generator):

  let results = await executor
    .executeGen(scriptName, queryText, customers, params, writer);
  for await (let res of results) {
    //res.rows - array of rows for one customer

Alternatively you can incorporate keepData option of the BigQueryWriter:

  let writer =
      new BigQueryWriter(projectId, dataset, {keepData: true});
  await executor.execute(scriptName, queryText, customers, macroParams, writer);

thanks to keepData you will be able access the writer.rowsByCustomer property with a map of customer id to rows with data.

To execute a single query for a single customer use executeOne method:

  let query = executor.parseQuery(queryText, params);
  let result = await executor.executeOne(query, customerId);


Run typescript directly

node -r ./node_modules/ts-node/register src/cli.ts ...



Package last updated on 31 May 2024

Did you know?


Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc