Class 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".

// load the changeset api
var api = require("josm/api").Api;

// download node 12345 
var ds = api.downloadObject(12345, "node");

Functions

downloadArea:DataSet

Downloads the objects within a bounding box.

Examples

var api = require("josm/api").Api;
var ds1 = api.downloadArea(new Bounds(
    new LatLon(46.9479186,7.4619484),   // min
    new LatLon(46.9497642, 7.4660683)   // max
));

var ds1 = api.downloadArea({
    min: {lat: 46.9479186, lon: 7.4619484}, 
    max: {lat: 46.9497642, lon: 7.4660683}  
}); 

downloadObject:DataSet

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.

full: boolean

If true, the object and its immediate children are downloaded, i.e. the nodes of a way and the relation members of a relation. Default if missing is false.

version: number

If present, the specified version of the object is downloaded. If missing, the current version is downloaded.

Examples

var api = require("josm/api").Api;
var SimlePrimitiveId = org.openstreetmap.josm.data.osm.SimplePrimitiveId;
var OsmPrimitiveType = org.openstreetmap.josm.data.osm.OsmPrimitiveType;

// download the node with id 12345
var ds1 = api.downloadObject(12345, "node");

// download the node with id 12345
var ds2 = api.downloadObject({id: 12345, type: "node"});

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

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

downloadReferrer:DataSet

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.

full:boolean

If true, the the full objects are retrieved using multi-gets. If missing or false, only proxy objects are downloaded. Default: false

Examples

var api = require("josm/api").Api;
var nbuilder = require("josm/builder").NodeBuilder;
var SimlePrimitiveId = org.openstreetmap.josm.data.osm.SimplePrimitiveId;
var OsmPrimitiveType = org.openstreetmap.josm.data.osm.OsmPrimitiveType;

// download the objects referring to the node with id 12345
var ds1 = api.downloadReferrer(12345, "node");

// download the objects referring to the node with id 12345
var ds2 = api.downloadReferrer({id: 12345, type: "node"});

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

 // create the global node 12345 ...
 var node = nbuilder.create(12345);
 // ... and downloads its referrers in full 
 var ds = api.downloadReferrer(node, {full: true});

upload:Collection

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

Named options

strategy: string|UploadStrategy

Indicates how the data is uploaded. Either one of the strings

• individualobjects
• chunked
• singlerequest

or one of the enumeration values in UploadStrategy. Default falue: UploadStrategy.DEFAULT_UPLOAD_STRATEGY

changeset: number|Changeset

The changeset to which the data is uploaded. Either a number (the changeset id) or a Changeset instance. Default: creates a new changeset.

chunkSize: number

The size of an upload chunk, if the data is uploaded with the upload strategy UploadStrategy.CHUNKED_DATASET_STRATEGY.

closeChangeset: boolean

If true, closes the changeset after the upload. Default: true

Parameters

Examples

var ds = new org.openstreetmap.josm.data.osm.DataSet();
ds.wayBuilder.withNodes(
    ds.nodeBuilder.withTags({name: 'node1'}).create(),
    ds.nodeBuilder.withTags({name: 'node2'}.create()
).withTags({name: 'way1'}).create();
var api = require("josm/api").Api;

// uploads the data in a new changeset in one chunk)
var processed = api.upload(ds, "just testing");