diff --git a/.Rbuildignore b/.Rbuildignore index c52aaf0..e397e84 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -3,3 +3,7 @@ ^LICENSE\.md$ ^README\.Rmd$ ^cran-comments\.md$ +^_pkgdown\.yml$ +^docs$ +^pkgdown$ +^\.github$ diff --git a/.github/.gitignore b/.github/.gitignore new file mode 100644 index 0000000..2d19fc7 --- /dev/null +++ b/.github/.gitignore @@ -0,0 +1 @@ +*.html diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml new file mode 100644 index 0000000..bfc9f4d --- /dev/null +++ b/.github/workflows/pkgdown.yaml @@ -0,0 +1,49 @@ +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples +# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help +on: + push: + branches: [main, master] + pull_request: + release: + types: [published] + workflow_dispatch: + +name: pkgdown.yaml + +permissions: read-all + +jobs: + pkgdown: + runs-on: ubuntu-latest + # Only restrict concurrency for non-PR jobs + concurrency: + group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + + - uses: r-lib/actions/setup-pandoc@v2 + + - uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + extra-packages: any::pkgdown, local::. + needs: website + + - name: Build site + run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) + shell: Rscript {0} + + - name: Deploy to GitHub pages ๐Ÿš€ + if: github.event_name != 'pull_request' + uses: JamesIves/github-pages-deploy-action@v4.5.0 + with: + clean: false + branch: gh-pages + folder: docs diff --git a/.gitignore b/.gitignore index 57a0904..ebda0e0 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ .httr-oauth .DS_Store data +docs diff --git a/DESCRIPTION b/DESCRIPTION index 9be02e9..b5fe5b8 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -28,5 +28,5 @@ Suggests: OpenImageR, testthat (>= 3.0.0), arrow -URL: https://github.com/favstats/metatargetr +URL: https://github.com/favstats/metatargetr, https://favstats.github.io/metatargetr/ BugReports: https://github.com/favstats/metatargetr/issues diff --git a/NAMESPACE b/NAMESPACE index d5376db..d198a9f 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -12,15 +12,23 @@ export(get_targeting_db) export(ggl_get_spending) export(map_dfr_progress) export(parse_location) +export(retrieve_targeting_metadata) export(stupid_conversion) export(unnest_and_fix_dups) export(walk_progress) importFrom(arrow,read_parquet) +importFrom(dplyr,arrange) importFrom(dplyr,bind_cols) +importFrom(dplyr,filter) importFrom(dplyr,left_join) +importFrom(dplyr,mutate) importFrom(dplyr,mutate_all) +importFrom(dplyr,rename) importFrom(dplyr,select) importFrom(dplyr,slice) +importFrom(dplyr,transmute) +importFrom(httr,GET) +importFrom(httr,content) importFrom(httr2,req_body_raw) importFrom(httr2,req_headers) importFrom(httr2,req_perform) @@ -34,7 +42,10 @@ importFrom(purrr,is_empty) importFrom(purrr,map_dfr) importFrom(purrr,set_names) importFrom(rvest,html_element) +importFrom(rvest,html_elements) importFrom(rvest,html_text) importFrom(stringr,str_remove) importFrom(stringr,str_split) importFrom(tibble,as_tibble) +importFrom(tibble,tibble) +importFrom(tidyr,separate) diff --git a/R/data.R b/R/data.R index d910cc6..99b5d46 100644 --- a/R/data.R +++ b/R/data.R @@ -72,29 +72,6 @@ get_targeting_db <- function(the_cntry, tf, ds, remove_nas = T, verbose = F) { # latest_data %>% filter(is.na(no_data)) - -#' Retrieve Report Data from GitHub Repository -#' -#' This function retrieves a report for a specific country and timeframe -#' from a GitHub repository hosting RDS files. The file is downloaded -#' to a temporary location, read into R, and then deleted. -#' -#' @param the_cntry Character. The ISO country code (e.g., "DE", "US"). -#' @param timeframe Character. One of "-yesterday", "-last_7_days", "-last_30_days", "-last_90_days", or "-lifelong". -#' @param file_name Character. The name of the RDS file to download (e.g., "report_2024-12-25.rds"). -#' @param verbose Logical. Whether to print messages about the process. Default is `FALSE`. -#' @return A data frame or object read from the RDS file. -#' @export -#' -#' @examples -#' # Example usage -#' report_data <- get_report_db( -#' the_cntry = "DE", -#' timeframe = "-last_30_days", -#' file_name = "report_2024-12-25.rds", -#' verbose = TRUE -#' ) -#' print(head(report_data)) #' Retrieve Report Data from GitHub Repository #' #' This function retrieves a report for a specific country and timeframe @@ -185,3 +162,77 @@ get_report_db <- function(the_cntry, timeframe, ds, verbose = FALSE) { # ds = "2024-10-25", # verbose = TRUE # ) + + +#' Retrieve Metadata for Targeting Data +#' +#' This function retrieves metadata for targeting data releases for a specific +#' country and timeframe from a GitHub repository. +#' +#' @param country_code Character. The ISO country code (e.g., "DE", "US"). +#' @param timeframe Character. The timeframe to filter (e.g., "7", "30", or "90"). +#' @param base_url Character. The base URL for the GitHub repository. Defaults to +#' `"https://github.com/favstats/meta_ad_targeting/releases/"`. +#' @return A data frame containing metadata about available targeting data, +#' including file names, sizes, timestamps, and tags. +#' @importFrom httr GET content +#' @importFrom rvest html_elements html_text +#' @importFrom dplyr transmute mutate filter rename arrange +#' @importFrom tidyr separate +#' @importFrom tibble tibble +#' @export +#' +#' @examples +#' # Retrieve metadata for Germany for the last 30 days +#' metadata <- retrieve_targeting_metadata("DE", "30") +#' print(metadata) +retrieve_targeting_metadata <- function(country_code, + timeframe, + base_url = "https://github.com/favstats/meta_ad_targeting/releases/expanded_assets/") { + # Validate inputs + if (missing(country_code)) { + stop("Parameter `country_code` is required.") + } + + if (missing(timeframe) || !timeframe %in% c("7", "30", "90")) { + stop("`timeframe` must be one of: '7', '30', or '90'.") + } + + # Timeframe suffix for filtering + timeframe_suffix <- paste0("-last_", timeframe, "_days") + + # Construct the full URL + url <- paste0(base_url, country_code, timeframe_suffix) + + # Fetch the data + response <- httr::GET(url) + + if (httr::status_code(response) != 200) { + stop("Failed to retrieve metadata from: ", url, ". Status code: ", httr::status_code(response)) + } + + html_content <- xml2::read_html(httr::content(response, as = "text", encoding = "UTF-8")) + + raw_elements <- rvest::html_elements(html_content, ".Box-row") %>% + rvest::html_text() + + metadata <- tibble::tibble(raw = raw_elements) %>% + dplyr::mutate(raw = strsplit(as.character(raw), "\n")) %>% + dplyr::transmute( + filename = sapply(raw, function(x) trimws(x[3])), + file_size = sapply(raw, function(x) trimws(x[6])), + timestamp = sapply(raw, function(x) trimws(x[7])) + ) %>% + dplyr::filter(filename != "Source code") %>% + dplyr::mutate(release = paste0(country_code, timeframe_suffix)) %>% + dplyr::mutate_all(as.character) %>% + dplyr::rename(tag = release, file_name = filename) %>% + dplyr::arrange(desc(tag)) %>% + tidyr::separate(tag, into = c("cntry", "tframe"), sep = "-", remove = FALSE) %>% + dplyr::mutate(ds = stringr::str_remove(file_name, "\\.rds|\\.zip|\\.parquet")) %>% + dplyr::distinct(cntry, ds, tframe) %>% + tidyr::drop_na(ds) %>% + dplyr::arrange(desc(ds)) + + return(metadata) +} diff --git a/R/get_page_insights.R b/R/get_page_insights.R index 6dff14b..794ba76 100644 --- a/R/get_page_insights.R +++ b/R/get_page_insights.R @@ -53,9 +53,6 @@ if("page_info" %in% include_info ){ ua <- sample(ua_list, 1) # print(ua) -# pageid <- "7860876103" -# timeframe <- "90" - # Define static parameters static_params <- list( av = "0", # Likely application version; may not change often. Optional. @@ -64,20 +61,8 @@ static_params <- list( a = "1", # Arbitrary request parameter; purpose unclear but likely required. req = "3", # Request parameter; often a sequence or batch request identifier. Likely required. hs = "19797.BP%3ADEFAULT.2.0..0.0", # Host session or configuration metadata; required for server-side routing. - # dpr = "1", # Device Pixel Ratio; reflects screen resolution. Optional but often included. ccg = "EXCELLENT", # Connection grade; describes network quality. Optional but useful for server-side optimizations. - # rev = "1012093869", # Revision/version number; likely application or API version. Required. - # s = "sbbnic%3Awquopy%3A7r1j3c", # Session token or tracking identifier; unique to the visitor. Required. - # hsi = "7346737420686302672", # Hashed Session ID; unique to the visitor. Required. - # dyn = "7xe6Eiw_K9zo5ObwKBAgc9o2exu13wqojyUW3qi4EoxW4E7SewXwCwfW7oqx60Vo1upEK12wvk1bwbG78b87C2m3K2y11wBw5Zx62G3i1ywdl0Fw4Hwp8kwyx2cU8EmwoHwrUcUjwVw9O7bK2S2W2K4EG1Mxu16wciaw4JwJwSyES0gq0K-1LwqobU2cwmo6O1Fw44wt8", - # Dynamic parameters encoded in a proprietary format; likely unique to each request. Required. - csr = "", # CSRF token; placeholder here, likely required in some contexts. - # lsd = "AVo6-wl7l1Q", # Login session data; required for session validation. - # jazoest = "2881", # CSRF-related field; required for security checks. - # spin_r = "1012093869", # Spin-related metadata (server-specific session management). Required. - # spin_b = "trunk", # Backend branch/version. Required for routing to the correct API version. - # spin_t = "1710545602", # Server timestamp. Required for ensuring request freshness. `_jssesw` = "1", # Encoded session value. Required for session management. fb_api_caller_class = "RelayModern", # API metadata describing the client. Required. fb_api_req_friendly_name = "AdLibraryMobileFocusedStateProviderQuery", # API-friendly name for request logging. Optional. @@ -97,9 +82,6 @@ variables <- jsonlite::toJSON( active_status = "ALL", # Filter for active/inactive ads. Required. ad_type = "POLITICAL_AND_ISSUE_ADS", # Type of ads (repeated for clarity). Required. bylines = list(), # List of bylines to filter ads. Optional. - # collation_token = "7ca3912f-0148-43ce-83e4-9a68ef656e4d", - # Unique token for grouping or collation; may be session-based. Likely required. - content_languages = list(), # Filter for content languages. Optional. count = 30, # Number of results to fetch. Optional but usually required for pagination. countries = list(iso2c), # List of countries for filtering (repeated for clarity). Required. @@ -107,9 +89,6 @@ variables <- jsonlite::toJSON( full_text_search_field = "ALL", # Full-text search field filter. Optional. group_by_modes = list(), # Grouping modes for results. Optional. search_type = "PAGE", # Type of search (e.g., by page). Required. - # session_id = "1678877b-700b-485a-abb0-60efcb6b4019", - # Unique session identifier for the query. Required for tracking. - sort_data = list( mode = "SORT_BY_RELEVANCY_MONTHLY_GROUPED", # Sorting mode. Required. direction = "ASCENDING" # Sorting direction. Required. diff --git a/README.Rmd b/README.Rmd index 518868b..47ae173 100644 --- a/README.Rmd +++ b/README.Rmd @@ -115,6 +115,32 @@ page_info <- get_page_insights("121264564551002", include_info = "page_info") str(page_info) ``` +## `retrieve_targeting_metadata()` + +The `retrieve_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.** + +- `country_code` (*Character*): + The ISO country code (e.g., `"DE"` for Germany, `"US"` for the United States). + +- `timeframe` (*Character*): + The timeframe for the targeting data. Acceptable values are: + - `"7"`: Last 7 days. + - `"30"`: Last 30 days. + - `"90"`: Last 90 days. + +- `base_url` (*Character*, default: `"https://github.com/favstats/meta_ad_targeting/releases/expanded_assets/"`): + The base URL for the GitHub repository hosting the targeting data. + + +```{r} + +# Retrieve metadata for Germany for the last 30 days +metadata <- retrieve_targeting_metadata("DE", "30") + +print(metadata) + +``` + ## Get Images and Videos diff --git a/README.md b/README.md index 66031f0..718695f 100644 --- a/README.md +++ b/README.md @@ -182,17 +182,63 @@ str(page_info) #> $ page_verification : chr "BLUE_VERIFIED" #> $ entity_type : chr "PERSON_PROFILE" #> $ page_alias : chr "VVD" -#> $ likes : chr "108141" +#> $ likes : chr "108142" #> $ page_category : chr "Political party" #> $ ig_verification : chr "TRUE" #> $ ig_username : chr "vvd" -#> $ ig_followers : chr "42144" +#> $ ig_followers : chr "42145" #> $ shared_disclaimer_info: chr "[]" #> $ about : chr "Doe mee en word lid van de VVD! ๐Ÿ’™๐Ÿงก " #> $ event : chr "CREATION: 2010-04-23 21:05:02" #> $ no_address : logi TRUE ``` +## `retrieve_targeting_metadata()` + +The `retrieve_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.** + +- `country_code` (*Character*): + The ISO country code (e.g., `"DE"` for Germany, `"US"` for the United + States). + +- `timeframe` (*Character*): + The timeframe for the targeting data. Acceptable values are: + + - `"7"`: Last 7 days. + - `"30"`: Last 30 days. + - `"90"`: Last 90 days. + +- `base_url` (*Character*, default: + `"https://github.com/favstats/meta_ad_targeting/releases/expanded_assets/"`): + The base URL for the GitHub repository hosting the targeting data. + +``` r + +# Retrieve metadata for Germany for the last 30 days +metadata <- retrieve_targeting_metadata("DE", "30") + +print(metadata) +#> # A tibble: 313 ร— 3 +#> cntry ds tframe +#> +#> 1 DE 2024-12-25 last_30_days +#> 2 DE 2024-12-24 last_30_days +#> 3 DE 2024-12-23 last_30_days +#> 4 DE 2024-12-22 last_30_days +#> 5 DE 2024-12-21 last_30_days +#> 6 DE 2024-12-20 last_30_days +#> 7 DE 2024-12-19 last_30_days +#> 8 DE 2024-12-18 last_30_days +#> 9 DE 2024-12-17 last_30_days +#> 10 DE 2024-12-16 last_30_days +#> # โ„น 303 more rows +``` + ## Get Images and Videos The following code downloads the images and videos of a Meta ad. It also @@ -276,4 +322,4 @@ timeseries_dat %>% ggplot2::theme_minimal() ``` - + diff --git a/_pkgdown.yml b/_pkgdown.yml new file mode 100644 index 0000000..39acd4f --- /dev/null +++ b/_pkgdown.yml @@ -0,0 +1,47 @@ +template: + bootstrap: 5 + bootswatch: yeti # A modern theme with clean design + bslib: + bg: "#ffffff" # Page background color + fg: "#000000" # Default text color + primary: "#007bff" # Modern blue color for links and accents + base_font: {google: "Roboto"} + heading_font: {google: "Roboto Slab"} + code_font: {google: "JetBrains Mono"} + light-switch: true # Enable light/dark mode switching + +navbar: + bg: "#007bff" # Modern blue background color + type: dark # Black text for a light-themed navbar + structure: + left: [intro, reference, articles, news] + right: [search, github, lightswitch] + components: + github: + icon: fa-github + href: https://github.com/favstats/metatargetr + aria-label: GitHub + +articles: + - title: "Get Started" + contents: + - introduction + - title: "Working with Targeting Data" + contents: + - retrieving-targeting-data + - retrieve-historical-data + - retrieve-targeting-metadata + - title: "Google Transparency Integration" + contents: + - google-transparency-report + +news: + one_page: true + +footer: + structure: + left: developed_by + right: built_with + components: + developed_by: "Developed by Fabio Votta and Philipp Mendoza." + built_with: "Built with โค๏ธ and pkgdown." diff --git a/man/figures/README-unnamed-chunk-10-1.png b/man/figures/README-unnamed-chunk-10-1.png new file mode 100644 index 0000000..699867a Binary files /dev/null and b/man/figures/README-unnamed-chunk-10-1.png differ diff --git a/man/figures/metatargetr_logo.png b/man/figures/metatargetr_logo.png index a58de41..00c2259 100644 Binary files a/man/figures/metatargetr_logo.png and b/man/figures/metatargetr_logo.png differ diff --git a/man/get_report_db.Rd b/man/get_report_db.Rd index 9d9ed83..6716416 100644 --- a/man/get_report_db.Rd +++ b/man/get_report_db.Rd @@ -14,12 +14,8 @@ get_report_db(the_cntry, timeframe, ds, verbose = FALSE) \item{ds}{Character. A timestamp or identifier used to construct the file name (e.g., "2024-12-25").} \item{verbose}{Logical. Whether to print messages about the process. Default is \code{FALSE}.} - -\item{file_name}{Character. The name of the RDS file to download (e.g., "report_2024-12-25.rds").} } \value{ -A data frame or object read from the RDS file. - A data frame or object read from the RDS file. } \description{ @@ -28,20 +24,6 @@ from a GitHub repository hosting RDS files. The file is downloaded to a temporary location, read into R, and then deleted. } \examples{ -# Example usage -report_data <- get_report_db( - the_cntry = "DE", - timeframe = "-last_30_days", - file_name = "report_2024-12-25.rds", - verbose = TRUE -) -print(head(report_data)) -Retrieve Report Data from GitHub Repository - -This function retrieves a report for a specific country and timeframe -from a GitHub repository hosting RDS files. The file is downloaded -to a temporary location, read into R, and then deleted. - # Example usage report_data <- get_report_db( the_cntry = "DE", diff --git a/man/retrieve_targeting_metadata.Rd b/man/retrieve_targeting_metadata.Rd new file mode 100644 index 0000000..7c1ad99 --- /dev/null +++ b/man/retrieve_targeting_metadata.Rd @@ -0,0 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/data.R +\name{retrieve_targeting_metadata} +\alias{retrieve_targeting_metadata} +\title{Retrieve Metadata for Targeting Data} +\usage{ +retrieve_targeting_metadata( + country_code, + timeframe, + base_url = "https://github.com/favstats/meta_ad_targeting/releases/expanded_assets/" +) +} +\arguments{ +\item{country_code}{Character. The ISO country code (e.g., "DE", "US").} + +\item{timeframe}{Character. The timeframe to filter (e.g., "7", "30", or "90").} + +\item{base_url}{Character. The base URL for the GitHub repository. Defaults to +\code{"https://github.com/favstats/meta_ad_targeting/releases/"}.} +} +\value{ +A data frame containing metadata about available targeting data, +including file names, sizes, timestamps, and tags. +} +\description{ +This function retrieves metadata for targeting data releases for a specific +country and timeframe from a GitHub repository. +} +\examples{ +# Retrieve metadata for Germany for the last 30 days +metadata <- retrieve_targeting_metadata("DE", "30") +print(metadata) +} diff --git a/vignettes/.gitignore b/vignettes/.gitignore new file mode 100644 index 0000000..075b254 --- /dev/null +++ b/vignettes/.gitignore @@ -0,0 +1 @@ +/.quarto/ diff --git a/vignettes/google-transparency-report.qmd b/vignettes/google-transparency-report.qmd new file mode 100644 index 0000000..22f8f92 --- /dev/null +++ b/vignettes/google-transparency-report.qmd @@ -0,0 +1,69 @@ +--- +title: "Google Transparency Report Integration" +description: > + Learn how to access and analyze data from the Google Transparency Report. +vignette: > + %\VignetteIndexEntry{Google Transparency Report Integration} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +knitr: + opts_chunk: + collapse: true + comment: '#>' +--- + +## Accessing Google Transparency Data + +metatargetr provides integration with the Google Transparency Report through the `ggl_get_spending()` function: + +```{r} +#| eval: false +library(metatargetr) +library(ggplot2) + +# Get aggregated spending data +spending_data <- ggl_get_spending( + advertiser_id = "AR18091944865565769729", + start_date = "2023-10-24", + end_date = "2023-11-22", + cntry = "NL" +) +``` + +## Time-Based Analysis + +For temporal analysis, use the `get_times` parameter: + +```{r} +#| eval: false +# Get time-series data +timeseries_data <- ggl_get_spending( + advertiser_id = "AR18091944865565769729", + start_date = "2023-10-24", + end_date = "2023-11-22", + cntry = "NL", + get_times = TRUE +) + +# Create visualization +ggplot(timeseries_data, aes(x = date, y = spend)) + + geom_col() + + theme_minimal() + + labs( + title = "Ad Spending Over Time", + x = "Date", + y = "Spend Amount" + ) +``` + +## Understanding the Metrics + +The Google Transparency Report provides: + +- Total spending amounts + +- Ad type distribution + +- Temporal patterns + +- Regional variations diff --git a/vignettes/introduction.qmd b/vignettes/introduction.qmd new file mode 100644 index 0000000..2e8d03f --- /dev/null +++ b/vignettes/introduction.qmd @@ -0,0 +1,47 @@ +--- +title: "Introduction to metatargetr" +description: > + Get started with metatargetr, learn about its core functionality and basic usage. +vignette: > + %\VignetteIndexEntry{Introduction to metatargetr} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +knitr: + opts_chunk: + collapse: true + comment: '#>' +--- + +## Overview + +metatargetr is an R package designed to parse and analyze targeting information from the Meta Ad Library dataset and retrieve data from the Audience tab. It provides tools for working with Meta ad library data and includes integration with the Google Transparency Report. + +## Installation + +You can install the development version of metatargetr from GitHub: + +```{r} +#| eval: false +# install.packages("remotes") +remotes::install_github("favstats/metatargetr") +``` + +## Basic Usage + +First, load the package: + +```{r} +#| warning: false +#| message: false +library(metatargetr) +``` + +The package provides several core functions: + +1. `get_targeting()`: Retrieve recent targeting data +2. `get_targeting_db()`: Access historical targeting data +3. `get_page_insights()`: Get page information +4. `get_ad_snapshots()`: Download ad creatives +5. `ggl_get_spending()`: Access Google Transparency Report data + +Each of these functions is documented in detail in the following sections. diff --git a/vignettes/retrieve-historical-data.qmd b/vignettes/retrieve-historical-data.qmd new file mode 100644 index 0000000..9f22d0f --- /dev/null +++ b/vignettes/retrieve-historical-data.qmd @@ -0,0 +1,61 @@ +--- +title: "Retrieve Historical Data" +description: > + Learn how to access and work with historical Meta Ad targeting data from the archive. +vignette: > + %\VignetteIndexEntry{Retrieve Historical Data} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +knitr: + opts_chunk: + collapse: true + comment: '#>' +--- + +## Accessing Historical Data + +While Meta's API only provides recent targeting data, metatargetr maintains an archive of historical targeting data. Access this using `get_targeting_db()`: + +```{r} +#| eval: false +library(metatargetr) + +# Set parameters +country_code <- "DE" +timeframe <- 30 +date <- "2024-10-25" + +# Retrieve historical data +historical_data <- get_targeting_db(country_code, timeframe, date) +``` + +## Understanding Historical Data + +The historical data includes: +- Daily targeting snapshots +- Spending information +- Page details +- Targeting criteria used + +## Getting Report Data + +For broader historical analysis, use `get_report_db()`: + +```{r} +#| eval: false +report_data <- get_report_db( + country_code = "DE", + timeframe = 30, + date = "2024-10-25" +) +``` + +This provides aggregated advertising reports including: + +- Total spending + +- Number of ads + +- Page information + +- Temporal data diff --git a/vignettes/retrieve-targeting-metadata.qmd b/vignettes/retrieve-targeting-metadata.qmd new file mode 100644 index 0000000..982a8d0 --- /dev/null +++ b/vignettes/retrieve-targeting-metadata.qmd @@ -0,0 +1,63 @@ +--- +title: "Retrieve Targeting Metadata" +description: > + Understand how to work with targeting metadata and check data availability. +vignette: > + %\VignetteIndexEntry{Retrieve Targeting Metadata} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +knitr: + opts_chunk: + collapse: true + comment: '#>' +--- + +## Overview of Targeting Metadata + +The `retrieve_targeting_metadata()` function helps you understand what targeting data is available in the archive. It provides information about: + +- Available dates + +- File sizes + +- Data completeness + +- Country coverage + + +## Basic Usage + +```{r} +#| eval: false +library(metatargetr) + +# Get metadata for Germany's 30-day data +metadata <- retrieve_targeting_metadata("DE", "30") + +# View the metadata +print(metadata) +``` + +## Understanding the Output + +The metadata includes: + +- Country code + +- Date stamps + +- Timeframe information + +- Data availability flags + +## Using Metadata for Data Validation + +```{r} +#| eval: false +# Check data availability before retrieval +metadata <- retrieve_targeting_metadata("DE", "30") + +if (nrow(metadata) > 0) { + # Data is available, proceed with retrieval + historical_data <- get_targeting_db("DE", 30, metadata$ds[1]) +} diff --git a/vignettes/retrieving-targeting-data.qmd b/vignettes/retrieving-targeting-data.qmd new file mode 100644 index 0000000..fd508a7 --- /dev/null +++ b/vignettes/retrieving-targeting-data.qmd @@ -0,0 +1,59 @@ +--- +title: "Retrieving Targeting Data" +description: > + Learn how to retrieve and analyze Meta Ad targeting data for different time periods. +vignette: > + %\VignetteIndexEntry{Retrieving Targeting Data} + %\VignetteEngine{quarto::html} + %\VignetteEncoding{UTF-8} +knitr: + opts_chunk: + collapse: true + comment: '#>' +--- + +## Getting Recent Targeting Data + +The `get_targeting()` function allows you to retrieve targeting data for specific time windows: + +```{r} +#| eval: false +library(metatargetr) + +# Last 7 days +last7 <- get_targeting("121264564551002", timeframe = "LAST_7_DAYS") + +# Last 30 days +last30 <- get_targeting("121264564551002", timeframe = "LAST_30_DAYS") + +# Last 90 days +last90 <- get_targeting("121264564551002", timeframe = "LAST_90_DAYS") +``` + +## Understanding the Output + +The function returns a data frame containing: + +- Basic targeting information (gender, age, location) +- Detailed targeting options (interests, behaviors) +- Custom audience information +- Spending and reach metrics + +## Getting Page Information + +Use `get_page_insights()` to retrieve additional page information: + +```{r} +#| eval: false +page_info <- get_page_insights("121264564551002", include_info = "page_info") +``` + +This returns details such as: + +- Page name and verification status + +- Follower counts + +- Page category + +- Creation date