From OpenStreetMap Wiki
< JOSM‎ | Plugins
Jump to navigation Jump to search


This article or section may contain out-of-date information: This plug is now part of the core project.
If you know about the current state of affairs, please help keep everyone informed by updating this information. (Discussion)

Using the WMS plugin with Yahoo! Aerial Imagery (with a downloader installed)
Using the WMS plugin to trace woodland areas over Landsat imagery (bottom left), and comparing road layouts with 1950s NPE maps (top right)
screenshot needs updating since the new WMS plugin does continuous tile downloading

The WMS Plugin provided functions which are now part of JOSM core. The plugin allowed you to fetch images from any WMS source, and display them as a background image (a layer) within JOSM. It also supported Yahoo! Aerial Imagery and Rectifier like Metacarta and Geothing to display rectified/warped images.

Now that imagery is a core feature, you can open WMS sources from the 'imagery' menu. There is no longer any need to install these features as a plugin. See also the help page in the JOSM Wiki.

Starting with JOSM version 3715, WMS functionality is part of JOSM itself.

Tutorial video on basic WMS setup

Using the WMS functionality

  • Load / Download openstreetmap data and go to your favourite area
  • Show the 'Layers' panel if it isn't showing already (Click the toggle button: JOSM-Icon-layerlist.svg)
  • Click the menu option "WMS → Landsat" (or whatever named WMS server you want to use) This should cause it to create a new imagery layer.
  • Wait a few moments for it to begin fetching image tiles.

As you pan around it will download more tiles. It also seems to remove tiles which are out of viewing area, to free up memory.

To remove the imagery and stop all WMS downloading, select the layer and click the trash can button. You can also temporarily toggle visibility of the layer (keeps imagery in memory). Right click on the layer (in the layers panel) to access further WMS layer options.

When your WMS layer is selected, the data layer is shown as deselected (dark grey). Simply select your data layer again (often called 'unnamed') to restore normal colours. It is also possible to display the WMS layer "above" the data layer, which will hide the data layer completely. Use the up/down arrows to fix the ordering.

You can adjust the positioning of the imagery by clicking JOSM-Icon-adjustxywms.png button on the left. In this mode you can drag and drop the WMS layer. Press the button again to lock it in place. This can be useful if the imagery appears to be offset from reality, but note that your GPS unit isn't perfect. A bad GPS signal can cause an entire trace to have an offset from reality, so you may find it useful to check also by downloading other GPS traces recorded for the area.

You may need to adjust your map colours ('Edit' menu -> 'Preferences') to be darker or lighter, to contrast with the images you are using.

Basic troubleshooting

Things to try in case of problem.

no image appears, even after waiting a bit

  • adjust zoom level so that the scale in the top left says ~150m, delete the layer (trash can icon), add it again from the menu.
  • The plugin may not find the DLL files. Check you have placed all of the webkit-image zip file contents them somewhere on the system path.

images at bad resolution from Yahoo

  • adjust zoom level as decribed above. Note that in most regions Yahoo imagery has a lesser resolution than Google Maps.

Exception occurred red tiles

  • This can mean the WMS server is temporarily not available. Landsat and OpenAerialMap seem to be prone to periods of non-availability. Delete the WMS layer and try again 10 minutes later.

error : bad parameters red tiles

  • Check that configuration -> projection is set to EPSG:4326 or Mercator.

gray tiles

  • if you have non-ACSII symbols in the path to your plugin folder in Windows (e.g. cyrillic letters in your name in C:\Documents and Settings\your name\Application Data\JOSM\plugins), a possible solution is to change your name to an equivalent short filename. To find this open a command window and do
dir /x "C:\Documents and Settings"

In its output the column to the left of your name should contain short version of your name, let it be for example 9335~1. Add a line to the batch file starting JOSM:

rem   Contents of start_JOSM.cmd
set APPDATA=C:\Documents and Settings\9335~1\Application Data
start javaw -jar josm.jar

"Plugin requires JOSM update: wmsplugin" at JOSM startup

  • Update JOSM: see JOSM to last tested version.
  • If the message still appears, the problem is on your side - you have a newer version plugin version than your josm can hande. Go to the plugin preferences page and update there. This should install the last version which is usable in your josm (when necessary does a downgrade of the plugin).

For other troubleshooting you can ask a bunch of JOSM users via various Contact channels. Bugs are tracked on josm trac 'Plugin WMS' component


To reuse the tiles over JOSM sessions without having the reload them from the server, right click on the WMS layer and set a bookmark. During the next session, select the new WMS created by the bookmark in the WMS memu. Additionally, you may want to modify the following values in the preferences :

  • cache.wmsplugin.expire -1 : this is a time in second until the tiles are invalidated. -1 means "never flush".
  • cache.wmsplugin.maxsize 999999999 : maximal size of the cache (probably in MB)

Even though you have to download an area "manually", you can work offline using this technique.

Using a "Rectified Image"

Do not use copyrighted material, unless you have the right/permission to do so (see the Licensing section below)!

