A Python script for downloading structure and performance data from ad accounts in a single business manager using the Facebook Ads API (v2.9) to local files.
By default, it creates two data sets:
-
Ad Performance consists of measures such as impressions, clicks, conversions and spend. The script creates one sqlite3 database per day and ad account in a specified time range:
data/2017/01/01/facebook/ad-performance-act_1234567890.sqlite3 data/2017/01/02/facebook/ad-performance-act_1234567890.sqlite3
For the last 28 days, the script always redownloads the files as data still changes (e.g spend or attributed conversions). Beyond that, files are only downloaded for dates where the ad account existed but the file is missing. Note: If you are using an attribution window larger than 28 days adjust the
redownload_window
config accordingly.The resulting sqlite3 databases contain a single table
ad_performance
, with individual rows per ad and the device and placement breakdown. See Insights Breakdowns for a documentation of the breakdown. The performance data is stored in JSON format in a single columndate | 2017-01-01 ad_id | 1234567890 device | desktop placement | desktop_feed performance | {"spend": 0.42, | "impressions": 25, | "actions": [{"value": 1.0, "28d_click": 1.0, "action_type": "link_click"}, | {"value": 20.0, "28d_click": 20.0, "action_type": "offsite_conversion.fb_pixel_add_to_cart"}, | {"value": 2.0, "28d_click": 2.0, "action_type": "offsite_conversion.fb_pixel_purchase"}, | {"value": 18.0, "28d_click": 17.0, "action_type": "offsite_conversion.fb_pixel_view_content"}, | {"value": 1.0, "28d_click": 1.0, "action_type": "page_engagement"}, | {"value": 1.0, "28d_click": 1.0, "action_type": "post_engagement"}, | {"value": 45.0, "28d_click": 34.0, "action_type": "offsite_conversion"}], | "action_values": [{"value": 2.0, "28d_click": 2.0, "action_type": "offsite_conversion.fb_pixel_purchase"}, | {"value": 2.0, "28d_click": 2.0, "action_type": "offsite_conversion"}]}
See Insights Fields for a documentation of the fields.
-
Account Structure information. This file is always overwritten by the script:
data/facebook-account-structure_v1.csv.gz
Each line contains one ad together with its ad group, campaign and account:
ad_id | 1234567890 ad_name | Foo ad_group_id | 3456789012 ad_group_name | Bar campaign_id | 5678901234 campaign_name | Baz account_id | 7890123456 account_name | Qux attributes | {"Target": "buyer", "Channel": "reactivation", "Country": "France", "Language": "French"}
The
attributes
field contains a JSON representation of all labels of an ad or its parents in a{Key=Value}
syntax. For example an account has the label{Channel=reactivation}
, then all ads below will have the"Channel": "reactivation"
. Note: Labels on lower levels overwrite those from higher levels.
To use the Facebook Ads Performance Downloader you have to
- consolidate all accounts of a company under a single business manager,
- create a normal system user for that business manager using the guide in the link or the System User page in your business manager.
- give the system user access to all ad accounts that should be downloaded,
- create an app and disable development mode,
- set up app and system user credentials to access the Facebook Ads API. See Set up your credentials for the necessary steps.
Optionally, you can apply labels on all hierarchy levels for segmenting the structure.
The Facebook Ads Performance Downloader requires:
Python (>= 3.5)
facebookads (==2.9.2)
click (>=6.0)
The easiest way to install facebook-ads-downloader is using pip
pip install git+https://github.com/mara/facebook-ads-performance-downloader.git
In case you want to install it in a virtual environment:
$ git clone git@github.com:mara/facebook-ads-performance-downloader.git facebook_downloader
$ cd facebook_downloader
$ python3 -m venv .venv
$ .venv/bin/pip install .
Find the app_id
and app_secret
in your app's dashboard at https://developers.facebook.com/apps/<YOUR_APP_ID>/dashboard/
:
Log into your Facebook account and go to the system users page of your company's business manager at https://business.facebook.com/settings/system-users
and click on Generate New Token:
Select the app you want to use to download the data, activate the read_insights
and ads_read
scope and generate the token:
The generated access_token
is then shown to you:
To run the Facebook Ads Performance Downloader call download-facebook-performance-data
with its config parameters:
$ download-facebook-performance-data --app_id 1234567890 \
--app_secret ABCDEFEGHIJKL \
--access_token aBcDeFgHiJkLmNoPqRsTuVwXyZ \
--data_dir /tmp/facebook