facebook-ads-reports


Namefacebook-ads-reports JSON
Version 2.0.1 PyPI version JSON
download
home_pagehttps://github.com/machado000/facebook-ads-reports
SummaryETL module for Facebook Ads API v23 with lightweight native Python data processing
upload_time2025-10-08 16:50:54
maintainerNone
docs_urlNone
authorJoao Brito
requires_python<3.15,>=3.11
licenseGPL
keywords facebook-ads etl data-extraction reports flatten-json
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # Facebook Ads Reports Helper

A Python ETL driver for Facebook Marketing API v23 data extraction and transformation. Simplifies the process of extracting Facebook Ads data and converting it to structured data formats with comprehensive utility functions.

[![PyPI version](https://img.shields.io/pypi/v/facebook-ads-reports)](https://pypi.org/project/facebook-ads-reports/)
[![Last Commit](https://img.shields.io/github/last-commit/machado000/facebook-ads-reports)](https://github.com/machado000/facebook-ads-reports/commits/main)
[![Issues](https://img.shields.io/github/issues/machado000/facebook-ads-reports)](https://github.com/machado000/facebook-ads-reports/issues)
[![License](https://img.shields.io/badge/License-GPL-yellow.svg)](https://github.com/machado000/facebook-ads-reports/blob/main/LICENSE)

## Features

- **Facebook Marketing API v23**: Latest API version support with full compatibility
- **Robust Error Handling**: Comprehensive error handling with retry logic and specific exceptions
- **Multiple Report Types**: Pre-configured report models for common use cases
- **Custom Reports**: Create custom report configurations
- **Flexible Data Export**: Built-in CSV and JSON export utilities
- **Lightweight Architecture**: No pandas dependency for faster installations and smaller footprint
- **Type Hints**: Full type hint support with strict mypy compliance for better IDE experience
- **Data Processing Utilities**: Helper functions for data transformation and export

## Installation

```bash
pip install facebook-ads-reports
```

## Quick Start

### 1. Set up credentials

**Option A: Configuration file**

Create a `secrets/fb_business_config.json` file with your Facebook Ads API credentials:

```json
{
  "app_id": "YOUR_APP_ID",
  "app_secret": "YOUR_APP_SECRET",
  "access_token": "YOUR_ACCESS_TOKEN",
  "ad_account_id": "act_1234567890",
  "base_url": "https://graph.facebook.com/v23.0"
}
```

**Option B: Environment variable**

Set the `FACEBOOK_ADS_CONFIG_JSON` environment variable with your credentials as JSON:

```bash
export FACEBOOK_ADS_CONFIG_JSON='{"app_id": "YOUR_APP_ID", "app_secret": "YOUR_APP_SECRET", "access_token": "YOUR_ACCESS_TOKEN", "ad_account_id": "act_1234567890", "base_url": "https://graph.facebook.com/v23.0"}'
```

### 2. Basic usage

```python
from datetime import date, timedelta
from facebook_ads_reports import MetaAdsReport, MetaAdsReportModel
from facebook_ads_reports.utils import load_credentials, save_report_to_csv, save_report_to_json

# Load credentials
credentials = load_credentials()
client = MetaAdsReport(credentials_dict=credentials)

# Configure report parameters
ad_account_id = "act_1234567890"
start_date = date.today() - timedelta(days=7)
end_date = date.today() - timedelta(days=1)

# Extract report data
data = client.get_insights_report(
        ad_account_id=ad_account_id,
        report_model=MetaAdsReportModel.ad_performance_report,
        start_date=start_date,
        end_date=end_date
)

# Save to CSV using utility function
save_report_to_csv(data, "ad_performance_report.csv")

# Save to JSON using utility function
save_report_to_json(data, "ad_performance_report.json")
```


## Available Report Models

- `MetaAdsReportModel.ad_dimensions_report` - Ad dimensions and metadata
- `MetaAdsReportModel.ad_performance_report` - Ad performance and actions metrics

## Custom Reports

Create custom report configurations:

```python
from facebook_ads_reports import create_custom_report

custom_report = create_custom_report(
    report_name="my_custom_report",
    select=["ad_id", "impressions", "spend"],
    from_table="ad_insights"
)

# Usage:
# data = client.get_insights_report(ad_account_id, custom_report, start_date, end_date)
```

## Examples

Check the `examples/` directory for comprehensive usage examples:

- `basic_usage.py` - Simple report extraction


## Requirements

- Python 3.11-3.14
- requests >= 2.32.4


## License

GPL License. See [LICENSE](LICENSE) file for details.


## Support

- [Documentation](https://github.com/machado000/facebook-ads-reports#readme)
- [Issues](https://github.com/machado000/facebook-ads-reports/issues)
- [Examples](examples/)


## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/machado000/facebook-ads-reports",
    "name": "facebook-ads-reports",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<3.15,>=3.11",
    "maintainer_email": null,
    "keywords": "facebook-ads, etl, data-extraction, reports, flatten-json",
    "author": "Joao Brito",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/4a/2a/4846035ee8a3f586018a01651f5fbc149ee94abab8f928ecb81773f17ec0/facebook_ads_reports-2.0.1.tar.gz",
    "platform": null,
    "description": "# Facebook Ads Reports Helper\n\nA Python ETL driver for Facebook Marketing API v23 data extraction and transformation. Simplifies the process of extracting Facebook Ads data and converting it to structured data formats with comprehensive utility functions.\n\n[![PyPI version](https://img.shields.io/pypi/v/facebook-ads-reports)](https://pypi.org/project/facebook-ads-reports/)\n[![Last Commit](https://img.shields.io/github/last-commit/machado000/facebook-ads-reports)](https://github.com/machado000/facebook-ads-reports/commits/main)\n[![Issues](https://img.shields.io/github/issues/machado000/facebook-ads-reports)](https://github.com/machado000/facebook-ads-reports/issues)\n[![License](https://img.shields.io/badge/License-GPL-yellow.svg)](https://github.com/machado000/facebook-ads-reports/blob/main/LICENSE)\n\n## Features\n\n- **Facebook Marketing API v23**: Latest API version support with full compatibility\n- **Robust Error Handling**: Comprehensive error handling with retry logic and specific exceptions\n- **Multiple Report Types**: Pre-configured report models for common use cases\n- **Custom Reports**: Create custom report configurations\n- **Flexible Data Export**: Built-in CSV and JSON export utilities\n- **Lightweight Architecture**: No pandas dependency for faster installations and smaller footprint\n- **Type Hints**: Full type hint support with strict mypy compliance for better IDE experience\n- **Data Processing Utilities**: Helper functions for data transformation and export\n\n## Installation\n\n```bash\npip install facebook-ads-reports\n```\n\n## Quick Start\n\n### 1. Set up credentials\n\n**Option A: Configuration file**\n\nCreate a `secrets/fb_business_config.json` file with your Facebook Ads API credentials:\n\n```json\n{\n  \"app_id\": \"YOUR_APP_ID\",\n  \"app_secret\": \"YOUR_APP_SECRET\",\n  \"access_token\": \"YOUR_ACCESS_TOKEN\",\n  \"ad_account_id\": \"act_1234567890\",\n  \"base_url\": \"https://graph.facebook.com/v23.0\"\n}\n```\n\n**Option B: Environment variable**\n\nSet the `FACEBOOK_ADS_CONFIG_JSON` environment variable with your credentials as JSON:\n\n```bash\nexport FACEBOOK_ADS_CONFIG_JSON='{\"app_id\": \"YOUR_APP_ID\", \"app_secret\": \"YOUR_APP_SECRET\", \"access_token\": \"YOUR_ACCESS_TOKEN\", \"ad_account_id\": \"act_1234567890\", \"base_url\": \"https://graph.facebook.com/v23.0\"}'\n```\n\n### 2. Basic usage\n\n```python\nfrom datetime import date, timedelta\nfrom facebook_ads_reports import MetaAdsReport, MetaAdsReportModel\nfrom facebook_ads_reports.utils import load_credentials, save_report_to_csv, save_report_to_json\n\n# Load credentials\ncredentials = load_credentials()\nclient = MetaAdsReport(credentials_dict=credentials)\n\n# Configure report parameters\nad_account_id = \"act_1234567890\"\nstart_date = date.today() - timedelta(days=7)\nend_date = date.today() - timedelta(days=1)\n\n# Extract report data\ndata = client.get_insights_report(\n        ad_account_id=ad_account_id,\n        report_model=MetaAdsReportModel.ad_performance_report,\n        start_date=start_date,\n        end_date=end_date\n)\n\n# Save to CSV using utility function\nsave_report_to_csv(data, \"ad_performance_report.csv\")\n\n# Save to JSON using utility function\nsave_report_to_json(data, \"ad_performance_report.json\")\n```\n\n\n## Available Report Models\n\n- `MetaAdsReportModel.ad_dimensions_report` - Ad dimensions and metadata\n- `MetaAdsReportModel.ad_performance_report` - Ad performance and actions metrics\n\n## Custom Reports\n\nCreate custom report configurations:\n\n```python\nfrom facebook_ads_reports import create_custom_report\n\ncustom_report = create_custom_report(\n    report_name=\"my_custom_report\",\n    select=[\"ad_id\", \"impressions\", \"spend\"],\n    from_table=\"ad_insights\"\n)\n\n# Usage:\n# data = client.get_insights_report(ad_account_id, custom_report, start_date, end_date)\n```\n\n## Examples\n\nCheck the `examples/` directory for comprehensive usage examples:\n\n- `basic_usage.py` - Simple report extraction\n\n\n## Requirements\n\n- Python 3.11-3.14\n- requests >= 2.32.4\n\n\n## License\n\nGPL License. See [LICENSE](LICENSE) file for details.\n\n\n## Support\n\n- [Documentation](https://github.com/machado000/facebook-ads-reports#readme)\n- [Issues](https://github.com/machado000/facebook-ads-reports/issues)\n- [Examples](examples/)\n\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.",
    "bugtrack_url": null,
    "license": "GPL",
    "summary": "ETL module for Facebook Ads API v23 with lightweight native Python data processing",
    "version": "2.0.1",
    "project_urls": {
        "Homepage": "https://github.com/machado000/facebook-ads-reports",
        "Issues": "https://github.com/machado000/facebook-ads-reports/issues"
    },
    "split_keywords": [
        "facebook-ads",
        " etl",
        " data-extraction",
        " reports",
        " flatten-json"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4fcd130d638bc8cf038a80759689316dc16ed68c41c0e7ec1393364954dcd632",
                "md5": "be56a1f7ef644155d21cd9d78d936b70",
                "sha256": "7f5b32e48f1b2a8794e5a9821b2eecc4381da95dd8676761b9e2a1bde20d0cab"
            },
            "downloads": -1,
            "filename": "facebook_ads_reports-2.0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "be56a1f7ef644155d21cd9d78d936b70",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.15,>=3.11",
            "size": 26912,
            "upload_time": "2025-10-08T16:50:53",
            "upload_time_iso_8601": "2025-10-08T16:50:53.267795Z",
            "url": "https://files.pythonhosted.org/packages/4f/cd/130d638bc8cf038a80759689316dc16ed68c41c0e7ec1393364954dcd632/facebook_ads_reports-2.0.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4a2a4846035ee8a3f586018a01651f5fbc149ee94abab8f928ecb81773f17ec0",
                "md5": "916efd7ca703947fe597a8d284be7821",
                "sha256": "67b09443bfb6cab0be49fe6dd4d30069937ee591f929a474a12471f948bcdf04"
            },
            "downloads": -1,
            "filename": "facebook_ads_reports-2.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "916efd7ca703947fe597a8d284be7821",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.15,>=3.11",
            "size": 25240,
            "upload_time": "2025-10-08T16:50:54",
            "upload_time_iso_8601": "2025-10-08T16:50:54.350782Z",
            "url": "https://files.pythonhosted.org/packages/4a/2a/4846035ee8a3f586018a01651f5fbc149ee94abab8f928ecb81773f17ec0/facebook_ads_reports-2.0.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-08 16:50:54",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "machado000",
    "github_project": "facebook-ads-reports",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "facebook-ads-reports"
}
Joao Brito
Elapsed time: 0.81217s