Before you start with your own images, it might be a good idea to start with Landsat data so you'll learn how to work with these downloaded images.

To work with your own images in JOSM:

  • upload your aerial image / scanned old map to either
  • rectify it on their site so it "fits with reality"
  • XXX - wait for the image to be processed?
  • remember the metacarta id (look at the URL in your browser)
  • in JOSM, load some openstreetmap data of the expected image area (to be in the right "clipping range")
  • click on WMS -> Rectified Image and enter the id in the upcoming dialog

If the "clipping range" was wrong, you might see just nothing. In this case zoom out and retry the download.

Adding a WMS Server

Do not use copyrighted material, unless you have the right/permission to do so (see the Licensing section below)!

To add a new WMS Server, use the Menu: 'Edit' menu -> 'Preferences' and click on the WMS tab. Now you can add / remove WMS server URL's.

A WMS server typically can provide different projections, subsets of data, etc., so you may need to experiment with the URL settings to get the best results.

Adding presets for objects and source=yahoo_wms

It can be useful to let other users know what your data is based on by adding source=yahoo_wms. This can be quickly done by creating a JOSM tagging preset for roads, woodland, etc and source=yahoo_wms.

Once this is set up, it is simple to apply custom combinations of tags to a node, way or area in JOSM:

  • Download the Yahoo-road.png Yahoo road icon.
  • Open your favourite text editor and insert the following:
  <item name="road-source" icon="[PATH TO ICON]\Yahoo-road.png">
      <key key="source" value="yahoo_wms" />
      <key key="highway" value="road" />
  • Save it as yahoo-presets.xml
  • Open JOSM
  • Open the Preferences, go to the Map Settings (3rd tab)
  • Add your file at the "Tagging Preset Sources"
  • Restart JOSM
  • If you want, you can put the preset in your toolbar for quick access (Preferences, Toolbar customization)
  • You might also want presets for things like Yahoo-farm.png landuse=farm and/or Yahoo-stream.png waterway=stream
  • Download the above icons and add new <item> entries to your yahoo-presets.xml file
  • Contact User:LeedsTracker if you want any more icons made --LeedsTracker 17:04, 28 February 2009 (UTC)

Remote control

Since version 22677 the WMSPlugin will register an additional remote control command "wms" if the RemoteControl plugin version 22675 or newer is loaded.

The "wms" command instructs JOSM to open a WMS layer in the same way as with the "rectified image" menu command.

 GET /wms?title=foobar&urldecode=false&url=...


parameter required/


url R WMS URL in the usual format. This must be the last parameter.
title O Title (name) of WMS layer. If not specified the title will be "remote WMS".
urldecode O Disable URL-decoding of URL value if true. All other values will be URL-decoded anyway.
cookies O Can be used to specify cookies for the WMS request.

Note: The "url" parameter must be the last one. Everything after url= will be used as the WMS URL. It is not mandatory to URL-encode the value, but the WMSPlugin will try to URL-decode it unless urldecode=false is specified. If you notice that the decoding modifies the URL in an unwanted way, add "urldecode=false" before the "url" parameter.

This remote control function can be disabled by setting preferences value


or by using the checkbox "Allow remote control (requires remotecontrol plugin)" in the preferences editor.


Nuvola apps important.svg

You MUST NOT trace over maps, aerial photography, or satellite images from any source, unless the images are public domain, or otherwise compatible with our OpenStreetMap License.

Tracing over an image is generally regarded to be creating a derivative work of the underlying image. This is also the case for aerial photographs as well as for (more clearly copyrighted) finished maps. If the images are copyrighted, or if you are unsure of the copyright status of the images, from a particular source, then you must not use those images for tracing/correcting maps for OpenStreetMap.

Sources you can use
  • NASA Landsat - Public Domain low resolution satellite imagery. Worldwide coverage, but generally too low-res for tracing roads or other such details.
  • Bing Aerial Imagery - Special Permission - We have been given special permission to derive our vector map data.
  • Yahoo! Aerial Imagery - For a long time we've been allowed to derive our vector map data from Yahoo. It requires a special downloader component. Installation described above.
  • De:DOP Sources - List of DOP sources for Germany and their status of permission to use in OSM
  • New Jersey 2007 aerial photography. Only available within and slightly overlapping the borders of New Jersey. There are no restrictions on its use.
  • OpenAerialMap: This is currently offline, but if/when this project is resuscitated it provides open aerial imagery compiled from many sources/imagery donations.
  • WikiProject_Italy/PCN: Covering all of Italy with good ortho-rectification and far better resolution than Yahoo (please don't trace from Yahoo in Italy for this reason, as there is a big offset)

See WMS sources for more information.

Sources you can't use
  • Google map tiles - Copyrighted!
  • Google aerial imagery - Copyrighted!
  • Bing map tiles - Copyrighted! (we're only allowed to use the aerial imagery)
  • Yahoo map tiles - Copyrighted! (we're only allowed to use the aerial imagery)
  • Pretty much any other source which is not explicitly listed above