107 lines
2.5 KiB
Markdown
107 lines
2.5 KiB
Markdown
# Meta API Grabber
|
|
|
|
Async script to grab ad insights data from Meta's Marketing API with conservative rate limiting.
|
|
|
|
## Features
|
|
|
|
- **OAuth2 Authentication** - Automated token generation flow
|
|
- **Async/await architecture** for efficient API calls
|
|
- **Conservative rate limiting** (2s between requests, 1 concurrent request)
|
|
- **Multi-level insights** - Account, campaign, and ad set data
|
|
- **JSON output** with timestamps
|
|
- **Configurable date ranges**
|
|
|
|
## Setup
|
|
|
|
1. Install dependencies using uv:
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
2. Configure your Meta API credentials:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
3. Edit `.env` and add your App ID, App Secret, and Ad Account ID:
|
|
- Get your App credentials from [Meta for Developers](https://developers.facebook.com/)
|
|
- Find your ad account ID in Meta Ads Manager (format: `act_1234567890`)
|
|
|
|
4. Get an access token (choose one method):
|
|
|
|
**Option A: OAuth2 Flow (Recommended)**
|
|
```bash
|
|
uv run python src/meta_api_grabber/auth.py
|
|
```
|
|
This will:
|
|
- Generate an authorization URL
|
|
- Walk you through the OAuth2 flow
|
|
- Offer to save the access token to `.env` automatically
|
|
|
|
**Option B: Manual Token**
|
|
- Get a token from [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
|
|
- Add it manually to `.env` as `META_ACCESS_TOKEN`
|
|
|
|
## Usage
|
|
|
|
Run the insights grabber:
|
|
```bash
|
|
uv run python src/meta_api_grabber/insights_grabber.py
|
|
```
|
|
|
|
This will:
|
|
- Fetch insights for the last 7 days
|
|
- Grab account-level, campaign-level (top 10), and ad set-level (top 10) data
|
|
- Save results to `data/meta_insights_TIMESTAMP.json`
|
|
|
|
### Authentication Scripts
|
|
|
|
**Get OAuth2 Access Token:**
|
|
```bash
|
|
uv run python src/meta_api_grabber/auth.py
|
|
```
|
|
|
|
**Grab Insights Data:**
|
|
```bash
|
|
uv run python src/meta_api_grabber/insights_grabber.py
|
|
```
|
|
|
|
## Data Collected
|
|
|
|
### Account Level
|
|
- Impressions, clicks, spend
|
|
- CPC, CPM, CTR
|
|
- Reach, frequency
|
|
- Actions and cost per action
|
|
|
|
### Campaign Level (top 10)
|
|
- Campaign name and ID
|
|
- Impressions, clicks, spend
|
|
- CTR, CPC
|
|
|
|
### Ad Set Level (top 10)
|
|
- Ad set name and ID
|
|
- Impressions, clicks, spend
|
|
- CTR, CPM
|
|
|
|
## Rate Limiting
|
|
|
|
The script is configured to be very conservative:
|
|
- 2 seconds delay between API requests
|
|
- Only 1 concurrent request at a time
|
|
- Limited to top 10 campaigns and ad sets
|
|
|
|
You can adjust these settings in the `MetaInsightsGrabber` class if needed.
|
|
|
|
## Output
|
|
|
|
Data is saved to `data/meta_insights_TIMESTAMP.json` with the following structure:
|
|
```json
|
|
{
|
|
"account": { ... },
|
|
"campaigns": { ... },
|
|
"ad_sets": { ... },
|
|
"summary": { ... }
|
|
}
|
|
```
|