JOSM/RemoteControl
The RemoteControl functionality opens a listening TCP port (8111) on 127.0.0.1 (localhost) where it accepts commands.
To enable the remote control feature, go to 'Edit' menu -> 'Preferences...' and click the remote control icon on the left to see all the settings, and simply tick to enable.
More features are documented under: http://josm.openstreetmap.de/wiki/Help/Preferences/RemoteControl
The JOSM manual page also lists some things that should be checked if it is not working.
Privacy/Security concerns:
Opening a port can enable other applications to detect a running JOSM which might not be desired. It could introduce a security risk based on the actual implementation even with the current implementation considered safe.
The protocol used is HTTP, so that web applications wishing to let the user edit a certain area can simply generate suitable HTTP links. Browsers should always call the http endpoint, not the deprecated https endpoint
It is important to make calls on the 127.0.0.1 loopback IP address and not the localhost hostname: browsers whitelist calls to http://127.0.0.1 from https pages, but not calls to http://localhost.
All commands are implemented as GET requests.
(Partial) List of Commands
 | Much more commands listed on the JOSM documentation |
version command
This command returns the current protocol version. Developers can use it to query for a running instance of JOSM and also determine whether the requested functionality is available in the client.
GET /version[?jsonp=callback] (GET http://127.0.0.1:8111/version )
The command returns a json object containing an application identifier that is always "JOSM RemoteControl", a major number and a minor number. Compatible protocol changes result in an increase of the minor number. Incompatible changes increase the major number. So a client application knowing of protocol version 1.0 can still talk to JOSM having 1.1. But it's not guaranteed to be working with 2.0. So the client should verify the major number.
A typical output looks like this:
{
"protocolversion": {
"major": 1,
"minor": 0
},
"application": "JOSM RemoteControl"
}
For older browsers not implementing Cross-Origin Resource Sharing (CORS) the command provides the possibility for jsonp callback. Load the URL in a script tag and supply the name of a callback that will receive the JSON data.
Following is some sample code that checks for CORS capabilities and uses JSONP as a fallback solution.
// in addition to the CC-BY-SA of the wiki feel free to use the following source for any purpose without restrictions (PD)
// credits and additions appreciated: https://wiki.openstreetmap.org/wiki/User:Stephankn
function checkJOSM(version){
alert(version.application + " uses protocol version " + version.protocolversion.major + "." + version.protocolversion.minor);
// do something useful, maybe showing edit button
}
var url = "http://127.0.0.1:8111/version";
var useFallback = false;
// currently FF3.5, Safari 4 and IE8 implement CORS
if (XMLHttpRequest) {
var request = new XMLHttpRequest();
if ("withCredentials" in request) {
request.open('GET', url, true);
request.onreadystatechange = function(){
if (request.readyState != 4) {
return;
}
if (request.status == 200) {
checkJOSM(eval('(' + request.responseText + ')'));
}
};
request.send();
}
else if (XDomainRequest) {
var xdr = new XDomainRequest();
xdr.open("get", url);
xdr.onload = function(){
checkJOSM(eval('(' + xdr.responseText + ')'));
};
xdr.send();
} else {
useFallback = true;
}
}
else {
// no XMLHttpRequest available
useFallback = true;
}
if (useFallback) {
// Use legacy jsonp call
var s = document.createElement('script');
s.src = url + '?jsonp=checkJOSM';
s.type = 'text/javascript';
if (document.getElementsByTagName('head').length > 0) {
document.getElementsByTagName('head')[0].appendChild(s);
}
}
load_and_zoom command
Instructs JOSM to download a bounding box from the API, zoom to the downloaded area and optionally select one or more objects.
GET /load_and_zoom?left=...&right=...&top=...&bottom=...[&select=object[,object...][&addtags=...]]
where
| parameter | required/
optional |
meaning |
|---|---|---|
| left | R | minimum longitude |
| right | R | maximum longitude |
| bottom | R | minimum latitude |
| top | R | maximum latitude |
| select | O | comma-separated list of objects that should be selected. Object specifiers are combinations of the words "way", "node", or "relation", and the numerical object id. Example: select=way38473,node12399,node54646 Since r13212 the special value select=currentselection let JOSM keep its previous selection.
|
| addtags | O | See full documentation and usage under: /Add-tags. Optional parameter to add tags. The key and value is separated by "=" and multiple tags can be separated by a Pipe "|". New parameter since JOSM 3850 (latest version) Try this one for example. Works also with the zoom-command. The user must review the tags and the selection before the tags are applied to the selected objects. |
Example
Start JOSM, then click on:
JOSM should now load an area in the german Schwarzwald and have the specified node selected.
zoom command
Instructs JOSM to zoom to the specified area and optionally select one or more objects. (available since remotecontrol revision 22734)
GET /zoom?left=...&right=...&top=...&bottom=...&select=object[,object...]
Accepts the same parameters as the load_and_zoom command and uses the same code for zoom and selection. The only difference is that no data will be loaded from the API.
Hint: This command can also be used to select objects only. Just enter a small arbitrary area to the left..bottom entries and add the object list to the select= option.
import command
Instructs JOSM to download the specified OSM file and add it to the current data set.
GET /import?url=...
where
| parameter | required/
optional |
meaning |
|---|---|---|
| url | R | URL to download data from |
other commands
More features are documented under: http://josm.openstreetmap.de/wiki/Help/Preferences/RemoteControl
Remote Control allows plugins to add additional commands. The plugin registers a RequestHandler class and specifies a command to be handled by this class. The command syntax has to be defined.
Currently Reverter plugin since 27091 makes use of this feature.
Security
Since the remote control feature contacts remote servers, if you are of the security conscious kind, you might want to know exactly what it does, and allow or disallow certain actions. The following configuration options are available:
| configuration option | default value | meaning |
|---|---|---|
| remotecontrol.always-confirm | false | if true, each remote control request must be approved in a pop-up dialog. This will be checked also for commands added by other plugins. |
| remotecontrol.permission.change-selection | true | allows remote control to change which objects are selected |
| remotecontrol.permission.change-viewport | true | allows remote control to zoom/pan to another location |
| remotecontrol.permission.import | true | allows remote control to import data from remote URLs |
| remotecontrol.permission.load-data | true | allows remote control to load data from OSM API |
| remotecontrol.permission.read-protocolversion | true | allows remote control to report its protocol version |
Plugins that register additional commands can specify a similar setting to disable the specific command registered by this plugin. Since this is controlled by the plugin, the setting should be in the plugin's preferences name space and should be handled by the plugin's preferences editor.
Use from this wiki
Several templates create links for the RemoteControl feature.
- Template:BrowseRelation for loading a relation in JOSM
- Template:JOSMLoadXAPI for loading elements in JOSM