# Snapchat Ads Library Scraper (`automation-lab/snapchat-ads-library-scraper`) Actor Download and filter public Snapchat political ads archive records from Snap's transparency ZIP files. - **URL**: https://apify.com/automation-lab/snapchat-ads-library-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Marketing - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Snapchat Ads Library Scraper Extract public Snapchat political ads archive records from Snap's transparency ZIP files. This Apify Actor downloads the official Snap political advertising archive, parses the yearly `PoliticalAds.csv` files, normalizes spend, impressions, dates, advertiser names, creative URLs, and targeting fields, then saves one dataset row per ad record. Use it when you need repeatable monitoring of Snapchat political advertisers without manually downloading ZIP files from Snap's transparency page. ### What does Snapchat Ads Library Scraper do? Snapchat Ads Library Scraper automates the public Snap political ads archive workflow. It can: - ๐Ÿ“ฆ Download selected yearly Snap political ads ZIP archives - ๐Ÿงพ Parse the `PoliticalAds.csv` archive files - ๐Ÿ’ฐ Extract spend, currency, and impression counts - ๐Ÿง‘โ€๐Ÿ’ผ Extract organization, paying advertiser, committee, and disclosure fields - ๐Ÿ—“๏ธ Normalize start and end dates - ๐ŸŽฏ Preserve targeting fields such as country, regions, interests, OS, age, gender, language, postal codes, and metros - ๐ŸŽฌ Return creative URLs and media type hints - ๐Ÿ”Ž Filter by year, advertiser, country, date range, and free-text search terms - ๐Ÿงฐ Include raw archive columns when you need audit-grade exports ### Who is it for? This scraper is built for teams that monitor paid political communication on social platforms. Typical users include: - ๐Ÿ›๏ธ Political compliance teams tracking paid Snapchat election ads - ๐Ÿ“Š Ad-intelligence analysts comparing spend and impressions across advertisers - ๐Ÿ“ฐ Journalists and researchers investigating public political advertising archives - ๐Ÿง‘โ€โš–๏ธ Public affairs and legal teams documenting disclosures - ๐Ÿข Agencies monitoring a candidate, issue group, nonprofit, or advertiser portfolio - ๐Ÿงช Data teams that need structured CSV/JSON exports for dashboards ### Why use this actor? Snap publishes political ad transparency data as yearly downloadable archives. That is useful, but manual ZIP downloads are slow, repetitive, and hard to integrate. This actor turns the archive into an Apify dataset with consistent field names and filters. Use it when you need: - repeatable scheduled monitoring, - one API call instead of a manual download, - structured JSON, CSV, Excel, or API output, - consistent field names across archive years, - a small filtered extract instead of the whole archive, - or raw fields for compliance review. ### What data can you extract? | Field | Description | | --- | --- | | `adId` | Snap archive ad identifier | | `archiveYear` | Year inferred from the downloaded archive URL | | `creativeUrl` | Snap-hosted creative asset URL when present | | `mediaType` | Media type inferred from the creative URL | | `currencyCode` | Spend currency code | | `spend` | Numeric spend value | | `impressions` | Numeric impression count | | `startDate` | Normalized ad start timestamp | | `endDate` | Normalized ad end timestamp when present | | `organizationName` | Organization from the Snap archive | | `payingAdvertiserName` | Paying advertiser name | | `committeeName` | Committee name | | `disclosureNameOfCommittee` | Disclosure committee name | | `countryCode` | Country/country-code field from the archive | | `regionsIncluded` | Included region targeting | | `regionsExcluded` | Excluded region targeting | | `interests` | Interest targeting | | `language` | Language targeting | | `osType` | OS targeting | | `ageBracket` | Age targeting | | `gender` | Gender targeting | | `creativeProperties` | Creative metadata field from the archive | | `rawFields` | Optional original archive columns | ### How much does it cost to scrape Snapchat political ads? The actor uses pay-per-event pricing. - Start event: a small one-time fee per run. - Item event: a tiered fee per ad record saved to the dataset. The exact platform pricing is visible on the Apify Store page. Use `maxItems` and filters to keep test runs small. ### Input options #### `years` Archive years to download. Snap archives are available as yearly ZIP files. The default input uses the latest public archive year. Example: ```json { "years": ["2026"], "maxItems": 100 } ```` #### `archiveUrls` Optional direct ZIP URLs. Use this only when Snap publishes a new archive URL before the schema is updated, or when you need to test a mirrored archive. #### `maxItems` Maximum matching ad records to save. For first tests, keep this at 100 or less. For production monitoring, raise it based on the archive size and your export needs. #### `advertiserNames` Case-insensitive advertiser filters matched against organization, paying advertiser, committee, and disclosure names. #### `countryCodes` Filters the archive `CountryCode` field. Snap sometimes stores country names and sometimes code-like values, so use the exact form you see in your target archive when possible. #### `searchTerms` Free-text filters matched across advertiser, creative URL, targeting, language, OS, age, gender, regions, and creative metadata. #### `startDate` and `endDate` Date range filters for ads active in a window. #### `includeRawFields` Set to `true` to include the original Snap archive column names and values in each output row. ### Example input: latest archive ```json { "years": ["2026"], "maxItems": 100, "includeRawFields": false } ``` ### Example input: advertiser monitoring ```json { "years": ["2026"], "advertiserNames": ["Human Appeal"], "countryCodes": ["united arab emirates"], "maxItems": 50 } ``` ### Example input: multi-year targeting audit ```json { "years": ["2025", "2026"], "searchTerms": ["election"], "startDate": "2025-01-01", "maxItems": 250, "includeRawFields": true } ``` ### Output example ```json { "adId": "f917ba828f9b6dcbd5b6dfff8e1210d04812f9fb40d916df84ddfaa7866f85ca", "archiveYear": 2026, "creativeUrl": "https://www.snap.com/political-ads/asset/...", "mediaType": "mp4", "currencyCode": "GBP", "spend": 10, "impressions": 2144, "startDate": "2026-05-07T19:14:44.000Z", "organizationName": "Human Appeal Arabic", "payingAdvertiserName": "HUMAN APPEAL", "countryCode": "united arab emirates", "language": "ar", "osType": "IOS" } ``` ### How to run 1. Choose one or more archive years. 2. Add optional filters for advertiser, country, dates, or search terms. 3. Set `maxItems`. 4. Run the actor. 5. Export the dataset as JSON, CSV, Excel, XML, RSS, or HTML. ### Tips for best results - Start with one year and `maxItems: 100`. - Add filters only after confirming the archive contains the fields you expect. - Use `includeRawFields: true` for compliance audits or when Snap changes columns. - Use scheduled runs for repeat monitoring. - Use multiple small targeted runs for advertiser watchlists. ### Integrations You can connect the dataset to: - Google Sheets for analyst review, - BigQuery or Snowflake for long-term ad intelligence, - Slack or email alerts for new advertiser matches, - compliance dashboards, - newsroom research notebooks, - or CRM/enrichment pipelines. A common workflow is to schedule one run per archive year, filter by advertiser watchlist, and send new rows to a review queue. ### API usage: Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/snapchat-ads-library-scraper').call({ years: ['2026'], maxItems: 100, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items.slice(0, 3)); ``` ### API usage: Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('automation-lab/snapchat-ads-library-scraper').call(run_input={ 'years': ['2026'], 'maxItems': 100, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items[:3]) ``` ### API usage: cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~snapchat-ads-library-scraper/runs?token=YOUR_APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"years":["2026"],"maxItems":100}' ``` ### MCP usage Use the Apify MCP server with this actor when you want Claude Desktop or Claude Code to run archive checks from natural language. MCP URL: ```text https://mcp.apify.com/?tools=automation-lab/snapchat-ads-library-scraper ``` Claude Code setup: ```bash claude mcp add apify-snapchat-ads --transport http "https://mcp.apify.com/?tools=automation-lab/snapchat-ads-library-scraper" ``` Claude Desktop JSON config: ```json { "mcpServers": { "apify-snapchat-ads": { "url": "https://mcp.apify.com/?tools=automation-lab/snapchat-ads-library-scraper" } } } ``` Example prompts: - "Run the Snapchat Ads Library Scraper for 2026 and summarize the top advertisers by spend." - "Find Snap political ads mentioning election in 2025 and 2026." - "Export the latest Snapchat political ads archive records as CSV." ### Scheduling For monitoring workflows, schedule the actor weekly or monthly. Political ad archives may update over time, so scheduled pulls help maintain a historical local copy. ### Data source The actor uses Snap's public political ads transparency archives linked from `https://www.snap.com/political-ads`. It does not require a Snapchat login, browser automation, cookies, or private APIs. ### Limitations - The actor depends on the public archive files Snap makes available. - Column names may drift between years. - Some records may omit optional fields such as end date, targeting, committee, or creative metadata. - Creative asset availability is controlled by Snap. ### Legality This actor extracts public transparency archive data. You are responsible for using the data lawfully, respecting Snap's terms, and complying with privacy, election, and advertising regulations in your jurisdiction. ### FAQ #### Is this an official Snapchat API? No. The actor downloads and parses public transparency archive ZIP files linked from Snap's political ads page. #### Can I scrape all years? Yes. Add multiple values to `years`, but start with one year while testing so runs stay fast and inexpensive. ### Troubleshooting #### Why did I get zero results? Your filters may be too narrow. Try removing `advertiserNames`, `countryCodes`, `searchTerms`, and date filters, then run one archive year with a small `maxItems`. #### Why is a country value not matching? Snap's archive field may contain a country name rather than a two-letter code. Inspect a broad sample or enable `includeRawFields` to see the exact value. #### Why is `endDate` empty? Many archive records do not include an end date. The actor returns `null` when Snap leaves it blank. ### Related scrapers Other automation-lab actors that can complement this one: - https://apify.com/automation-lab/google-ads-transparency-center-scraper - https://apify.com/automation-lab/facebook-ads-library-scraper - https://apify.com/automation-lab/pinterest-ads-library-scraper - https://apify.com/automation-lab/tiktok-creative-center-scraper ### Changelog Initial version: - public Snap political ads ZIP download, - CSV parsing, - normalized archive fields, - advertiser/country/date/search filters, - optional raw field output. ### Support If a run fails, include the run ID, input JSON, archive year, and the filter values you used when reporting the issue. # Actor input Schema ## `years` (type: `array`): Snap political ads archive years to download. Leave empty to use the latest available year. ## `archiveUrls` (type: `array`): Optional direct PoliticalAds.zip URLs. Use only when you need a custom or newly published archive not covered by years. ## `maxItems` (type: `integer`): Maximum matching ad records to emit. ## `advertiserNames` (type: `array`): Case-insensitive filters matched against organization, paying advertiser, committee, and disclosure names. ## `countryCodes` (type: `array`): Filter the archive CountryCode field. Examples: US, GB, united states. ## `searchTerms` (type: `array`): Terms that must appear across advertiser, creative URL, targeting, region, language, or creative fields. ## `startDate` (type: `string`): Include ads active on or after this date. Accepts YYYY-MM-DD or full timestamps. ## `endDate` (type: `string`): Include ads active on or before this date. Accepts YYYY-MM-DD or full timestamps. ## `includeRawFields` (type: `boolean`): Add rawFields with the original Snap archive column names and values for schema-drift audits. ## Actor input object example ```json { "years": [ "2026" ], "archiveUrls": [], "maxItems": 20, "advertiserNames": [], "countryCodes": [], "searchTerms": [], "includeRawFields": false } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "years": [ "2026" ], "archiveUrls": [], "maxItems": 20, "advertiserNames": [], "countryCodes": [], "searchTerms": [], "startDate": "", "endDate": "", "includeRawFields": false }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/snapchat-ads-library-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "years": ["2026"], "archiveUrls": [], "maxItems": 20, "advertiserNames": [], "countryCodes": [], "searchTerms": [], "startDate": "", "endDate": "", "includeRawFields": False, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/snapchat-ads-library-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "years": [ "2026" ], "archiveUrls": [], "maxItems": 20, "advertiserNames": [], "countryCodes": [], "searchTerms": [], "startDate": "", "endDate": "", "includeRawFields": false }' | apify call automation-lab/snapchat-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/snapchat-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Snapchat Ads Library Scraper", "description": "Download and filter public Snapchat political ads archive records from Snap's transparency ZIP files.", "version": "0.1", "x-build-id": "Ew6gAKtfZp2j8Oa8r" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~snapchat-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-snapchat-ads-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automation-lab~snapchat-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-snapchat-ads-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automation-lab~snapchat-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-snapchat-ads-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "years": { "title": "Archive years", "type": "array", "description": "Snap political ads archive years to download. Leave empty to use the latest available year.", "items": { "type": "string" } }, "archiveUrls": { "title": "Custom archive ZIP URLs", "type": "array", "description": "Optional direct PoliticalAds.zip URLs. Use only when you need a custom or newly published archive not covered by years.", "items": { "type": "string" } }, "maxItems": { "title": "Maximum ads", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Maximum matching ad records to emit.", "default": 20 }, "advertiserNames": { "title": "Advertiser or organization names", "type": "array", "description": "Case-insensitive filters matched against organization, paying advertiser, committee, and disclosure names.", "items": { "type": "string" } }, "countryCodes": { "title": "Country codes or names", "type": "array", "description": "Filter the archive CountryCode field. Examples: US, GB, united states.", "items": { "type": "string" } }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Terms that must appear across advertiser, creative URL, targeting, region, language, or creative fields.", "items": { "type": "string" } }, "startDate": { "title": "Earliest active date", "type": "string", "description": "Include ads active on or after this date. Accepts YYYY-MM-DD or full timestamps." }, "endDate": { "title": "Latest active date", "type": "string", "description": "Include ads active on or before this date. Accepts YYYY-MM-DD or full timestamps." }, "includeRawFields": { "title": "Include raw archive fields", "type": "boolean", "description": "Add rawFields with the original Snap archive column names and values for schema-drift audits.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```