Hypothes.is Collector

Tools by John Stewart

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/https://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.

HypCollector

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.

https://docs.google.com/spreadsheets/d/133icqjeRM7ZGp2AiziV0XbCb6RkA4QoqIThp8xV5TlU/copy

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

14 comments

  3. jhh1899

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

    Reply
    1. John Stewart

      It seems to be. What wasn’t working for you?

      Reply
  5. Shawn

    Hi – it’s working great for me. Whereabouts would I start noodling at the code to get more than 200 annotations? My gang are going, well, gangbusters with annotations… Thank you for building this!

    Reply
    1. John Stewart

      You should be able to access the Google Script from the Sheet, through the Script Editor in the Tools Menu. There, the code pertaining to limits is on lines 16-20. If I remember correctly, the Hypothes.is API limits you to 200 annotations, which is why I “set” it there. I think you might be able to loop lines 14-140 to pull and parse paginated sets of annotations. Alternatively, you could recode those lines with rational planning as opposed to my ad hoc experimentation and probably get a nice encapsulated function that would handle as many calls as you want.

      Reply
  6. Rishi

    Hi John, I had a question about the safety concerns of the collector’s script. Can you assure that no private documents that the script is running on will be accessed. I have this question because chrome has stated that its not a verified third party and I have been seeing some unusual viewing of private documents pop up. Thank you.

    Reply
    1. John Stewart

      Hi Rishi. I think the script can be run on either a public or private Google Sheet. The script doesn’t provide access to any of your sheets, public or private, so I don’t see how anyone could use it to access your sheets.

      Reply
      1. Rishi

        Understood John; thank you for clearing that up. Was just confused about dynamic changes that may happen through the script but looks like the activity was just standard google sessions time outs. Thank you for your prompt reply!

        Reply
      2. Rishi

        Thank you for clearing that up John, really appreciate it.

        Reply
  7. Insight. – Adam Croom

    […] it into every WordPress instance as a plugin and John Stewart has done great work with building the Hypothes.is Collector, a Google Spreadsheet that interacts with the Hypothes.is API. Jeremy and I connected first on […]

    Reply
    1. John Stewart

      Yeah, it’s a cloud based app. They have a really nice app for the Chrome browser, but it works on most modern web browsers.

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

css.php