README.md

In substackR: Access Substack Data via API

substackR

A lightweight R client for the Substack API. All functions return data frames, handle errors with informative messages, and work out of the box once you’ve set your API key.

Installation

From CRAN:

install.packages("substackR")

Development version from GitHub:

# install.packages("pak")   # if needed
pak::pak("posocap/substackR")

Authentication

Provide your API key once per session with:

library(substackR)
set_substack_key("your-substack-api-key")

If you haven’t set the key, any API call will prompt you to call set_substack_key() first.

Main Functions

get_substack_latest()

Fetches the latest posts.

latest_posts <- get_substack_latest(
  publication_url = "posocap.substack.com",
  limit           = 10,
  offset          = 0
)

Returns a data frame with columns:

• slug
• url
• title
• description
• excerpt
• body_html
• reading_time_minutes
• audio_url
• date
• likes
• paywall
• cover_image
• cover_image_color_palette
• author
• author_image

get_substack_top()

Fetches the top (most liked) posts.

top_posts <- get_substack_top("posocap.substack.com", limit = 5)

get_substack_search()

Searches posts by keyword.

search_results <- get_substack_search(
  publication_url = "posocap.substack.com",
  query           = "data science",
  limit           = 20
)

get_substack_post()

Retrieves a single post by slug.

single_post <- get_substack_post(
  publication_url = "posocap.substack.com",
  slug            = "your-post-slug"
)

Error Handling

• Missing API key → error asking you to run set_substack_key().
• HTTP errors (4xx, 5xx, rate limits) → cli::cli_abort() with status code and message.
• JSON parsing issues → warning + empty data frame.

Contributing

1. Fork the repo
2. Create a branch (e.g. feature/xyz)
3. Install dependencies: r devtools::install_deps(dependencies = TRUE)
4. Run tests: r devtools::test()
5. Submit a pull request.

License

MIT © Posocap.com See LICENSE for details.

substackR documentation built on June 17, 2025, 9:12 a.m.