Customise Consent Preferences

We use cookies to help you navigate efficiently and perform certain functions. You will find detailed information about all cookies under each consent category below.

The cookies that are categorised as "Necessary" are stored on your browser as they are essential for enabling the basic functionalities of the site. ... 

Always Active

Necessary cookies are required to enable the basic features of this site, such as providing secure log-in or adjusting your consent preferences. These cookies do not store any personally identifiable data.

No cookies to display.

Functional cookies help perform certain functionalities like sharing the content of the website on social media platforms, collecting feedback, and other third-party features.

No cookies to display.

Analytical cookies are used to understand how visitors interact with the website. These cookies help provide information on metrics such as the number of visitors, bounce rate, traffic source, etc.

No cookies to display.

Performance cookies are used to understand and analyse the key performance indexes of the website which helps in delivering a better user experience for the visitors.

No cookies to display.

Advertisement cookies are used to provide visitors with customised advertisements based on the pages you visited previously and to analyse the effectiveness of the ad campaigns.

No cookies to display.

Viewing and exporting Hypothesis annotations

By judell | 24 June, 2016

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.

Share this article