JOSM Scripting Plugin - JavaScript API V3

Class: Api

josm/api. Api

Collection of static methods to download objects from and upload objects to the OSM server. Note: this class doesn't provide a constructor. Methods and properties are 'static'.

new Api()

Collection of static methods to download objects from and upload objects to the OSM server

Source:
Example
// load the api
import { Api } from 'josm/api'

// download node 12345
const ds = Api.downloadObject(12345, 'node')

Methods

<static> downloadArea(bounds)

Downloads the objects within a bounding box.
Parameters:
Name Type Description
bounds Bounds | module:josm/api~BoundsSpec1 | module:josm/api~BoundsSpec2 the bounding box
Source:
Returns:
the downloaded primitives
Type
DataSet
Example
import { Api } from 'josm/api'
const Bounds = Java.type('org.openstreetmap.josm.data.Bounds')
const LatLon = Java.type('org.openstreetmap.josm.data.coor.LatLon')
const ds1 = Api.downloadArea(new Bounds(
    new LatLon(46.9479186,7.4619484),   // min
    new LatLon(46.9497642, 7.4660683)   // max
))

const ds2 = Api.downloadArea({
    min: {lat: 46.9479186, lon: 7.4619484},
    max: {lat: 46.9497642, lon: 7.4660683}
})

<static> downloadObject(id [, type] [, options])

Downloads an object from the server. There are multiple options to specify what object to download. In addition, the function accepts a set of optional named parameters as last argument.
downloadObject(id, type, ?options)
id is the global numeric id. type is either one of the strings 'node', 'way', or 'relation', or one of the enumeration OsmPrimitiveType.NODE, OsmPrimitiveType.WAY, or OsmPrimitiveType.RELATION
downloadObject(id, ?options)
id is a PrimitiveId or an object with the (mandatory) properties id and type, i.e. an object {id: ..., type: ...}. id is again a number, type is again either one of the strings 'node', 'way', or 'relation', or one of the enumeration OsmPrimitiveType.NODE, OsmPrimitiveType.WAY, or OsmPrimitiveType.RELATION.
Parameters:
Name Type Argument Description
id number | PrimitiveId the id of the object
type string | OsmPrimitiveType <optional>
 the type of the object
options module:josm/api~DownloadObjectOptions <optional>
 named options
Source:
Returns:
the downloaded primitives
Type
DataSet
Example
import { Api } from 'josm/api'
const SimplePrimitiveId = Java.type('org.openstreetmap.josm.data.osm.SimplePrimitiveId')
const OsmPrimitiveType = Java.type('org.openstreetmap.josm.data.osm.OsmPrimitiveType')

// download the node with id 12345
const ds1 = Api.downloadObject(12345, 'node')

// download the node with id 12345
const ds2 = Api.downloadObject({id: 12345, type: 'node'})

// download the full relation (including its members) with id 12345
const id = new SimplePrimitiveId(12345, OsmPrimitiveType.RELATION)
const ds3 = Api.downloadObject(id, {full: true})

// download version 5 of the full way 12345 (including its nodes)
const ds4 = Api.downloadObject(12345, OsmPrimitiveType.WAY, {full: true, version: 5})

<static> downloadReferrer(id [, type] [, options])

Downloads the objects referring to another object from the server. Downloads primitives from the OSM server which refer to a specific primitive. Given a node, the referring ways and relations are downloaded. Given a way or a relation, only referring relations are downloaded. The default behaviour is to reply proxy objects only. If you set the option {full: true}, every referring object is downloaded in full. There are multiple options to specify what referrers to download. In addition, the function accepts a set of optional named parameters as last argument.
downloadReferrer(id, type, ?options)
id is the global numeric id. type is either one of the strings 'node', 'way', or 'relation', or one of the enumeration OsmPrimitiveType.NODE, OsmPrimitiveType.WAY, or OsmPrimitiveType.RELATION.
downloadReferrer(id, ?options)
id is a PrimitiveId or an object with the (mandatory) properties id and type, i.e. an object {id: ..., type: ...}. id is again a number, type is again either one of the strings 'node', 'way', or 'relation', or one of the enumeration OsmPrimitiveType.NODE, OsmPrimitiveType.WAY, or OsmPrimitiveType.RELATION.
Parameters:
Name Type Argument Description
id number | PrimitiveId the id of the object
type string | OsmPrimitiveType <optional>
 the type of the object
options module:josm/api~DownloadReferrerOptions <optional>
 named options
Source:
Returns:
the downloaded primitives
Type
DataSet
Example
import { Api } from 'josm/api'
import { NodeBuilder } from 'josm/builder'
const SimplePrimitiveId = Java.type('org.openstreetmap.josm.data.osm.SimplePrimitiveId')
const OsmPrimitiveType = Java.type('org.openstreetmap.josm.data.osm.OsmPrimitiveType')

// download the objects referring to the node with id 12345
const ds1 = Api.downloadReferrer(12345, 'node')

// download the objects referring to the node with id 12345
const ds2 = Api.downloadReferrer({id: 12345, type: 'node'})

// download the relations referring to the  relation with id 12345.
// Referring relations are downloaded in full.
const id = new SimplePrimitiveId(12345, OsmPrimitiveType.RELATION)
const ds3 = Api.downloadReferrer(id, { full: true })

// create the global node 12345 ...
const node = NodeBuilder.create(12345)
// ... and downloads its referrers in full
const ds = Api.downloadReferrer(node, { full: true })

<static> upload(data, comment [, options])

Uploads objects to the server. You can submit data either as DataSet, APIDataSet, javascript array of OsmPrimitives or a Collection of OsmPrimitives. This method supports the same upload strategy as the JOSM upload dialog. Supply the named parameter {strategy: ...} to choose the strategy.

Be careful when uploading data to the OSM server! Do not upload copyright- protected or test data.

The method takes care to update the primitives in the uploaded data when the upload succeeds. For instance, uploaded new primitives become global objects and get assigned their new id and version, successfully deleted objects become invisible, etc. Even if the entire upload of a dataset fails, a subset therefore may have been uploaded successfully. In order to keep track, which pritives have been uploaded successfully in case of an error, the method replies a collection of the successfully uploaded objects.
Parameters:
Name Type Argument Description
data DataSet | APIDataSet | array | Collection the data to upload
comment string the upload comment
options module:josm/api~UploadOptions <optional>
 named options
Source:
Returns:
Type
Collection
Example
const DataSet = Java.type('org.openstreetmap.josm.data.osm.DataSet')
import { WayBuilder, NodeBuilder } from 'josm/builder'
import { Api } from 'josm/api'
const ds = new DataSet()
const nb = NodeBuilder.forDataSet(ds)
WayBuilder
 .forDataSet(ds)
 .withNodes(
    nb.withTags({name: 'node1'}).create(),
    nb.withTags({name: 'node2'}).create()
 )
 .withTags({name: 'way1'})
 .create()

// uploads the data in a new changeset in one chunk
const processed = Api.upload(ds, 'just testing')