facebook-ads-reports


Namefacebook-ads-reports JSON
Version 0.2.0 PyPI version JSON
download
home_pagehttps://github.com/machado000/facebook-ads-reports
SummaryETL module for Facebook Ads API v22 with database-optimized DataFrame processing
upload_time2025-08-09 23:41:07
maintainerNone
docs_urlNone
authorJoao Brito
requires_python<3.13,>=3.10
licenseGPL
keywords google-ads pandas etl data-extraction reports
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 v22 data extraction and transformation. Simplifies the process of extracting Facebook Ads data and converting it to database-ready pandas DataFrames with comprehensive optimization features.

[![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 v22**: 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
- **Database-Ready DataFrames**: Optimized data types and encoding for seamless database storage
- **Smart Type Detection**: Dynamic conversion of metrics to appropriate int64/float64 types
- **Configurable Missing Values**: Granular control over NaN/NaT handling by column type
- **Character Encoding Cleanup**: Automatic text sanitization for database compatibility
- **Zero Impression Filtering**: Robust filtering handling multiple zero representations
- **Type Hints**: Full type hint support for better IDE experience

## Installation

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

## Quick Start

### 1. Set up credentials

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

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

### 2. Basic usage

```python
from datetime import date, timedelta
from facebook_ads_reports import MetaAdsReport, MetaAdsReportModel, load_credentials

# Load credentials
credentials = load_credentials()
client = MetaAdsReport(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 with database optimization
df = 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
df.to_csv("ad_performance_report.csv", index=False)
```


## 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:
# df = client.get_insights_report(ad_account_id, custom_report, start_date, end_date)
```

## Database Optimization Features

- **Automatic Date Conversion**: String dates → `datetime64[ns]`
- **Dynamic Metrics Conversion**: Object metrics → `int64` or `float64` based on data
- **Preserve NULL Compatibility**: NaN/NaT preserved for database NULL mapping
- **Safe Conversion**: Invalid values gracefully ignored
- **ASCII Sanitization**: Removes non-ASCII characters for database compatibility
- **Length Limiting**: Truncates text to 255 characters (configurable)
- **Whitespace Trimming**: Removes leading/trailing whitespace


## Examples

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

- `basic_usage.py` - Simple report extraction


## Requirements

- Python 3.10-3.12
- pandas >= 2.0.0
- python-dotenv >= 1.0.0
- requests >= 2.32.4
- tqdm >= 4.65.0


## License

MIT 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.13,>=3.10",
    "maintainer_email": null,
    "keywords": "google-ads, pandas, etl, data-extraction, reports",
    "author": "Joao Brito",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/86/6c/9221f218a58410122671dccec1aa07c87dda4eb8fb6d39ec113e378cabb8/facebook_ads_reports-0.2.0.tar.gz",
    "platform": null,
    "description": "# Facebook Ads Reports Helper\n\nA Python ETL driver for Facebook Marketing API v22 data extraction and transformation. Simplifies the process of extracting Facebook Ads data and converting it to database-ready pandas DataFrames with comprehensive optimization features.\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 v22**: 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- **Database-Ready DataFrames**: Optimized data types and encoding for seamless database storage\n- **Smart Type Detection**: Dynamic conversion of metrics to appropriate int64/float64 types\n- **Configurable Missing Values**: Granular control over NaN/NaT handling by column type\n- **Character Encoding Cleanup**: Automatic text sanitization for database compatibility\n- **Zero Impression Filtering**: Robust filtering handling multiple zero representations\n- **Type Hints**: Full type hint support for better IDE experience\n\n## Installation\n\n```bash\npip install facebook-ads-reports\n```\n\n## Quick Start\n\n### 1. Set up credentials\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  \"access_token\": \"YOUR_ACCESS_TOKEN\",\n  \"base_url\": \"https://graph.facebook.com/v22.0\"\n  \"ad_account_id\": \"act_1234567890\",\n}\n```\n\n### 2. Basic usage\n\n```python\nfrom datetime import date, timedelta\nfrom facebook_ads_reports import MetaAdsReport, MetaAdsReportModel, load_credentials\n\n# Load credentials\ncredentials = load_credentials()\nclient = MetaAdsReport(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 with database optimization\ndf = 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\ndf.to_csv(\"ad_performance_report.csv\", index=False)\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# df = client.get_insights_report(ad_account_id, custom_report, start_date, end_date)\n```\n\n## Database Optimization Features\n\n- **Automatic Date Conversion**: String dates \u2192 `datetime64[ns]`\n- **Dynamic Metrics Conversion**: Object metrics \u2192 `int64` or `float64` based on data\n- **Preserve NULL Compatibility**: NaN/NaT preserved for database NULL mapping\n- **Safe Conversion**: Invalid values gracefully ignored\n- **ASCII Sanitization**: Removes non-ASCII characters for database compatibility\n- **Length Limiting**: Truncates text to 255 characters (configurable)\n- **Whitespace Trimming**: Removes leading/trailing whitespace\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.10-3.12\n- pandas >= 2.0.0\n- python-dotenv >= 1.0.0\n- requests >= 2.32.4\n- tqdm >= 4.65.0\n\n\n## License\n\nMIT 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 v22 with database-optimized DataFrame processing",
    "version": "0.2.0",
    "project_urls": {
        "Documentation": "https://github.com/machado000/facebook-ads-reports#readme",
        "Homepage": "https://github.com/machado000/facebook-ads-reports",
        "Issues": "https://github.com/machado000/facebook-ads-reports/issues"
    },
    "split_keywords": [
        "google-ads",
        " pandas",
        " etl",
        " data-extraction",
        " reports"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "0ca8add6c8224bad77f6cf65bca9b7ff7e23eaa9f47823812c94745ad4e019a8",
                "md5": "758c367852e13cb4a572f9581405feb5",
                "sha256": "c3f39805a6e0810ee80ceaf468bb8891b669f479cc01c997a66381d14ea861f9"
            },
            "downloads": -1,
            "filename": "facebook_ads_reports-0.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "758c367852e13cb4a572f9581405feb5",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.13,>=3.10",
            "size": 27437,
            "upload_time": "2025-08-09T23:41:05",
            "upload_time_iso_8601": "2025-08-09T23:41:05.812119Z",
            "url": "https://files.pythonhosted.org/packages/0c/a8/add6c8224bad77f6cf65bca9b7ff7e23eaa9f47823812c94745ad4e019a8/facebook_ads_reports-0.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "866c9221f218a58410122671dccec1aa07c87dda4eb8fb6d39ec113e378cabb8",
                "md5": "acfeed4247cb4507077362cd2d52085b",
                "sha256": "22dede03f2dc5bb3e9800ae51501a230ab12c0ed4eafd3656775cc832232c5fa"
            },
            "downloads": -1,
            "filename": "facebook_ads_reports-0.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "acfeed4247cb4507077362cd2d52085b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.13,>=3.10",
            "size": 26129,
            "upload_time": "2025-08-09T23:41:07",
            "upload_time_iso_8601": "2025-08-09T23:41:07.353702Z",
            "url": "https://files.pythonhosted.org/packages/86/6c/9221f218a58410122671dccec1aa07c87dda4eb8fb6d39ec113e378cabb8/facebook_ads_reports-0.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-09 23:41:07",
    "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: 1.20716s