wiki:Help/RemoteControlCommands

Version 21 (modified by stoecker, 4 years ago) ( diff )

Do not documented unwanted behaviour

This page is missing command features.

Languages:

Remote control commands

  1. load_and_zoom
  2. zoom
  3. import
  4. load_data
  5. open_file
  6. imagery
  7. load_object
  8. add_node
  9. add_way
  10. version
  11. Adding, changing or deleting tags
  12. Other commands

List of Commands

A complete list of commands and mandatory/optional parameters is shown at ​http://127.0.0.1:8111/ (when JOSM is running).

load_and_zoom

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...]

where

Parameter Required/
Optional 		Meaning
bottom R Minimum latitude
top R Maximum latitude
left R Minimum longitude
right R Maximum longitude
new_layer O If true, downloads to a new layer. (Overwrites user preference, see #19308)
layer_name O Only valid when the data is loaded in a new layer; Gives JOSM a hint on how to name the layer
layer_locked O Only valid when the data is loaded in a new layer; If true, new layer is locked
download_policy O Only valid when the data is loaded in a new layer; If never , download is blocked
upload_policy O Only valid when the data is loaded in a new layer; If never or false, upload is blocked or discouraged
addtags O Optional parameter to add tags. The key and value is separated by "=" and multiple tags can be separated by a Pipe "|". See details.
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 currentselection let JOSM keep its previous selection.
zoom_mode O download | selection, defaults to selection
changeset_comment O Comment of the changeset
changeset_source O Source of the changeset
changeset_hashtags O Hashtags of the changeset (since r13109)
changeset_tags O Optional parameter to add changeset tags. The key and value is separated by "=" and multiple tags can be separated by a Pipe "|". This command uses the same syntax as the addtags parameter. changeset_comment and changeset_source currently override the comment and source tags passed in this parameter, but this may change in the future. (since r15316)
search O Search objects in the current data layer. See Search

Example

Start JOSM (don't forget to enable the RemoteControl feature), then click on:

​http://127.0.0.1:8111/load_and_zoom?left=8.19&right=8.20&top=48.605&bottom=48.590&select=node413602999

JOSM should now load an area in the German Schwarzwald and have the specified node selected.

zoom

Instructs JOSM to zoom to the specified area and optionally select one or more objects. 

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

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 The Request URL, including patterns. Must be the last parameter, everything after "&url=" is interpreted as URL, even if it contains "&" characters.
new_layer O If true, downloads to a new layer. (Overwrites user preference, see #19308)
layer_name O Only valid when the data is loaded in a new layer; Gives JOSM a hint on how to name the layer
layer_locked O Only valid when the data is loaded in a new layer; If true, new layer is locked
download_policy O Only valid when the data is loaded in a new layer; If never , download is blocked
upload_policy O Only valid when the data is loaded in a new layer; If never or false, upload is blocked or discouraged
changeset_tags O Optional parameter to add changeset tags. The key and value is separated by "=" and multiple tags can be separated by a Pipe "|". This command uses the same syntax as the addtags parameter. First available in r16324.

load_data

(since version 1.6)

Instruct JOSM to load OSM data, directly encoded in the URL, instead of coming from an external file. This is only suited for smaller data (some browsers limit the maximum URL length), but it is faster (since no download is required), and in many cases where dynamically generated data is needed, it's easier to generate. 

GET /load_data?new_layer=(true/false)&layer_name=...&mime_type=...&data=...

where

Parameter Required/
Optional 		Meaning
data R The XML data to load, this should be URL encoded in a way that also encodes the special characters &, = and ? to resp. %26, %3D and %3F. The JS ​encodeUriComponent() method provides this functionality out of the box.
new_layer O Choose to load the data in a new layer. (Overwrites user preference, see #19308)
mime_type O Mime type of the data, by default this is "application/x-osm+xml", which is currently the only supported mime type, but in the future other mime types could be supported
layer_name O Only valid when the data is loaded in a new layer; Gives JOSM a hint on how to name the layer
layer_locked O Only valid when the data is loaded in a new layer; If true, new layer is locked
download_policy O Only valid when the data is loaded in a new layer; If never , download is blocked
upload_policy O Only valid when the data is loaded in a new layer; If never or false, upload is blocked or discouraged

open_file

Open a local file in JOSM. 

GET /open_file?filename=...

where

Parameter Required/
Optional 		Meaning
filename R The local file to open in JOSM (Ie: /tmp/test.osm)

imagery

Instructs JOSM to add an imagery (WMS/TMS) layer. 

GET /imagery?title=...&type=...&url=...

where

Parameter Required/
Optional 		Meaning
url R The Request URL, including patterns. Must be the last parameter, everything after "&url=" is interpreted as URL, even if it contains "&" characters.
title O The display name of the layer
type O Type of the layer. Possible values are wms, tms and bing (defaults to wms, since RemoteControl Version 1.3)
cookies O
min_zoom O The minimum zoom level (since RemoteControl Version 1.4)
max_zoom O The maximum zoom level. For higher scales, the images of the maximum level is enlarged (since RemoteControl Version 1.4)
name O alias for title (since RemoteControl Version 1.10)
attribution-text O (since RemoteControl Version 1.10)
attribution-url O (since RemoteControl Version 1.10)
bestMarked O (since RemoteControl Version 1.10)
bounds O (since RemoteControl Version 1.10)
category O (since RemoteControl Version 1.10)
country-code O (since RemoteControl Version 1.10)
customHttpHeaders O (since RemoteControl Version 1.10)
date O (since RemoteControl Version 1.10)
default-layers O (since RemoteControl Version 1.10)
description O (since RemoteControl Version 1.10)
eula O (since RemoteControl Version 1.10)
icon O (since RemoteControl Version 1.10)
id O (since RemoteControl Version 1.10)
logo-image O (since RemoteControl Version 1.10)
logo-url O (since RemoteControl Version 1.10)
metadataHeaders O (since RemoteControl Version 1.10)
minimumTileExpire O (since RemoteControl Version 1.10)
modTileFeatures O (since RemoteControl Version 1.10)
noTileChecksums O (since RemoteControl Version 1.10)
noTileHeaders O (since RemoteControl Version 1.10)
overlay O (since RemoteControl Version 1.10)
permission-reference-url O (since RemoteControl Version 1.10)
pixel-per-eastnorth O (since RemoteControl Version 1.10)
projections O (since RemoteControl Version 1.10)
shapes O (since RemoteControl Version 1.10)
terms-of-use-text O (since RemoteControl Version 1.10)
terms-of-use-url O (since RemoteControl Version 1.10)
tileSize O (since RemoteControl Version 1.10)
transparent O (since RemoteControl Version 1.10)
type O (since RemoteControl Version 1.10)
valid-georeference O (since RemoteControl Version 1.10)

mandatory parameters: url optional parameters: title, type, cookies, min_zoom, max_zoom

Examples

  • TMS layer "osm" https://tile.openstreetmap.org/{zoom}/{x}/{y}.png

​http://localhost:8111/imagery?title=osm&type=tms&min_zoom=1&max_zoom=20&url=https://tile.openstreetmap.org/%7Bzoom%7D/%7Bx%7D/%7By%7D.png

  • WMS layer "landsat" http://irs.gis-lab.info/?layers=landsat&SRS={proj}&WIDTH={width}&HEIGHT={height}&BBOX={bbox}

​http://localhost:8111/imagery?title=landsat&type=wms&url=http://irs.gis-lab.info/?layers=landsat&SRS=%7Bproj%7D&WIDTH=%7Bwidth%7D&HEIGHT=%7Bheight%7D&BBOX=%7Bbbox%7D

load_object

Instructs JOSM to download objects with a given id. 

GET /load_object?new_layer=true|false&objects=...

where

Parameter Required/
Optional 		Meaning
objects R Comma separated list of object ids, e.g. "n1234,n1235,w84,r958493"
new_layer O If true, downloads to a new layer. (Overwrites user preference, see #19308)
addtags O Optional parameter to add tags. The key and value is separated by "=" and multiple tags can be separated by a Pipe "|". See details.
relation_members O If true, downloads objects members of the relations as well.
referrers O If true, downloads referrers of the object as well. I.e. parent relations, and for nodes, additionally, parent ways. (since r6782)
layer_name O Only valid when the data is loaded in a new layer; Gives JOSM a hint on how to name the layer
layer_locked O Only valid when the data is loaded in a new layer; If true, new layer is locked
download_policy O Only valid when the data is loaded in a new layer; If never , download is blocked
upload_policy O Only valid when the data is loaded in a new layer; If never or false, upload is blocked or discouraged

Example

​http://localhost:8111/load_object?new_layer=true&objects=w106159509

add_node

Instructs JOSM to create a new node at the given coordinates.

Note: This action requires the permission Create new objects which is disabled by default. 

GET /add_node?lon=...&lat=...

where

Parameter Required/
Optional 		Meaning
lon R The longitude of the node
lat R The latitude of the node
addtags O Optional parameter to add tags. The key and value is separated by "=" and multiple tags can be separated by a Pipe "|". See details. (since v1.5)

Example

​http://localhost:8111/add_node?lon=13.3&lat=53.2

add_way

Instructs JOSM to create a new way with new way nodes at given coordinates.

Note: This action requires the permission Create new objects which is disabled by default. 

GET /add_way?way=lat1,lon1;lat2,lon2;...

where

Parameter Required/
Optional 		Meaning
way R Pairs of latitude, longitude coordinates separated by semicolon.
addtags O Optional parameter to add tags. The key and value is separated by "=" and multiple tags can be separated by a Pipe "|". See details. (since v1.5)

Example

​http://localhost:8111/add_way?way=53.2,13.3;53.3,13.3;53.3,13.2

version

This command returns the current protocol version of the installed RemoteControl interface. 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]

where

Parameter Required/
Optional 		Meaning
jsonp O Jsonp callback for older browsers not implementing ​Cross-Origin Resource Sharing (CORS)

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",
   "version": 16587 // JOSM version (since r16587)
}

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);
   }
    
}

