API.md 8.12 KB
Newer Older
1
This file documents efforts toward establishing a public API for iD.
2

3 4
## URL parameters

5 6
##### iD Standalone

7 8 9 10
iD supports several URL parameters. When constructing a URL to a standalone instance
of iD (e.g. `http://openstreetmap.us/iD/release/`), the following parameters are available
in the hash portion of the URL:

11 12
* `map` - A slash separated `zoom/longitude/latitude`.  Example:
  `map=20.00/-77.02271/38.90085`
13 14 15 16
* `id` - The character 'n', 'w', or 'r', followed by the OSM ID of a node,
   way or relation, respectively. Selects the specified entity, and, unless
   a `map` parameter is also provided, centers the map on it.
* `background` - The value from a `sourcetag` property in iD's
John Firebaugh's avatar
John Firebaugh committed
17
  [imagery list](https://github.com/openstreetmap/iD/blob/master/data/imagery.json),
18 19
  or a custom tile URL. A custom URL is specified in the format `custom:<url>`,
  where the URL can contain the standard tile URL placeholders `{x}`, `{y}` and
Bryan Housel's avatar
Bryan Housel committed
20
  `{z}`/`{zoom}`, `{ty}` for flipped TMS-style Y coordinates, and `{switch:a,b,c}` for
21
  DNS multiplexing.  Example:
Bryan Housel's avatar
Bryan Housel committed
22
  `background=custom:http://{switch:a,b,c}.tiles.mapbox.com/v4/examples.map-4l7djmvo/{z}/{x}/{y}.png`
23 24 25 26 27
* `gpx` - A custom URL for loading a gpx track.  Specifying a `gpx` parameter will
  automatically enable the gpx layer for display.  Example:
  `gpx=https://tasks.hotosm.org/project/592/task/16.gpx`
* `offset` - imagery offset in meters, formatted as `east,north`.  Example:
  `offset=-10,5`
28
* `comment` - Prefills the changeset comment box, for use when integrating iD with
29
  external task management or quality assurance tools.  Example:
30
  `comment=CAR%20crisis%2C%20refugee%20areas%20in%20Cameroon%20%23hotosm-task-592`.
31

32 33
##### iD on openstreetmap.org (Rails Port)

34 35 36 37
When constructing a URL to an instance of iD embedded in the OpenStreetMap Rails
Port (e.g. `http://www.openstreetmap.org/edit?editor=id`), the following parameters
are available as regular URL query parameters:

38 39
* `map` - slash separated `zoom/latitude/longitude`.  Example:
  `map=20.00/38.90085/-77.02271`.
40 41
* `lat`, `lon`, `zoom` - Self-explanatory.
* `node`, `way`, `relation` - Select the specified entity.
42 43 44 45
* `background` - same as standalone
* `gpx` - same as standalone
* `offset` - same as standalone
* `comment` - same as standalone
46

47

48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
## CSS selectors

iD has a documented and stable set of classes that can be used to apply style or
attach behavior to the visual representation of map data via CSS selectors.
These classes relate to the vocabulary of the OSM data model, a related geometric
vocabulary established by iD, and to the tags present on OSM entities.

### OSM Data Model classes

An SVG element on the map to which an iD.Entity has been bound as a datum shall
have a class with that datum's type, i.e. either `.node` or `.way`. (If and when
we add visual representations for relations, `.relation` may also be valid.)

The visual representation of a single entity may be composed of several elements,
e.g. ways are composed of casing and stroke. Such elements will have a distinct class
identifying the particular aspect of representation, e.g. `.casing` and `.stroke`.

The particular type of SVG element (`path`, `circle`, `image` etc.) that is used to
implement that visual representation is explicitly NOT part of the public API. Avoid
naming specific tags in CSS selectors; as iD evolves, we may need to change what SVG
elements we use in order to implement a particular visual style.

### Geometric classes

In addition to the OSM element vocabulary of nodes, ways, and relations, iD has
73 74
established a related geometric vocabulary consisting of points, vertices, midpoints,
lines, and areas.
75

John Firebaugh's avatar
John Firebaugh committed
76 77 78 79 80
A **point** is a node that is not a member of any way. Elements representing points
have a `.point` class. Since a point is always a node, they also have a `.node` class.

A **vertex** is a node that is a member of one or more ways. Elements representing
points have `.vertex` and `.node` classes.
81

82 83 84 85
A **midpoint** is a virtual point drawn midway between two vertices along a way.
Midpoints indicate the direction that the way, but can also be selected and dragged
to create a new point along the way.  Midpoints are classed with a `.midpoint` class.

