The Annotations API

In addition to letting you create notes through the UI, the Annotations plugin also provides a web API that allows you to view, add and modify annotations. If you’re a programmer, you can use this API to make some interesting apps.

Apps that haven’t been made yet:

The following is a list of ideas for apps that use the Annotations API. These apps have not been created yet, but we’d love it if they did exist, and we’re sure others would too.

  • A WordPress plugin that automatically annotates your Matomo (Piwik) data every time a change is made or a new blogpost is written.
  • An app that monitors your github account and annotates your Matomo data after every commit or new release.
  • An app that annotates your Matomo data every time you send out an e-mail to your subscriber list.

The Annotations API is a part of Matomo’s API. You can read more about how the API works here. If you already know how to use the API and want to know how to use it to manipulate annotations, then keep reading.

Using the API to view annotations

There are two API methods you can use to query existing annotations:

  • Annotations.get — Gets a single annotation.Parameters:
    • idSite: The ID of the website the annotation belongs to.
    • idNote: The ID of the annotation.
  • Annotations.getAll — Gets several annotations.Parameters:
    • idSite: The IDs of the websites whose annotations will be searched. If more than one ID is supplied, this value should be comma separated.
    • date: The date the annotations are attached to. Or a date range if period is set to ‘range’.
    • period: The period to use. By default, a ‘day’ period is used. If you provide another value (ie, ‘week’, ‘month’, ‘year’, ‘range’), annotations within the entire period are returned.
    • lastN: (optional) If provided, the last N periods are included in the search.

If you are only interested in counting annotations, however, there is another API method you can use:

  • Annotations.getAnnotationCountForDates — Gets the count of annotations and starred annotations within a set of periods.Parameters:
    • idSite: The IDs of the websites to count annotations for.
    • date: The date the annotations are attached to. Or a date range if period is set to ‘range’.
    • period: The period to use. By default, a ‘day’ period is used. If you provide another value (ie, ‘week’, ‘month’, ‘year’, ‘range’), annotations within the entire period are returned.
    • lastN: (optional) If provided, the last N periods are included in the search.

Using the API to add and modify annotations

To create, modify and delete annotations, use the following API methods:

  • Annotations.add — Adds a new annotation for a website and date.Parameters:
    • idSite: The ID of the website the annotation is being added to.
    • date: The date the annotation should be attached to.
    • note: The text of the annotation.
    • starred: (optional) Either 1 or 0. If 1, this annotation starts out as starred. If 0 or not supplied, it does not.
  • Annotations.save — Modifies an existing annotation.Parameters:
    • idSite: The ID of the website the annotation belongs to.
    • idNote: The ID of the annotation.
    • date: (optional) If supplied, the existing annotation’s date is changed to the supplied date.
    • note: (optional) If supplied, the existing annotation’s text is changed to the supplied text.
    • starred: (optional) Either 1 or 0. If supplied, the annotation is either starred or un-starred based on the value of this parameter. If 1 it will be starred, if 0 it will be unstarred.
  • Annotations.delete — Deletes an existing annotation.Parameters:
    • idSite: The ID of the website the annotation belongs to.
    • idNote: The ID of the annotation.

Using Matomo’s Bulk Request feature to speed up your apps

If the app you are going to create will be creating or modifying a lot of annotations, you might want to consider sending bulk API requests. Sending one HTTP request at a time to create dozens of annotations (or more) will be much slower than issuing a bulk request. To learn more, read this.

Previous FAQ: Create and edit annotations