sentiR

R client for the SentiOne Listen API v2.

A tidyverse-compatible package for social listening and sentiment analysis.

Installation

# install.packages("devtools")
devtools::install_github("publico-data/sentiR", build_vignettes = TRUE)

Authentication

Get your API key from your SentiOne account settings.

library(sentiR)

# Option 1: Set directly
so_auth("your-api-key")

# Option 2: Use environment variable (recommended)
# Add to .Renviron: SENTIONE_API_KEY=your-api-key
so_auth()

Quick Start

library(sentiR)
library(dplyr)

# List your projects
projects <- so_projects()

# Get mentions from last 7 days
mentions <- so_mentions(
  project_id = 12345,
  from = Sys.Date() - 7,
  to = Sys.Date()
)

# With filters
mentions <- so_mentions(
  project_id = 12345,
  from = Sys.Date() - 7,
  to = Sys.Date(),
  .filter = so_filter(
    sentiment = c("Positive", "Negative"),
    sources = c("X", "Facebook"),
    language = "pt"
  )
)

# Analyze results
mentions |>
  count(sentiment)

Main Functions

Function	Description
so_auth()	Set API key
so_projects()	List all projects
so_project(id)	Get single project
so_mentions()	Search recent mentions (7 days)
so_mentions_historical()	Full archive search (Enterprise)
so_mentions_stream()	Bulk export (Enterprise)
so_filter()	Create reusable filters

Filtering

# Create reusable filter
my_filter <- so_filter(

sentiment = c("Positive", "Negative"),
  sources = c("X", "Facebook", "Instagram"),
  language = c("pt", "en"),
  query = "brand OR product"
)

mentions <- so_mentions(
  project_id = 12345,
  from = Sys.Date() - 7,
  to = Sys.Date(),
  .filter = my_filter
)

Features

• Automatic pagination
• Rate limiting (via httr2)
• Progress bars
• Tidyverse-compatible (returns tibbles)
• Informative error messages

Documentation

# Full tutorial (requires build_vignettes = TRUE during installation)
vignette("getting-started", package = "sentiR")

# Or view online: https://github.com/publico-data/sentiR/blob/main/vignettes/getting-started.Rmd

# Function help
?so_mentions
?so_filter

License

MIT