Viewing and exporting Hypothesis annotations

We’re delighted to see Roderic Page and Kris Shaffer putting the Hypothesis API to work. For us, the API isn’t just a great way to integrate Hypothesis with other systems. It’s also a way to try out ideas that inform the development of Hypothesis.

Today I’ll share two of those ideas. One is a faceted viewer that displays sets of annotations by user, group, and tag. The other exports annotations to several formats. If you’re a Hypothesis user, you may find these helpful until proper implementations are built into the product (faceted viewer: soon, export: later). And your feedback will help us design and build those features. If you’re a developer, you can use these as examples to learn to form API queries, authenticate for access to private and group annotations, parse JSON responses, and navigate threaded conversations.

These tools aren’t official Hypothesis offerings. They’re hosted on my own server. But they’re all done as single-page JavaScript apps which means there’s no web server required, you can even copy them to your own computer and use them locally.

Viewing annotation activity

Here’s a view of activity for Hypothesis user judell:

Results are organized like so:

1. Annotations are grouped into threads.
2. Threads are grouped by URL.
3. URLs appear in reverse order by recency of annotation.

The URL for that view is:

http://jonudell.net/h/facet.html?search=judell&token=

By default only public annotations are shown. But if I capture my API token I can pop that into the form, or tack it on to the URL like so:

http://jonudell.net/h/facet.html?facet=user&search=judell&token=6879-76…ac0

Now the page will show all my annotations, including those that are private (“Only Me”) and in groups I’ve joined. Just capture and swap in your own token to do this for yourself.

Variants of the page enable the same thing for tags, groups, or any facet.

Here’s a link for the tag hypothesis: http://jonudell.net/h/facet.html?facet=tag&tag=hypothesis.

Here’s a link for a group I just made, called Anyone Can Join:

http://jonudell.net/h/facet.html?facet=group&=8gk9i7VV

If you join that group, then add your token to the form, you’ll get a view of group activity:

And here’s a link to search all facets for candelalearning:

http://jonudell.net/h/facet.html?facet=any&search=candelalearning

The underlying API query in this case, https://hypothes.is/api/search?any=candelalearning, searches for the term candelalearning everywhere: in URLs, in tags, in annotation quotes and bodies. It can be a useful way to find all annotations for a domain, as happens in this case. But that’s only true when the term you’re searching for is uniquely associated with a domain (e.g. courses.candelalearning.com) and when the term does not include punctuation. A search for courses.candelalearning.com treats courses, candelalearning, and com as separate terms, and finds all kinds of stuff. So this isn’t a substitute for the forthcoming site: facet that will enable precise search for annotations within a domain.

Exporting annotations

A related single-page app, http://jonudell.net/h/export.html, enables you search along the same facets — user, group, and tag — and then export the results to HTML, CSV, text, and Markdown.

Here I’ve used it to search Jeremy Dean’s annotations for the tag nextprez:

I’ve omitted the token because that’s Jeremy’s secret, so only public annotations are shown here, but Jeremy could plug in his token to see all his stuff.

The HTML version of the export page is shown in the browser and also downloaded to hypothesis.html. Either way, it renders images and Markdown so you get a self-contained annotation set with full fidelity.

The CSV, text, and Markdown versions just report the number of annotations found. The exports land in your downloads folder as hypothesis.csv, hypothesis.txt, and hypothesis.md.

Update

: The export feature is now merged with the activity viewer.

Other experiments

I’m working on some more experiments as well, including:

1. Slack notification of group activity
2. An LTI app that wraps annotation around Canvas files
3. Controlled tagging for groups
4. A button to copy individual annotations to the clipboard

If you’d like to participate in one of these experiments, annotate this post to let us know and we’ll be in touch.