Meta Ads Export Guide — Python Script

GMSF v1.3 Meta Ads 10 min install
🎯
Objective
This Python script exports Meta Ads (Facebook, Instagram, Audience Network, Messenger) campaign data with GMSF v1.3 granularity for Carbon Intelligence™. Meta offers unique granularity on placements (Feed, Stories, Reels) and actual impression devices, essential for precise carbon calculation.
⚙️
Installation
3 steps · 10 minutes
Prerequisites
  1. Python 3.8+ installed on your machine
  2. Install dependencies: pip install requests pandas
  3. Create a Meta App on developers.facebook.com
  4. Obtain a long-lived Access Token with ads_read and ads_management permissions
  5. Note your Ad Account ID (format: act_XXXXXXXXX)
Configure the script
  1. Open the file: carbon-intelligence-meta-ads-export.py
  2. Fill in the variables: ACCESS_TOKEN, AD_ACCOUNT_ID
  3. Configure OUTPUT_DIR (CSV destination folder)
  4. Optional: Set environment variables CI_META_ACCESS_TOKEN and CI_META_AD_ACCOUNT_ID instead of hardcoding
Run
  1. Run the script: python carbon-intelligence-meta-ads-export.py
  2. CSV files are generated in OUTPUT_DIR
  3. Schedule execution via cron (weekly recommended)
📊
What is exported
10 tabs created automatically
TabContentUsage Carbon Intelligence
CI_CampaignsBy campaign + week: impressions, reach, frequency, spend, ROASCampaign overview
CI_DeviceBy device (mobile, desktop, tablet)Energy factor per device
CI_GeoBy countryGMSF v1.3 country energy mix
CI_PlacementsBy platform x position: Feed, Stories, Reels, Right Column🎯 Meta Specific — Feed/Stories/Reels granularity
CI_CreativeSizeBy ad with creative dimensionsData transfer weight
CI_AdFormatBy publisher_platformAd format factor
CI_VideoVideo quartiles (p25, p50, p75, p100), average durationVideo carbon calculation
CI_ImpDeviceBy real device: iPhone, iPad, Android, Desktop🔴 Carbon Critical — actual device used
CI_MetadataAccount and export info (timestamp, API version)Traceability and audit
CI_Export_CSVAll dimensions consolidated flatDirect CI platform import
📁
Export CSV
Two options available
The CI_Export_CSV tab contains all dimensions flattened, ready for direct import into the Carbon Intelligence™ platform. CSV files are automatically generated in OUTPUT_DIR with each script execution.
🔗
Sharing with Carbon Intelligence™
📨
Share the Google Sheet with: support@carbonintelligence.green (accès lecteur)
Or send the exported CSV by email to the same address.
🔧
Advanced Configuration
Script CONFIG section
# In the script, CONFIG section:

LOOKBACK_DAYS: 90,          # Days of history (default: 90)
MIN_IMPRESSIONS: 1,         # Minimum impression threshold per row
API_VERSION: 'v19.0'        # Meta API version (updated regularly)
🛠️
Troubleshooting
OAuthException
Access Token expired. Generate a new long-lived token on developers.facebook.com with the required permissions.
"Error validating access token"
Check that the Access Token has ads_read and ads_management permissions on your Meta App.
"Ad Account not found"
Check the format of your Ad Account ID: act_XXXXXXXXX (with the act_ prefix).
"Rate limit exceeded"
The script automatically handles exponential retries. If persistent, reduce LOOKBACK_DAYS to 30 or 60 days.
Empty video data
Normal if no video campaign is active for the period. The CI_Video tab only fills when there are video impressions.
💬
Support
Email support@carbonintelligence.green
Website carbonintelligence.green
Script version 1.0.0
Methodology GMSF v1.3 (Ad Net Zero)
Carbon Intelligence™ — Installation Guide Meta Ads — v1.0.0
ISO 14064 GHG Protocol ADEME Base Carbone GMSF v1.3 Ad Net Zero