Annotating your data

The Annotations plugin, added in version 1.10 of Piwik, allows you to create notes and attach them to dates in the past. The notes are just text and can contain anything you’d like them to.

Being able to take notes and stick them to your data might not seem like that powerful a feature, but its simplicity makes it an invaluable tool in helping you understand your data.

Why would I want to create annotations?

Everytime you make a change to your website, whether it’s as simple as a new blog post or as complicated as an entire redesign, you can make a note of it in Piwik. When you look back and see that certain dates have more visits than others, you can look at the annotations you made to figure out why. Then, you can act on this new information.

For the most part, the possible annotations you can make are only limited by your imagination, but here are some ideas to get you started:

• Changes to website content and design (new blog posts, new site design, etc.).
• E-mail newsletters and e-mail marketing campaigns.
• Offline advertising launches (print, radio, television, etc.).
• Important business milestones, such as product launches.
• Key calendar events, such as public holidays.

If anything occurs that is important to your website or your business, be sure to make a note of it in Piwik, so you’ll know if it has an affect on your visits.

Creating and editing annotations

You can view & edit annotations on any graph that shows statistics over time. This includes the visitors overview (Visitors > Overview), any goals page, the referrers overview (Referrers > Overview) and any row evolution popup.

To view annotations on one of these graphs, select a period that includes the date(s) you want to annotate, and either click below the date on the evolution graph, or click on the ‘Annotations’ link in the lower right corner.

Clicking on a date shows the annotations for that specific period (ie, the day Nov. 15, 2012 or the week starting on Nov. 18, 2012). Clicking on the ‘Annotations’ link will show every annotation within the date range displayed by the evolution graph.

To create a new annotation, first open the annotation viewer as described above. Then, while logged in, click on the ‘Create a new annotation…’ link:

Finally, enter a note (and optionally, change the date of the annotation), then click save. The new annotation will be saved.

To modify an existing annotation, first open the annotation viewer as described above. Then, while logged in, click on the ‘Edit…’ link next to the annotation you want to edit. If the link is not present, then you don’t have permission to edit the annotation.

Note: If you have admin access for a site, you can edit/delete any annotation. If you don’t, you can only edit/delete the annotations you created.

After you click the ‘Edit…’ link, you will be able to change the date and text.

If you want to delete the annotation, you can click the ‘Delete’ link.

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 Piwik data every time a change is made or a new blogpost is written.
• An app that monitors your github account and annotates your Piwik data after every commit or new release.
• An app that annotates your Piwik data every time you send out an e-mail to your subscriber list.

The Annotations API is a part of Piwik’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 Piwik’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.