Skip to contents

Query the LinkedIn Ad Library with Automatic Pagination

Source: R/liads.R
li_query.Rd

This function queries the LinkedIn Ad Library API based on specified criteria. It automatically handles pagination to retrieve all available results up to the specified max_pages limit. Supports all official API parameters including keyword search, advertiser filtering, country targeting, and date ranges.

Usage

li_query(
  keyword = NULL,
  advertiser = NULL,
  countries = NULL,
  start_date = NULL,
  end_date = NULL,
  count = 25,
  max_pages = Inf,
  linkedin_api_version = "202409",
  verbose = TRUE,
  clean = FALSE,
  direction = "wide"
)

Arguments

keyword

A string of one or more space-separated keywords to search in ad content. Multiple keywords are treated with logical AND operation. Optional.

advertiser

A string containing the name of the advertiser to filter by. Optional.

countries

A character vector of 2-letter ISO country codes (e.g., c("us", "gb", "de")). Case insensitive. Optional.

start_date

The start date for the ad search range (inclusive). Can be a Date object or "YYYY-MM-DD" string. Optional.

end_date

The end date for the ad search range (exclusive). Can be a Date object or "YYYY-MM-DD" string. Optional.

count

The number of ads to return per page. Maximum is 25 (API limitation). Defaults to 25.

max_pages

The maximum number of pages to retrieve. Set to control API usage. Defaults to Inf (retrieve all available pages).

linkedin_api_version

The LinkedIn API version to use. Defaults to "202409". Should not normally need to be changed.

verbose

Logical. If TRUE, provides detailed progress output during execution. Defaults to TRUE.

clean

Logical. If TRUE, returns a simplified dataset without list-columns. Targeting and impression data are unnested and joined to the main data. Defaults to FALSE.

direction

Character. When clean=TRUE, specifies output format: "wide" (default) keeps separate rows for each targeting/impression combination, "long" creates a longer format with one row per targeting facet or impression country. Only used when clean=TRUE. Defaults to "wide".

Value

A tibble containing the ad data with the following columns:

ad_url

Direct URL to the ad preview page

is_restricted

Boolean indicating if ad violates LinkedIn policies

restriction_details

Details about policy violations (if any)

advertiser_name

Name of the advertising organization

advertiser_url

LinkedIn page URL of the advertiser

ad_payer

Entity that paid for the advertisement

ad_type

Format/type of the advertisement (e.g., "SPOTLIGHT_V2")

first_impression_at

First time the ad was shown (POSIXct)

latest_impression_at

Most recent time the ad was shown (POSIXct)

total_impressions_from

Lower bound of total impressions

total_impressions_to

Upper bound of total impressions

impressions_by_country

List-column with country-wise impression data

ad_targeting

List-column with detailed targeting criteria

Authentication

Requires prior authentication using li_auth_configure and li_auth. The function automatically uses cached OAuth tokens.

Rate Limits

The LinkedIn API limits responses to 25 ads per request. Use the max_pages parameter to control the total number of API calls. Large queries may take time to complete.

API Reference

Based on the LinkedIn Ad Library API: https://www.linkedin.com/ad-library/api/ads

Examples

if (FALSE) { # \dontrun{
# First, authenticate:
# li_auth()
# readRenviron(".Renviron") # Run this after authenticating

# Example 1: Search for ads by keyword and country

# Example 2: Search for ads by a specific advertiser, limiting to 2 pages
} # }