Python scripts for interacting with the API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Python scripts for interacting with the API.

This script (still in progress) calls the API, searches for public annotations from a specific user with a specific hashtag, and writes the results to a markdown file that is Jekyll-friendly.

Simply open the script, change the variables at the top of the file to suit your needs, and run it. There are comments in the script to help you. Then place the '' file it creates into your Jekyll/GitHub blog. (I'd change the name.) Finally, add a link to the page.

You can see this script in action on my website:

The downside to this script, which results from the way GitHub Pages works, is that you have to run it manually each time you want to fetch new annotations. To enhance that process, you could add the appropriate path to the output file name in this script, and write a shell script that runs this script and then commits/pushes to GitHub, and then schedule that script to run at regular intervals from your computer/server. I'm going to look into adding that functionality to this script, but it's not ready yet.


The beginnings of a Python module that will allow programmers a simpler interface for the API. See test (at end of script) for sample code.

Following is a list of classes and functions in this module that Python programmers can use to incorporate functionality in their scripts.


An object class for a single annotation. Call Annotation(json_data_for_single_annotation) to create a new object. This object has the following attributes:

  • title (the title of the annotated article)
  • uri (the uri of the annotated article)
  • highlight (the article text highlighted in the annotation)
  • comment (the annotation comment left by the annotator)
  • user (the user ID of the annotator)
  • created (the date and time the annotation was created)
  • updated (the date and time the annotation was updated)
  • id (the unique ID of the annotation; this ID is included in the URL for the annotation)
  • hypothesisurl (the URL for the annotation)


A function that retrieves the JSON data for a single annotation, given the annotation's API URL. Call retrieve(api_url_for_a_single_annotation) to retrieve the JSON data, for passing into the Annotation() class.


A function that retrieves the JSON data for a list of annotations, given a well-formed search URL for the API. Call retrievelist(search_url_for_the_hypthes.is_api) to retrieve the JSON data for all annotations in the search results. Each annotation's JSON data is an item in a list. Use a for loop to pass each item returned into the Annotation() class.


A function that converts a share URL (easy to find in the user interface) into an API-friendly URL (difficult to find), for passing to retrieve(). Call apiurl(share_url_for_an_individual_annotation) to return the API-friendly URL.


A function that takes a user name and/or a tag (or list of tags) and generates a well-formed search URL for the API. The format is:

searchurl(user = '', tag = '', tags = [])

The searchurl() function requires at least one search term. It can be either a user name, a single tag, or a list of tags (as a well-formed Python list). Use either a single tag or a list of tags, not both. If you happen to send it both, it will take the list of tags and ignore the single tag.

Example searches:

# all annotations from a single user
searchurl(user = '')
# or

# all annotations tagged IndieEdTech
searchurl(tag = 'IndieEdTech')

# all annotations from a single user tagged IndieEdTech
searchurl(user = '', tag = 'IndieEdTech')
# or
searchurl('', 'IndieEdTech')

# all annotations tagged IndieEdTech AND EdTech (for an OR search, simply perform two searches and combine the results)
searchurl(tags = ['IndieEdTech', 'EdTech'])

Example code

# search for all annotations with the tag IndieEdTech and return them in json format.
s = searchurl(tag = 'IndieEdTech')
l = retrievelist(s)

# print the title of each article annotated.
for entry in l:
    e = Annotation(entry)
# Using the annotation share URL, retrieve and parse the JSON data for that annotation, then print it.
t = Annotation(retrieve(apiurl('')))