| Name | adsctl JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | |
| Summary | Google Ads Control CLI and Prompt |
| upload_time | 2023-07-25 13:47:32 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
cli
google ads
google ads api
prompt
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Google Ads API CLI and Prompt
<p align="center">
<a href="https://pypi.org/project/adsctl/">
<img src="https://img.shields.io/pypi/v/adsctl.svg">
</a>
<a href="https://pypi.org/project/mkdocs-jupyter">
<img src="https://img.shields.io/pypi/pyversions/adsctl.svg">
</a>
<a href="https://github.com/danielfrg/adsctl/actions/workflows/test.yml">
<img src="https://github.com/danielfrg/adsctl/workflows/test/badge.svg">
</a>
</a>
<a href="https://github.com/danielfrg/adsctl/blob/main/LICENSE.txt">
<img src="https://img.shields.io/:license-Apache%202-blue.svg">
</a>
</p>
Google Ads Interface for humans.
_This is a work in progress, please open an issue if you find any bugs or have any suggestions._
Features:
- A command line tool for executing GAQL queries against the Google Ads API.
Like [psql](https://www.postgresql.org/docs/current/app-psql.html) for the Google Ads API.
- A command line tool for managing Google Ads resources.
Like [kubectl](https://kubernetes.io/docs/reference/kubectl/) for the Google Ads API.
- Centralized configuration with multiple account management
- Automatically update refresh token
- Python API with Pandas integration
## Installation
```shell
pip install adsctl
```
## Getting started
Requirements:
- All the requirements to use the Google Ads API including a Developer Token and OAuth2 credentials
- See [Google Ads API Quickstart](https://developers.google.com/google-ads/api/docs/first-call/overview) for more details.
### Configuration
This project manages it's own configuration files.
To create the configuration file run:
```shell
adsctl config
# Open the location of the config files
adsctl config explore
```
Open the new default config file and fill it with your credentials:
Dev Token, Client ID, Client Secret and Customer ID.
To login and get a refresh token:
```shell
adsctl auth <path-to-secret.json>
```
The token is saved automatically in the config file.
You can see it by running:
```shell
# View config
adsctl config view
```
### Multiple Accounts
You can manage multiple accounts in the config file by adding TOML sections.
```toml
current_account = "default"
[... default account ...]
[accounts.another]
developer_token = ""
customer_id = ""
login_customer_id = ""
[accounts.another.oauth]
client_id = ""
client_secret = ""
```
Set the current account:
```shell
$ adsctl config set-account another
$ adsctl config get-account
another
```
## GAQL Prompt
An interactive shell for executing GAQL queries against the Google Ads API.
```shell
$ gaql
>>> SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id
+----+-----------------------------+---------+-------------+
| | resourceName | name | id |
|----+-----------------------------+---------+-------------|
| 0 | customers/XXX/campaigns/YYY | name1 | 10000000000 |
| 1 | customers/XXX/campaigns/YYY | name2 | 10000000000 |
| 2 | customers/XXX/campaigns/YYY | name3 | 10000000000 |
+----+-----------------------------+---------+-------------+
```
By default it uses the it in `table` format but you can control the output
format with the `-o` option:
```shell
# Print the plain protobuf response
$ gaql -o plain
# Print the contents of a CSV file
$ gaql -o csv
```
You can also run a single inline command and redirect the output to a file:
```shell
gaql -c 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id' -o csv > my-query.csv
```
This assumes only table is returned but in more complex queries that include other
resources or when using metrics or segments multiple tables are created.
On those cases use the -o csv-files flag to save each table to a different file
based on the table name.
```shell
$ gaql -c 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id' -o csv-files
$ ls
campaign.csv
```
### Query variables
You can specify one or more variables using the jinja syntax, those
variables will be replaced with the values specified in the `-v` options.
```shell
gaql -c 'SELECT campaign.id, campaign.name FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id' -v id=123456789
```
You can also pass `-v` without a command and use this the variables in the prompt
queries:
```shell
$ gaql -v id=123456789 -v field=name
>>> SELECT campaign.id, campaign.{{ field }} FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id
```
### Other options
You can overwrite the account and customer ID using the `-a` and `-i` options.
See `gaql --help` for more details.
## CLI
### Campaign Management
#### Get campaigns
````shell
```shell
adsctl get campaign
````
```plain
Name Status Id
-------------------------------------------- -------- -----------
Interplanetary Cruise Campaign #168961427368 Paused 20370195066
Interplanetary Cruise Campaign #168961215970 Paused 20379497161
```
#### Status Management
```shell
adsctl edit campaign -i <campaign-id> status enabled
adsctl edit campaign -i 20370195066 status enabled
```
```shell
adsctl get campaign
```
```plain
Name Status Id
-------------------------------------------- -------- -----------
Interplanetary Cruise Campaign #168961427368 Enabled 20370195066
Interplanetary Cruise Campaign #168961215970 Paused 20379497161
```
#### Update budget
```shell
adsctl edit campaign -i <campaign-id> budget <amount>
```
## Python API
You can also use the Python API to easily execute GAQL queries
and get the results as a Python dict or pandas DataFrame.
```python
import adsctl as ads
# Read config file and creates the Google Ads client
google_ads = ads.GoogleAds()
# Execute GAQL query
get_campaigns_query = """
SELECT campaign.name,
campaign_budget.amount_micros,
campaign.status,
campaign.optimization_score,
campaign.advertising_channel_type,
metrics.clicks,
metrics.impressions,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros,
campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
AND campaign.status != '{{ status }}'
"""
tables = google_ads.query(get_campaigns_query, params={"status": "REMOVED"}})
# Print Pandas DataFrames
for table_name, table in tables.items():
print(table_name)
print(table, "\n")
```
```plain
campaign
resourceName status ... name optimizationScore
0 customers/XXXXXXXXXX/campaigns/YYYYYYYYYYY ENABLED ... my-campaign 0.839904
[1 rows x 6 columns]
metrics
clicks costMicros ctr averageCpc impressions
0 210 6730050 0.011457 32047.857143 18330
campaignBudget
resourceName amountMicros
0 customers/XXXXXXXXXX/campaignBudgets/ZZZZZZZZZZZ 1000000
```
## Disclaimer
_This is not an official Google product_.
This repository is maintained by a Googler but is not a supported Google product.
Code and issues here are answered by maintainers and other community members on GitHub on a best-effort basis.
Raw data
{
"_id": null,
"home_page": "",
"name": "adsctl",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "cli,google ads,google ads api,prompt",
"author": "",
"author_email": "Daniel Rodriguez <daniel@danielfrg.com>",
"download_url": "https://files.pythonhosted.org/packages/d6/27/4c2a012014a868a19951bffd60bc82ca2e06cdff18aa90c56eaf138637e2/adsctl-0.4.1.tar.gz",
"platform": null,
"description": "# Google Ads API CLI and Prompt\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/adsctl/\">\n <img src=\"https://img.shields.io/pypi/v/adsctl.svg\">\n </a>\n <a href=\"https://pypi.org/project/mkdocs-jupyter\">\n <img src=\"https://img.shields.io/pypi/pyversions/adsctl.svg\">\n </a>\n <a href=\"https://github.com/danielfrg/adsctl/actions/workflows/test.yml\">\n <img src=\"https://github.com/danielfrg/adsctl/workflows/test/badge.svg\">\n </a>\n </a>\n <a href=\"https://github.com/danielfrg/adsctl/blob/main/LICENSE.txt\">\n <img src=\"https://img.shields.io/:license-Apache%202-blue.svg\">\n </a>\n</p>\n\nGoogle Ads Interface for humans.\n\n_This is a work in progress, please open an issue if you find any bugs or have any suggestions._\n\nFeatures:\n\n- A command line tool for executing GAQL queries against the Google Ads API.\n Like [psql](https://www.postgresql.org/docs/current/app-psql.html) for the Google Ads API.\n- A command line tool for managing Google Ads resources.\n Like [kubectl](https://kubernetes.io/docs/reference/kubectl/) for the Google Ads API.\n- Centralized configuration with multiple account management\n- Automatically update refresh token\n- Python API with Pandas integration\n\n## Installation\n\n```shell\npip install adsctl\n```\n\n## Getting started\n\nRequirements:\n\n- All the requirements to use the Google Ads API including a Developer Token and OAuth2 credentials\n- See [Google Ads API Quickstart](https://developers.google.com/google-ads/api/docs/first-call/overview) for more details.\n\n### Configuration\n\nThis project manages it's own configuration files.\nTo create the configuration file run:\n\n```shell\nadsctl config\n\n# Open the location of the config files\nadsctl config explore\n```\n\nOpen the new default config file and fill it with your credentials:\nDev Token, Client ID, Client Secret and Customer ID.\n\nTo login and get a refresh token:\n\n```shell\nadsctl auth <path-to-secret.json>\n```\n\nThe token is saved automatically in the config file.\nYou can see it by running:\n\n```shell\n# View config\nadsctl config view\n```\n\n### Multiple Accounts\n\nYou can manage multiple accounts in the config file by adding TOML sections.\n\n```toml\ncurrent_account = \"default\"\n\n[... default account ...]\n\n[accounts.another]\ndeveloper_token = \"\"\ncustomer_id = \"\"\nlogin_customer_id = \"\"\n\n[accounts.another.oauth]\nclient_id = \"\"\nclient_secret = \"\"\n```\n\nSet the current account:\n\n```shell\n$ adsctl config set-account another\n$ adsctl config get-account\nanother\n```\n\n## GAQL Prompt\n\nAn interactive shell for executing GAQL queries against the Google Ads API.\n\n```shell\n$ gaql\n\n>>> SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id\n+----+-----------------------------+---------+-------------+\n| | resourceName | name | id |\n|----+-----------------------------+---------+-------------|\n| 0 | customers/XXX/campaigns/YYY | name1 | 10000000000 |\n| 1 | customers/XXX/campaigns/YYY | name2 | 10000000000 |\n| 2 | customers/XXX/campaigns/YYY | name3 | 10000000000 |\n+----+-----------------------------+---------+-------------+\n```\n\nBy default it uses the it in `table` format but you can control the output\nformat with the `-o` option:\n\n```shell\n# Print the plain protobuf response\n$ gaql -o plain\n\n# Print the contents of a CSV file\n$ gaql -o csv\n```\n\nYou can also run a single inline command and redirect the output to a file:\n\n```shell\ngaql -c 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id' -o csv > my-query.csv\n```\n\nThis assumes only table is returned but in more complex queries that include other\nresources or when using metrics or segments multiple tables are created.\nOn those cases use the -o csv-files flag to save each table to a different file\nbased on the table name.\n\n```shell\n$ gaql -c 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id' -o csv-files\n\n$ ls\ncampaign.csv\n```\n\n### Query variables\n\nYou can specify one or more variables using the jinja syntax, those\nvariables will be replaced with the values specified in the `-v` options.\n\n```shell\ngaql -c 'SELECT campaign.id, campaign.name FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id' -v id=123456789\n```\n\nYou can also pass `-v` without a command and use this the variables in the prompt\nqueries:\n\n```shell\n$ gaql -v id=123456789 -v field=name\n\n>>> SELECT campaign.id, campaign.{{ field }} FROM campaign WHERE campaign.id = {{ id }} ORDER BY campaign.id\n```\n\n### Other options\n\nYou can overwrite the account and customer ID using the `-a` and `-i` options.\nSee `gaql --help` for more details.\n\n## CLI\n\n### Campaign Management\n\n#### Get campaigns\n\n````shell\n\n```shell\nadsctl get campaign\n````\n\n```plain\nName Status Id\n-------------------------------------------- -------- -----------\nInterplanetary Cruise Campaign #168961427368 Paused 20370195066\nInterplanetary Cruise Campaign #168961215970 Paused 20379497161\n```\n\n#### Status Management\n\n```shell\nadsctl edit campaign -i <campaign-id> status enabled\n\nadsctl edit campaign -i 20370195066 status enabled\n```\n\n```shell\nadsctl get campaign\n```\n\n```plain\nName Status Id\n-------------------------------------------- -------- -----------\nInterplanetary Cruise Campaign #168961427368 Enabled 20370195066\nInterplanetary Cruise Campaign #168961215970 Paused 20379497161\n```\n\n#### Update budget\n\n```shell\nadsctl edit campaign -i <campaign-id> budget <amount>\n```\n\n## Python API\n\nYou can also use the Python API to easily execute GAQL queries\nand get the results as a Python dict or pandas DataFrame.\n\n```python\nimport adsctl as ads\n\n# Read config file and creates the Google Ads client\ngoogle_ads = ads.GoogleAds()\n\n# Execute GAQL query\nget_campaigns_query = \"\"\"\nSELECT campaign.name,\n campaign_budget.amount_micros,\n campaign.status,\n campaign.optimization_score,\n campaign.advertising_channel_type,\n metrics.clicks,\n metrics.impressions,\n metrics.ctr,\n metrics.average_cpc,\n metrics.cost_micros,\n campaign.bidding_strategy_type\nFROM campaign\nWHERE segments.date DURING LAST_7_DAYS\n AND campaign.status != '{{ status }}'\n\"\"\"\n\ntables = google_ads.query(get_campaigns_query, params={\"status\": \"REMOVED\"}})\n\n# Print Pandas DataFrames\nfor table_name, table in tables.items():\n print(table_name)\n print(table, \"\\n\")\n```\n\n```plain\ncampaign\n resourceName status ... name optimizationScore\n0 customers/XXXXXXXXXX/campaigns/YYYYYYYYYYY ENABLED ... my-campaign 0.839904\n[1 rows x 6 columns]\n\nmetrics\n clicks costMicros ctr averageCpc impressions\n0 210 6730050 0.011457 32047.857143 18330\n\ncampaignBudget\n resourceName amountMicros\n0 customers/XXXXXXXXXX/campaignBudgets/ZZZZZZZZZZZ 1000000\n```\n\n## Disclaimer\n\n_This is not an official Google product_.\n\nThis repository is maintained by a Googler but is not a supported Google product.\nCode and issues here are answered by maintainers and other community members on GitHub on a best-effort basis.\n",
"bugtrack_url": null,
"license": "",
"summary": "Google Ads Control CLI and Prompt",
"version": "0.4.1",
"project_urls": {
"Documentation": "https://github.com/danielfrg/adsctl#readme",
"Issues": "https://github.com/danielfrg/adsctl/issues",
"Source": "https://github.com/danielfrg/adsctl"
},
"split_keywords": [
"cli",
"google ads",
"google ads api",
"prompt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "52e18542c38ea922d008b08949d7501f9803c1b91c8ba147b5994c244cdf8b9c",
"md5": "6f7510b52a03c9a43645ac3209d9fa3f",
"sha256": "c95fc03c3fb986bd7bcf3fa8de676d3d98faabee6073790c6047078e30af8f74"
},
"downloads": -1,
"filename": "adsctl-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6f7510b52a03c9a43645ac3209d9fa3f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28950,
"upload_time": "2023-07-25T13:47:31",
"upload_time_iso_8601": "2023-07-25T13:47:31.178171Z",
"url": "https://files.pythonhosted.org/packages/52/e1/8542c38ea922d008b08949d7501f9803c1b91c8ba147b5994c244cdf8b9c/adsctl-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d6274c2a012014a868a19951bffd60bc82ca2e06cdff18aa90c56eaf138637e2",
"md5": "617d57d128690c1b6c7b84488760201a",
"sha256": "b753ebc9620887ce7cda000e02c19d4163317aab778e8390652683079c19dbd9"
},
"downloads": -1,
"filename": "adsctl-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "617d57d128690c1b6c7b84488760201a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24936,
"upload_time": "2023-07-25T13:47:32",
"upload_time_iso_8601": "2023-07-25T13:47:32.491614Z",
"url": "https://files.pythonhosted.org/packages/d6/27/4c2a012014a868a19951bffd60bc82ca2e06cdff18aa90c56eaf138637e2/adsctl-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-25 13:47:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "danielfrg",
"github_project": "adsctl#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "adsctl"
}