Adding, changing or deleting tags

Try this example: ​http://localhost:8111/load_and_zoom?addtags=wikipedia%3Ade=Weiße_Gasse%7Cmaxspeed=5&select=way23071688,way23076176,way23076177,&left=13.739727546842&right=13.740890970188&top=51.049987191025&bottom=51.048466954325. (Works also with the zoom-command)

The user must review the tags and the selection before the tags are applied to the selected objects. If the tag exists on some objects, it will be replaced.

Since protocol version 1.5

  • add_node and add_way commands support addtags parameter
  • It is possible to use = character in value and all leading/trailing spaces are trimmed.

​http://localhost:8111/add_node?lon=13.3&lat=53.2&addtags=natural=tree%7Cname=%20%20%20==Great%20Oak== (creates node with natural=tree an name="==Great Oak==")

  • If empty value is found, tag is to be deleted from objects (checkbox-confirmation is needed)

​http://localhost:8111/load_and_zoom?addtags=wikipedia%3Ade=%7Cmaxspeed=&select=way23071688,way23076176,way23076177,&left=13.739727546842&right=13.740890970188&top=51.049987191025&bottom=51.048466954325.

Other commands

Remotecontrol allows other plugins to add additional commands. The other registers a RequestHandler class and specifies a command to be handled by this class. The command syntax has to be defined by the other plugin.

Reverter plugin since version 27091 makes use of this feature.

Back to Remote control preferences
Back to Preferences
Back to Main Help

Note: See TracWiki for help on using the wiki.