{"id":22966369,"url":"https://github.com/favstats/metatargetr","last_synced_at":"2025-08-13T09:33:26.148Z","repository":{"id":62746382,"uuid":"554276893","full_name":"favstats/metatargetr","owner":"favstats","description":"Retrieve and Parse Meta Ad Targeting Data","archived":false,"fork":false,"pushed_at":"2024-07-08T13:21:10.000Z","size":217,"stargazers_count":30,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-07-08T16:39:23.437Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/favstats.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-19T14:41:46.000Z","updated_at":"2024-07-08T13:21:14.000Z","dependencies_parsed_at":"2024-07-08T16:33:51.974Z","dependency_job_id":"9e26910d-7f8f-4d2e-a669-84e42c93e0ea","html_url":"https://github.com/favstats/metatargetr","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/favstats%2Fmetatargetr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/favstats%2Fmetatargetr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/favstats%2Fmetatargetr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/favstats%2Fmetatargetr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/favstats","download_url":"https://codeload.github.com/favstats/metatargetr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229754831,"owners_count":18119131,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-14T20:42:52.058Z","updated_at":"2025-08-13T09:33:26.127Z","avatar_url":"https://github.com/favstats.png","language":"R","funding_links":["https://www.buymeacoffee.com/favstats)!","https://www.buymeacoffee.com/favstats","https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026emoji=\u0026slug=favstats\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Arial\u0026outline_colour=000000\u0026coffee_colour=ffffff"],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\n# metatargetr \u003cimg src=\"man/figures/metatargetr_logo.png\" width=\"160px\" align=\"right\"/\u003e\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n\u003c!-- badges: start --\u003e\n[![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-lightblue.svg)](https://lifecycle.r-lib.org/articles/stages.html#maturing)\n[![CRAN status](https://www.r-pkg.org/badges/version/metatargetr)](https://CRAN.R-project.org/package=metatargetr)\n\u003c!-- badges: end --\u003e\n\nThe goal of `metatargetr` is to parse targeting information from the [Meta Ad Targeting dataset](https://developers.facebook.com/docs/fort-ads-targeting-dataset/) and retrieve data from the [Audience tab](https://www.facebook.com/ads/library/?active_status=all\u0026ad_type=political_and_issue_ads\u0026country=NL\u0026view_all_page_id=175740570505\u0026sort_data[direction]=desc\u0026sort_data[mode]=relevancy_monthly_grouped\u0026search_type=page\u0026media_type=all) in the Meta Ad Library. It also includes helper functions for Meta ad library data and integrates data from the Google Transparency Report.\n\n\n💡 *Support Open-Source Development*\n\nIf `metatargetr` has been helpful to you, consider [supporting the project](https://www.buymeacoffee.com/favstats)! Every contribution keeps the maintenance work going and helps me develop new features 😊\n\n```{=html}\n\u003cdiv style=\"text-align: right;\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/favstats\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026emoji=\u0026slug=favstats\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Arial\u0026outline_colour=000000\u0026coffee_colour=ffffff\" alt=\"Buy Me a Coffee\" style=\"height: 40px; width: auto;\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n```\n---\n\n## Table of Contents\n\n- 🚀 [Installation](#installation)  \n- 📦 [Load in Package](#load-in-package)  \n- 🎯 [Get Targeting Criteria](#get-targeting-criteria)  \n  - ⏳ [Last 30 Days](#get-targeting-criteria-last-30-days)  \n  - 🗓️ [Last 7 Days](#get-targeting-criteria-last-7-days)  \n- 🕰️ [Retrieve Historical Targeting Data](#retrieve-historical-targeting-data-from-database)  \n- 🗂️ [Retrieve Historical Report Data](#retrieve-historical-report-data-from-the-database)  \n- ℹ️ [Get Page Info](#get-page-info)  \n- 🔍 [Retrieve Targeting Metadata](#retrieve-targeting-metadata)  \n- 🖼️ [Get Images and Videos](#get-images-and-videos)  \n- 📊 [Google Transparency Report](#google-transparency-report)  \n  - 💰 [Retrieve Aggregated Spending Data](#retrieve-aggregated-spending-data)  \n  - 📈 [Retrieve Time-Based Spending Data](#retrieve-time-based-spending-data)  \n- ✍️ [Citing metatargetr](#citing-metatargetr)\n\n---\n\n## Installation\n\nYou can install the development version of metatargetr like so:\n\n``` r\nremotes::install_github(\"favstats/metatargetr\")\n```\n\n## Load in Package\n\n\n```{r example}\nlibrary(metatargetr)\n```\n\n## Get Targeting Criteria (Last 30 Days)\n\nThe following code retrieves the targeting criteria used by the main page of the VVD (Dutch party) in the last 30 days of available data. \n\nJust put in the right *Page ID*. These can be found in the [Meta Ad Library](https://www.facebook.com/ads/library/) or the [Meta Ad Library Report](https://www.facebook.com/ads/library/report/). You can also [retrieve historical report data](#retrieve-historical-report-data-from-the-database) from the maintained database.\n\n```{r}\n\nlast30 \u003c- get_targeting(id = \"121264564551002\", \n                        timeframe = \"LAST_30_DAYS\")\n\nhead(last30, 5)\n\n```\n\n## Get Targeting Criteria (Last 7 Days)\n\nThe following code retrieves the targeting criteria used by the main page of the VVD (Dutch party) in the last 7 days. Just put in the right Page ID.\n\n```{r}\nlast7 \u003c- get_targeting(id = \"121264564551002\", \n                       timeframe = \"LAST_7_DAYS\")\n\n\nhead(last7, 5)\n```\n\n## Retrieve *Historical* Targeting Data from Database\n\nUnfortunately, using `get_targeting` **you can only get the targeting criteria in the last 7, 30, and 90 days windows**. However, I have set up scrapers that retrieve the daily targeting data for every single page in the world that runs advertisements in order to archive this data. You can use the function below to retrieve it. \n\n\u003e Be aware: sometimes the scrapers do not work so it is possible that some pages are missing. You can use [`get_targeting_metadata`](#get-targeting-metadata) function to check which data for which country and day is present. \n\n```{r}\n# # set some parameters\nthe_cntry \u003c- \"DE\"\ntf \u003c- 30\nds \u003c- \"2024-10-25\"\n\n# # Call the function\nlatest_data \u003c- get_targeting_db(the_cntry, tf, ds)\n\n# # Inspect the data\nhead(latest_data)\n```\n\n## Retrieve *Historical* Report Data from the Database\n\nUsing `get_report_db`, you can retrieve archived advertising reports for specific pages, countries, and timeframes. Reports are stored in a repository and can be downloaded and read directly into R.\n\n\u003e\tNote: While we strive to keep the archive complete, occasional scraper failures may lead to missing data for certain days.\n\n```{r}\n# # set some parameters\nthe_cntry \u003c- \"DE\"\ntf \u003c- 30\nds \u003c- \"2024-10-25\"\n\n# # Call the function\nlatest_data \u003c- get_report_db(the_cntry, tf, ds)\n\n# # Inspect the data\nhead(latest_data)\n```\n\n## Get Page Info\n\nYou can also retrieve some page info of the page that you are interested in.\n\n```{r}\npage_info \u003c- get_page_insights(\"121264564551002\", include_info = \"page_info\")\n\n\nstr(page_info)\n```\n\n## `get_targeting_metadata()`\n\nThe `get_targeting_metadata` function is designed to retrieve metadata about targeting data releases from a GitHub repository to see which data is present (or not). It extracts and organizes information such as file names, sizes, timestamps, and tags for a specified country and timeframe. **This metadata provides an overview of the available targeting data without downloading the actual files.**\n\n- `country_code` (*Character*):  \n  The ISO country code (e.g., `\"DE\"` for Germany, `\"US\"` for the United States).  \n\n- `timeframe` (*Character*):  \n  The timeframe for the targeting data. Acceptable values are:\n  - `\"7\"`: Last 7 days.\n  - `\"30\"`: Last 30 days.\n  - `\"90\"`: Last 90 days.\n\n- `base_url` (*Character*, default: `\"https://github.com/favstats/meta_ad_targeting/releases/expanded_assets/\"`):  \n  The base URL for the GitHub repository hosting the targeting data.\n\n\n```{r}\n\n# Retrieve metadata for Germany for the last 30 days\nmetadata \u003c- get_targeting_metadata(\"DE\", \"30\")\n\nprint(metadata)\n\n```\n\n\n## Get Images and Videos\n\nThe following code downloads the images and videos of a Meta ad. It also retrieves additional info not present in the Meta Ad Library API (e.g. `page_like_count` `cta_type` i.e. call to action button). Just put in the right Ad Archive ID.\n\nIt automatically handles duplicate images and videos (of which there are many) by hashing the images and videos and making sure they are not saved twice.\n\nThis piece of code was created in collaboration with [Philipp Mendoza](https://www.uva.nl/en/profile/m/e/p.m.mendoza/p.m.mendoza.html).\n\n```{r}\n\nget_ad_snapshots(\"561403598962843\", download = T, hashing = T, mediadir = \"data/media\")\n\n```\n\n## Google Transparency Report\n\n`ggl_get_spending` is a function in R that queries the Google Transparency Report to retrieve information about advertising spending for a specified advertiser. It supports a range of countries and can provide either aggregated data or time-based spending data.\n\nTo use `ggl_get_spending`, you need the advertiser's unique identifier, the desired date range, and the country code. The function also has an option to retrieve time-based spending data.\n\n### Retrieve Aggregated Spending Data\n\nRetrieve aggregated spending data for a specific advertiser in the Netherlands. It returns details like currency, number of ads, ad type breakdown, advertiser details, and other metrics.\n \n```{r}\n\nggl_get_spending(advertiser_id = \"AR18091944865565769729\", \n                 start_date = \"2023-10-24\", \n                 end_date = \"2023-11-22\",\n                 cntry = \"NL\")\n```\n\n### Retrieve Time-Based Spending Data\n\nRetrieve time-based spending data for the same advertiser and country. If `get_times` is set to `TRUE`, it returns a tibble with date-wise spending data.\n\n\n```{r}\n# Retrieve time-based spending data for the same advertiser and country\ntimeseries_dat \u003c- ggl_get_spending(advertiser_id = \"AR18091944865565769729\", \n                                   start_date = \"2023-10-24\", \n                                   end_date = \"2023-11-22\", \n                                   cntry = \"NL\", \n                                   get_times = T)\n\n# Plotting the time-series data\ntimeseries_dat %\u003e% \n    ggplot2::ggplot(ggplot2::aes(date, spend)) +\n    ggplot2::geom_col() +\n    ggplot2::theme_minimal()\n```\n\n\n\n\n---\n\n## Citing `metatargetr`\n\nIf you use the `metatargetr` package or data from its database in your research, publications, or other outputs, please ensure you provide proper attribution. This helps recognize the effort and resources required to maintain and provide access to these data.\n\n### Citation Format\n\n\u003e \tVotta, Fabio, \u0026 Mendoza, Philipp. (2024). `metatargetr`: A package for parsing and analyzing ad library and targeting data. GitHub. Available at: https://github.com/favstats/metatargetr\n\n### BibTeX Entry\n\n```bibtex\n@misc{votta2024metatargetr,\n  author = {Votta, Fabio and Mendoza, Philipp},\n  title = {metatargetr: A package for parsing and analyzing ad library and targeting data},\n  year = {2024},\n  publisher = {GitHub},\n  url = {https://github.com/favstats/metatargetr}\n}\n```\n\n### Additional Notes\n\nIf you use data from the `metatargetr` database, please include the following acknowledgement in your work:\n\n\u003e Data were retrieved from the `metatargetr` database, maintained by Fabio Votta. The database archives targeting data from the Meta Ad Library and Google Transparency Report. For more information, visit https://github.com/favstats/metatargetr.\n\nBy including these citations and acknowledgements, you help support the continued development of `metatargetr` and its associated resources. Thank you for your collaboration! \n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffavstats%2Fmetatargetr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffavstats%2Fmetatargetr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffavstats%2Fmetatargetr/lists"}