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.

Table of content

- Overview
- Command Line
- Install globally
- Running from folder
- Config files
- Ads API config
- Library
- Development

Overview

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

Command Line

$3

``shell
npm i google-ads-api-report-fetcher -g
`

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

`shell
gaarf [options]
`

If you have both versions install (Python and Node) you can run the Node-version explicitly via gaarf-node alias.

Documentation on available options see in the root README.md.

$3

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:

`shell
ads-api-fetcher/js/gaarf [options]
`

or

`shell
node ads-api-fetcher/js/dist/cli.js [options]
`

$3

Besides passing options explicitly (see the root README.me 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:

`json
{
"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 --config=gaarf.yaml

Example of a yaml config:

`yaml
ads-config: .config/google-ads.yaml
output: bq
csv.destination-folder: output
macro:
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):

`json
{
"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.

Library

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.

`ts
import {
GoogleAdsApiClient,
AdsQueryExecutor,
loadAdsConfigFromFile,
CsvWriter,
} from 'google-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):

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

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

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

Development

$3

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

License

Apache-2.0

Disclaimer

This is not an officially supported Google product.