hypothesisr

Interact with the API for hypothes.is, the web annotation service.

Allows users to add, search for, and retrieve annotation data.

Installation

# install.packages("devtools")
devtools::install_github("mdlincoln/hypothesisr")

Usage

Search and retrieve annotations

library(hypothesisr)
ulysses_annotations <- hs_search(text = "ulysses")
dim(ulysses_annotations)
#> [1]  6 28
names(ulysses_annotations)
#>  [1] "updated"                     "group"                      
#>  [3] "target"                      "tags"                       
#>  [5] "text"                        "created"                    
#>  [7] "uri"                         "user"                       
#>  [9] "id"                          "references"                 
#> [11] "links.json"                  "links.html"                 
#> [13] "links.incontext"             "document.link"              
#> [15] "document.title"              "document.favicon"           
#> [17] "document.twitter.url"        "document.twitter.site"      
#> [19] "document.twitter.card"       "document.twitter.title"     
#> [21] "document.facebook.url"       "document.facebook.site_name"
#> [23] "document.facebook.type"      "document.facebook.title"    
#> [25] "permissions.read"            "permissions.admin"          
#> [27] "permissions.update"          "permissions.delete"
ulysses_annotations$text
#> [1] "Pope adds in a footnote: \"Minerva in like manner, during the Battle of Ulysses with the Suitors in Odyss. perches on a beam of the roof to behold it.\"\n\nSource: \n\nPope, Alexander, and Adolphus William Ward. The Poetical Works of Alexander Pope. London: Macmillan, 1907. Print."
#> [2] "Reminds me also of the \"Bloomsday\" tradition of reading (gulp) Joyce's *Ulysses* aloud on the calendar day associated with the fictional events of the novel."                                                                                                                          
#> [3] "I wonder if the paperback of *Ulysses* I spilled a Venti iced coffee on in 2009 will make it into one of these displays some day. Probably not, but a girl can dream, right?"                                                                                                             
#> [4] "Using s sneak attack on Gen, Ulysses S. Grant on the Tennessee river ending in 13,000 people killed and injured on the union, and 10,000 confederates. Knowing that the Union can not take many more loses like this, and something new had to be done. "                                 
#> [5] "And Ulysses may be the ideal text to annotate and collaborate with, as Joyce's work itself  "                                                                                                                                                                                             
#> [6] "What better novel to annotate than Ulysses, a novel full of jokes, references, and puzzles? "

You can specify any of the available annotation data fields with a named list using the custom parameter. For example, to find all the annotations on a domain, query the uri.parts field (but don't include .com, .org, .edu and the like; this currently results in the API returning annotations sharing any of those TLDs.)

ph <- hs_search_all(custom = list(uri.parts = "programminghistorian"))

library(dplyr)
# Display the top 5 most-annotated pages under this domain
slice(count(ph, uri, sort = TRUE), 1:5)

hs_search() will retrieve one page of annotations (up to 200 annotations per page), while hs_search_all() will page through all available annotations until they are all downloaded.

Note: running hs_search_all() with no parameters will download all publicly accessible hypothes.is annotations.

Create, read, update, and delete annotations

To create and delete annotations, you will need to register for an API token at https://hypothes.is/register.

At the moment, hpothesisr cannot create annotations targeted to a particular section of a webpage, such as a highlighted line. These annotations will be visible at the page-level.

user_token <- "xxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
hs_create(token = user_token, uri = "https://github.com/mdlincoln/hypothesisr", user = "acct:mdlincoln@hypothes.is", tags = c("testing", "R"), text = "R made me!")
#> [1] "WFMnSC3FEeaNvLeGkQeJbg"

You may also retrieve the data describing individual annotations by id:

a <- hs_read("WFMnSC3FEeaNvLeGkQeJbg")
a$uri
#> [1] "https://github.com/mdlincoln/hypothesisr"
a$text
#> [1] "R made me!"
a$user
#> [1] "acct:mdlincoln@hypothes.is"

You can update individual fields of annotations by passing your token, the annotation ID, and one or more fields with replacement values.

hs_update(user_token, "WFMnSC3FEeaNvLeGkQeJbg", text = "Now even more annotate-y!")
hs_read("WFMnSC3FEeaNvLeGkQeJbg")$text
#> [1] "Now even more annotate-y!"

You can also delete annotations (at least, those for which you have the permissions to delete):

hs_delete(user_token, "lDf9rC3EEea6ck-G5kLdXA")
#> [1] TRUE

Other utilities

Easily reply to an annotation with hs_reply(), which sends useful defaults to hs_create() in order to construct a new annotation that will show up as a reply to an existing annotation.

open_context(id) will open a hypothes.is annotation in context in the browser.

To-do

1. Target annotations to specific parts of a webpage

Matthew Lincoln