Input Functions: Loading the Data

Warning

Please disable AdBlock, as it might hide some elements on this page!

These functions can be imported from the ppc_robot_lib.reporting.input module.

AdWords

Google Ads (Beta)

These functions can be used to download data from the upcoming Google Ads API (currently in beta).

download_ads_report(query=None)[source]

Downloads Google Ads resources. Records are stored in a table.

Example:

>>> from ppc_robot_lib.google_ads.query import Query, Condition, LastNDaysRange, OrderBy, Op, Sort
>>> from ppc_robot_lib.reporting.input.ads import download_ads_report
>>> gaql_query = Query(
...     select=['campaign.name', 'metrics.clicks'],
...     from_resource='campaign',
...     during=LastNDaysRange(7),
...     where=[
...         Condition('metrics.clicks', Op.GREATER_THAN, 10)
...     ],
...     order_by=[OrderBy('metrics.clicks', Sort.ASCENDING)],
...     limit=100
... )
>>> download_ads_report(gaql_query)

You can use Interactive GAQL Builder to build your queries.

Parameters:: query (Query) – Query to be executed
Return type:: DataFrame
Returns:: DataFrame with filled data

Sklik

download_sklik_report(query, allow_empty_statistics=False, transformation=None, custom_columns=None)[source]

Downloads a report from Sklik API. This step uses the PPC Robots Sklik connector to download the report, this means that it automatically performs all necessary paging and data normalization.

Only reports defined in the ppc_robot_lib.sklik.reports module can be used. See Available Reports for more details.

The query parameter should be a ppc_robot_lib.sklik.query.Query instance with one of the reports above.

Example:

>>> from ppc_robot_lib.sklik import Query, Condition, Op, During, Granularity
>>> from ppc_robot_lib.sklik.types import StatusEnum
>>> from ppc_robot_lib.reporting.input import download_sklik_report
>>> query = Query(
...     select=['Name', 'Status', 'Clicks', 'Impressions'],
...     from_report='group',
...     where=[
...         Condition('Status', Op.EQ, StatusEnum.ACTIVE),
...         Condition('Impressions', Op.GT, 0),
...     ],
...     during=During.LAST_30_DAYS,
...     granularity=Granularity.DAILY,
... )
>>> df = download_sklik_report(query)

Parameters:

query (Query) – Query to execute.
allow_empty_statistics – Should we include rows with zero impressions?
transformation (Callable[[Iterable], Iterable]) – Custom transformation function. The function receives an iterable (a generator, to be more precise, but this behaviour can change in the future) and must return another iterable, that can be passed to pandas.DataFrame as the data argument.
custom_columns (list[str]) – Custom column names for the output table. If no columns are given, names from the query are used. Useful if you use a custom transformation that can change the columns.

Return type:

DataFrame

Returns:

DataFrame with downloaded data.

download_sklik_report_details(base_query, cond_column, in_values, allow_empty_statistics=False, transformation=None, custom_columns=None, batch_size=10000)[source]

Downloads additional details for a given table. This step takes a column from source table, takes the base query and adds a new IN[] condition for specified column (defaults to the source column name) to the query. Then it uses this query to fetch report data. The data is fetched in multiple batches and ten concatenated.

Example:

>>> from ppc_robot_lib.sklik import Query, During
>>> from ppc_robot_lib.reporting.input import download_sklik_report_details
>>> ids = [12, 15, 36, 85, 94, 101]  # This can be any iterable, such as column from a DataFrame.
>>> base_query = Query(
...     select=['Id', 'Name', 'Impressions', 'Clicks'],
...     from_report='campaign',
...     during=During.LAST_30_DAYS,
... )
>>> campaign_details = download_sklik_report_details(
...     base_query=base_query,
...     cond_column='Id',
...     in_values=ids,
...     batch_size=5000,
... )

Parameters:

base_query (Query) – Base Query used to build a query for each batch.
cond_column (str) – Name of the column that will be used in the condition.
in_values (Iterable[str | int | float]) – Values that will be used for the IN[] condition.
allow_empty_statistics (bool) – Should we include rows with zero impressions?
transformation (Callable[[Iterable], Iterable]) – Custom transformation function. The function receives an iterable (a generator, to be more precise, but this behaviour can change in the future) and must return another iterable, that can be passed to pandas.DataFrame as the data argument.
custom_columns (list[str]) – Custom column names for the output table. If no columns are given, names from the query are used. Useful if you use a custom transformation that can change the columns.
batch_size (int) – Number of values in the IN[] condition for each batch.

Return type:

DataFrame

Returns:

DataFrame with downloaded data.

download_sklik_custom_report(custom_report, columns, filters, during, allow_empty_statistics=False)[source]

Return type:: DataFrame

PPC Robot’s database

join_account_info(table, properties=list[str], client_id_column=None, context_client_id=False, suffix='_account')[source]

Fetches account information and settings and joins them to the given table. The accounts are fetched either by value in column client_id_column, or by client ID specified in task context. Lookups are always performed by the ext_id column in the ppc_robot_lib.models.client_account.ClientAccount model.

Properties is either a list of columns to be fetched, any field from ppc_robot_lib.models.client_account.ClientAccount can be used. If the column already exits in the table, specified suffix is appended to the result name (_account by default).

A copy of the given DataFrame with additional details is returned.

Parameters:

table (DataFrame) – Table name to which the account information should be added.
properties – Properties of the ppc_robot_lib.models.client_account.ClientAccount model which should be added as columns to the table.
client_id_column (str) – Use the specified column values as input for the lookup.
context_client_id (bool) – Set to True if you would like to use client_id stored in the task context.
suffix – Suffix to add to the columns if they already exists in the table.

Return type:

DataFrame

Returns:

DataFrame with new information.