86 87 88 89
A **line** is a way that is not an area. Elements representing lines have a `.line`
class. Since a line is also a way, they also have a `.way` class.

An **area** is a way that is circular, has certain tags, or lacks certain other
90
tags (see `iD.Way#isArea` for the exact definition). Elements representing areas
John Firebaugh's avatar
John Firebaugh committed
91
have `.area` and `.way` classes.
92

93

94 95
### Tag classes

96
Elements also receive classes according to certain of the OSM key-value tags that are
97 98
assigned to them.

99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124
Tag classes are prefixed with `tag-` (see [`iD.svg.TagClasses`](https://github.com/openstreetmap/iD/blob/master/js/id/svg/tag_classes.js) for details).

#### Primary

An element may be classed with at most one primary tag class based on its main OSM
key -- "building", "highway", "railway", "waterway", etc.
(e.g. `.tag-highway .tag-highway-residential`).

#### Secondary

An element may be classed with one or more secondary tag classes based on other
interesting OSM keys -- "bridge", "tunnel", "barrier", "surface", etc.
(e.g. `.tag-bridge .tag-bridge-yes`).

#### Status

An element may be classed with at most one status tag.  Status tagging in OSM can
be either key or value based, but iD attempts to detect most common lifecycle tagging
schemes -- "construction", "proposed", "abandoned", "disused", etc.
(e.g. `.tag-status .tag-status-construction`).

#### Unpaved Surfaces (highways only)

Most vehicular highways in OSM are assumed to have a smooth paved surface. A highway
element may receive the special tag class `.tag-unpaved` if it contains certain OSM tags
indicating a bumpy surface.
125 126 127

### Special classes

128
A node that is a member of two or more ways shall have the `.shared` class.
129 130 131 132 133 134 135 136

Two or more nodes at identical coordinates shall each have an `.overlapped` class. (TODO)

Elements comprising the entity currently under the cursor shall have the `.hover` class.
(The `:hover` psuedo-class is insufficient when an entity's visual representation consists
of several elements, only one of which can be `:hover`ed.)

Elements that are currently active (being clicked or dragged) shall have the `.active`
137
class.
138

139
Elements that are currently selected shall have the `.selected` class.
140 141 142 143 144 145 146 147 148 149 150 151 152

## Customized Deployments

iD is used to edit data outside of the OpenStreetMap environment. There are some basic configuration steps to introduce custom presets, imagery and tag information.

### Presets

iD can use external presets exclusively or along with the default OpenStreetMap presets. This is configured using the `iD().presets` accessor. To use external presets alone, initialize iD in index.html with the Presets object.

```js

var iD = iD()
  .presets(customPresets)
Bryan Housel's avatar
Bryan Housel committed
153
  .taginfo(iD.services.taginfo())
154 155 156 157 158 159 160 161 162 163 164 165 166 167
  .imagery(iD.data.imagery);

```

The format of the Preset object is [documented here](https://github.com/openstreetmap/iD/tree/master/data/presets#custom-presets).

### Imagery

Just like Presets, Imagery can be configured using the `iD().imagery` accessor.

```js

var iD = iD()
  .presets(customPresets)
Bryan Housel's avatar
Bryan Housel committed
168
  .taginfo(iD.services.taginfo())
169 170 171 172
  .imagery(customImagery);

```

173
The Imagery object should follow the structure defined by [editor-layer-index](https://github.com/osmlab/editor-layer-index/blob/gh-pages/schema.json)
174 175 176 177 178 179 180 181 182 183


### Taginfo

[Taginfo](http://taginfo.openstreetmap.org/) is a service that provides comprehensive documentation about the tags used in OpenStreetMap. iD uses Taginfo to display description and also autocomplete keys and values. This can be completely disabled by removing the `iD().taginfo` accessor. To point iD to a different instance of Taginfo other than the default OpenStreetMap instance

```js

var iD = iD()
  .presets(customPresets)
Bryan Housel's avatar
Bryan Housel committed
184
  .taginfo(iD.services.taginfo().endpoint('url'))
185 186
  .imagery(customImagery);

187 188 189 190
```

### Minimum Editable Zoom

Bryan Housel's avatar
Bryan Housel committed
191
The minimum zoom at which iD enters the edit mode is configured using the `iD().minEditableZoom()` accessor. The default value is 16. To change this initialise iD as
192 193 194 195 196 197 198 199

```js

var iD = iD().
  .minEditableZoom(zoom_level)

```

Bryan Housel's avatar
Bryan Housel committed
200
This should be set with caution for performance reasons. The OpenStreetMap API has a limitation of 50000 nodes per request.