Access Substack Data via API

An interface to access data from Substack publications via API. Users can fetch the latest, top, search for specific posts, or retrieve a single post by its slug. This functionality is useful for developers and researchers looking to analyze Substack content or integrate it into their applications. For more information, visit the API documentation at < https://substackapi.dev/introduction>.

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:

   devtools::install_deps(dependencies = TRUE)
   

4. Run tests:

   devtools::test()
   

5. Submit a pull request.

License

MIT © Posocap.com
See LICENSE for details.