Hypothes.is Collector

One of my favorite online tools is Hypothes.is. It allows you to annotate web pages as you would a book. When you’re using Hypothes.is you can highlight text on a webpage or add notes.

The tool can be used to take private notes, but it becomes all the more powerful when you use it for collaborative reading. By making your notes public or sharing them with a chosen group, you can share your take on a reading as you’re reading it. My colleague Lauren Horn Griffin recently wrote on the uses cases for this web annotation within a university setting. She identified five possibilities

  • Reading Accountability & Promoting Active Reading
  • Collaborative Reading & Modeling
  • Public-but-Independent Research
  • Instructor Feedback/Self-Assessment
  • Citations

You can launch the tool by appending “https://via.hypothes.is/” before a URL. To annotate this post you would visit https://via.hypothes.is/http://www.johnastewart.org/tools/hypothes-is-collector/. You can also download an extension for Chrome to be able to launch Hypothesis quickly on any website. Site builders can also install Hypothes.is directly into WordPress, Drupal, or Jekyll sites, or pretty much anything else that allows javascript.

Here is how a recent LA Review of Books article on Digital Humanities looks when viewing the public annotations:

A screenshot of an article in LA Review of Books on Digital Humanities with the Hypothesis tool active

Hypothes.is Collector

In order to make it easier to track activity in Hypothes.is, I created a program called Hypothes.is Collector. The idea is that you can type in user name, a URL, a tag, or a group ID and click the button to see all of the related annotations. The program will create a new sheet with an archive of up to 200 annotations based on the search terms.  It will then create a third sheet that will count how many of these annotations were made on each URL in the set by each user.


As with Hypothes.is itself, I see several use cases for this. The original idea for the program was to allow a course instructor to quickly see the activity of their students. If an instructor asks her students to annotate three different articles, she could use this app to assess whether or not each student made their annotations. The easiest way to do this would be to set up a group in Hypothes.is for the class.  The instructor could then enter the group ID and her user authorization token (a unique password that allows you to pull your private and group annotations) into the system. When she clicked the button, she would see an archive of the annotations and a count of activity for the students across the three readings.

Other use cases as I currently see them include:

  • Studying how various tags are being used within Hypothes.is
  • Tracking recent public activity for Hypothes.is
  • Breaking down activity on a particular reading by user
  • Tracking one of Remi Holden’s  annotation flash mobs

I built the Collector as an attempt to make it easy for people to access annotations in a format that could then be analyzed. I think the counter that gets built on the third sheet is handy, but it’s not going to be useful for everyone. As I continue to refine this project, I am going to add some different visualizations of the annotation archive and I will extend the number of annotations that can be pulled at a single time. I welcome feedback and feature requests and encourage everyone to modify the project to best suit their needs.

Please try out the new Hypothes.is Collector. You can follow this link to get a copy of the spreadsheet and collect annotations. You can also view or modify the code by choosing “Script Editor” from the Tools Menu.


A few notes on the Code:

The code for the program (shared below) is written in Google Scripts. This is a modified javascript that features a library of functions to facilitate interaction within and between the Google Docs Apps. While writing this particular code, I learned a few tricks for collecting and passing the parameters for the API search and how to pass the authorization token. You can run Google’s version of a GET request, UrlFetchApp.fetch, woith or without an authorization token and other advanced options. To run it with the advanced options (to pass headers like authorization), I formatted the ‘headers’ as a js object, passed them into a second object called ‘options’, and then passed ‘options’ a parameter into UrlFetchApp.fetch.

This probably isn’t interesting to most people, but it took me a long time to figure out and opens the doors to all sorts of other APIs that require authorization. Google Script is a little particular and APIs vary, but I learned a lot about APIs while figuring out the authorization, search parameters, and how to parse the returned json. After writing an initial version of the code, I found better solutions to many of my questions in some of Jon Udell’s Hypothes.is API code – so thank you Jon and be sure to check out his site: jonudell.net.

The bit of code at the end that sets up the third spreadsheet for counting annotations by user and URL is also pretty nifty. I had to figure out how to use arrays to populate Sheets ranges and then played with the archaic R1C1 notation to create dynamic formulas for the sheet. Feel free to hack at or extend the code for your own use. Chunks of the code may also be useful for working on other API projects. As with most of my work, feel free to take whatever is useful.

End of code


My Week in Review


My Week in Review May 16 – 20


  1. jhh1899

    Does your Collector still work? I couldn’t get it do so.

Leave a Reply

Powered by WordPress & Theme by Anders Norén