In leeper/lumendb: Lumen Database API Client

Lumen Database API Client

lumendb is a simple client package for the Lumen Database (formerly Chilling Effects) API. It can retrieve, as well as deposit, copyright takedown notices from the Lumen database. It may be useful for tracking who is sending copyright-related cease and desist orders and what material is being used in apparent violation of copyright.

All Lumen Database data is released under to Public Domain (CC0), though the API has additional terms of use.

Use of the package does not require an API token, though Lumen rate limits non-authenticated requests. To request a token, contact Lumen directly at: team (at) lumendatabase.org. The token should then be stored as an environment variable:

Sys.setenv(LUMEN_TOKEN = "t1o2k3e4n5v6a7l8u9e")

Or this can be passed atomically to every API call. Setting the environment variable is simpler and more secure because it will not be recorded in R history logs.

Code Examples

The key functionality of the package is to retrieve notices by their identification numbers and to search for notices. To retrieve a single notice, just query it:

library("lumendb")
x <- ldnotice(1)
summary(x)

The summary() method will print some essential details for each notice, as seen above.

The other major function is to search for notices by keyword. The search functionality is pretty complicated, so I have not written R-specific documentation for it. The search API is based on elastic search and Lumen's documentation is available on GitHub for those who are interested. As a simple example, one can perform a full-text search for notices related to YouTube:

x <- ldsearch(list(term = "youtube"))
print(x)

Another example would be to retrieve 100 requests from a major takedown requester, The Publishers Association, which represents a large number of publishing companies:

# query 50 notices
x <- ldsearch(list(sender_name = "The Publishers Association"), per_page = 50)

# view first two notices
summary(x[[1]])
summary(x[[2]])

The ldsearch() function is, like the API it wraps, paginated and pagination details are printed by to the console by default and are available in meta attribute in the search result list.

Note: the notice submission API is not yet implemented in this package.

Installation

This package is not yet on CRAN. To install the latest development version from GitHub, run the following:

if (!require("ghit")) {
    install.packages("ghit")
}
ghit::install_github("leeper/lumendb")

leeper/lumendb documentation built on May 21, 2019, 12:37 a.m.