A Note About JOSM

Over the past couple of months I have been slowly working to add support for OSM notes into JOSM. Back in July 2013, Ian Dees and I initially did a rewrite of the OpenStreetBugs plugin to support notes. We actually both started out in a friendly competition to see who could get a working version out first as we traded words on IRC. But soon Ian gave me access to his GitHub repository where we continued to work on the plugin for a while.

This plugin basically worked but I decided that since notes are now a core feature of OSM, they should also be more integrated into JOSM. In particular I wanted the workflow of notes to follow the standard JOSM download-work-upload sequence. The plugin was designed to be always online and issued a new query against the notes API every time you panned or zoomed the map. It had an "offline" mode which would stop this behavior and allow you to work without constant network traffic. However in this mode, changes to notes and newly created notes were not shown on the map which was a bit confusing. And unfortunately it was not a simple fix because the plugin just wasn't designed that way. In offline mode, it held actions in queue which were then executed when you went back online. So there was no note object in queue to draw on the map until after the upload happened and another download was initiated from the API. Also, the most useful way of using it was to zoom out, let it download notes and then go into offline mode to work. This was not at all intuitive.

After receiving a favorable response from the josm-dev mailing list, I began submitting patches in September 2014. Throughout the rest of 2014 I slowly built up behind-the-scenes functionality to download, parse and display notes in JOSM. As of the December release, the notes functionality is actually usable. It is not turned on by default yet because there is still some polishing that needs to be done, especially in the user interface department. But I would love to get some more people testing it. The secret handshake to enable notes in JOSM is as follows:

0. Download some data. Anything, anywhere. This just initializes a setting that you will change
1. Open JOSM preferences
2. Go to the advanced preferences
3. Search for "notes"
4. Change the preference osm.notes.enableDownload to "true"
5. Restart JOSM

In graphical format: 

When you open the download dialog after restarting JOSM, you will notice a new "Notes" checkbox alongside the "OpenStreetMap Data" and "Raw GPS data":

After your first download of notes, you will also need to open the note panel or you won't be able to manipulate notes. Click the note icon in the left hand panel. If you still have the notes plugin installed, there will be two identical buttons. Either figure out which one is which or uninstall the plugin. Here is a view of things:

The area download limit for the notes API is far greater than the limit on downloading OSM data. You can download 1 square degree at a time if you are only downloading notes. The limit for OSM data is 0.25 square degrees (although realistically you usually run into the 50,000 object limit before you run into the square degree limit). The above screenshot was downloaded in one request. It is about half the state of Kansas.

Protip: By default, JOSM will only download 1,000 notes per download request. The OSM API has a hard limit of 10,000 per request. What JOSM asks for is controlled by the osm.notes.downloadLimit setting in the advanced preferences. The other setting worth mentioning is osm.notes.daysClosed. This determines whether or not closed notes are downloaded. If set to -1, it will download all notes ever created within the requested bounding box. If it is set to 0 it will only download currently open notes. If it is set to a positive number, it will download notes which have been closed for that many days. By default, osm.org shows notes that have been closed within the last week. To copy this behavior, this setting should be set to 7. I believe the default right now is 1 day.

There is some discussion around these options as well as some of the other polishing that is still needed in the JOSM bug tracker. And of course that is also where any new issues can be reported.

In particular, one of the open tickets which I have already submitted a patch for, but hasn't been accepted yet is the ability to download notes via the note search API. I use this periodically to download all the notes created by Craigslist users (they all start with the word "bounds" so that's the query I send to the note search API) and close all the useless ones.

One last screenshot. One of the features of the notes code is that it can read note dump files. It is actually a byproduct of being able to save and load the note layer. Anyway, here is a screenshot of the latest note dump from http://planet.osm.org/notes/ loaded into JOSM. All 309,000 of them.

Happy noting!

P.S. Dear iD: Your move!