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.
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:
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.
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.
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.
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:
If you are only interested in counting annotations, however, there is another API method you can use:
Using the API to add and modify annotations
To create, modify and delete annotations, use the following API methods:
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.