Open Database License/Changes in the API

From OpenStreetMap Wiki
Jump to navigation Jump to search

This page documents the changes that have been made to the API (more precisely, to the OSM XML data emitted by the API) in conjunction with the license change.

If you are an editor writer or the author of software that interacts otherwise with the API, you should read this and make sure that your software can cope with these changes.

Technical Overview

The license change has been performed on the live database (i.e. no dump and reload). Data contributed by non-agreers has, for the time being, been kept in the database but specially marked.

For every object that is tainted in some way by non-agreeing edits, a bot has modified or deleted the object so that the current version is ODbL compatible. (In the worst case this will mean that the current version is deleted, but a deleted version *is* ODbL compatible.) The exact modifications made by the bot are not the subject of this discussion; the important bit is that after the bot is through, the current version of every object is "clean".

Special note for nodes that have to be deleted: When the bot deletes a node it will also set its latitude and longitude to zero because otherwise the node would, even though it is deleted, still contain information created by a decliner. The deleted version is then accessible through the API.

Historic versions may not be "clean", and have been internally flagged as such by the bot. In extreme cases, all but the most recent version of an object may be flagged. When the API is asked for historic information, these versions will not be returned. We call the process of suppressing historic versions "redaction". There are two modes of "redaction": Some historic versions have to be redacted because they have been created by a decliner; by definition these do not contribute to the final, bot-modified version of the object (else the final version would have to be CC-BY-SA licensed). Other historic versions have to be redacted because they carry over information created by a decliner, even though the version itself was created by an agreer.

Currently, both types of redaction are treated in the same manner; historic versions redacted in any way will not be returned in a history call. It is possible that, at a later time, we will release some information about those redacted versions created by agreers (e.g. user and timestamp).

Simple "redaction" example

This table illustrates what happens to a node that has received edits by both decliners and agreers.

version created by before license change action after license change
1 agreer node id=123 lat="50.1" lon="8.1"

amenity="restaurant"

allow node id=123 lat="50.1" lon="8.1"

amenity="restaurant"

2 decliner node id=123 lat="50.1" lon="8.1"

amenity="restaurant"
cuisine="pizza"

redact

"hidden"

Version cannot be shown because it has been created by decliner.
3 agreer node id=123 lat="50.1" lon="8.1"

amenity="restaurant"
cuisine="pizza"
name="Luigi's"

redact

"visible"

Version cannot be shown because it contains information created by a decliner.

Metadata (timestamp, uid, changeset) might be shown later, but currently the version is completely hidden.

4 license change bot not present create new version node id=123 lat="50.1" lon="8.1"

amenity="restaurant"
name="Luigi's"

Changes to API calls

Object history call /api/{node|way|relation}/{id}/history

The history call works as before, and will always return at least one historic version (the latest version). However, some historic versions may be missing from the response. There is no guarantee that a version 1 will exist, for example.

It is possible to modify the request by adding "?show_redactions=true". If you do this, and are authenticated with an account that has moderator privileges, you will be shown the historic versions, with an extra attribute called "redacted", which points to the ID of the redaction process/type - currently 1 for objects redacted because they were contributed by decliners, and 2 for objects redacted because they carried over such information.

If you are not logged in with a moderator account, ?show_redactions=true has no effect.

The history XML for the node in the earlier example would look like this without "show_redactions=true":

<node id="123" version="1" lat="50.1" lon="8.1" uid="1" user="bob" changeset="1" timestamp="...">
   <tag k="amenity" v="restaurant" />
</node>
<node id="123" version="4" lat="50.1" lon="8.1" uid="4" user="OSMF Redaction Accountt" changeset="4" timestamp="...">
   <tag k="amenity" v="restaurant" />
   <tag k="name" v="Luigi's" />
</node>

If you put "show_redactions=true" and have moderator privileges, then you get:

<node id="123" version="1" lat="50.1" lon="8.1" uid="1" user="bob" changeset="1" timestamp="...">
   <tag k="amenity" v="restaurant" />
</node>
<node id="123" version="2" lat="50.1" lon="8.1" uid="2" user="alice" changeset="2" timestamp="..." redacted="1">
   <tag k="amenity" v="restaurant" />
   <tag k="cuisine" v="pizza" />
</node>
<node id="123" version="3" lat="50.1" lon="8.1" uid="3" user="charlie" changeset="3" timestamp="..." redacted="2">
   <tag k="amenity" v="restaurant" />
   <tag k="cuisine" v="pizza" />
   <tag k="name" v="Luigi's" />
</node>
<node id="123" version="4" lat="50.1" lon="8.1" uid="4" user="OSMF Redaction Account" changeset="4" timestamp="...">
   <tag k="amenity" v="restaurant" />
   <tag k="name" v="Luigi's" />
</node>


Individual version access call /api/0.6/{node|way|relation}/{id}/{version}

Will return a HTTP 403 Forbidden message if an attempt is made to access a "redacted" version.

If "?show_redactions=true" is added and you are authenticated with an account having moderator privileges, you will get a normal response with a "redacted" attribute.

In addition to this, any request for a deleted node does not return a "lat" and "lon" attribute any longer. This was the case before.

Changeset information call /api/0.6/changeset/{id}

A changeset created by someone who did not agree to the license change can, at present, still be accessed with its metadata intact (created_at, closed_at, bbox, num_changes) and all its tags.

This will likely be changed to omit all tags in the future if the user has not agreed to the license change.

Changeset download call /api/changeset/{id}/download

Changesets can be downloaded as before but any historic versions that have been redacted will be missing from the changeset. This can affect both changesets made by agreers and by decliners; if some of a decliner's contributions are not considered copyrightable they will still be visible (i.e. not all decliners' changesets are necessarily empty).

Note that this may cause a discrepancy between what you read in the comment ("re-aligned roundabout") and what you see in the changeset contents (e.g. just a couple deletions).

There is no way to download a full changeset even with moderator privileges.

Other API calls

remain unchanged.

Changes to dump files

Planet file

Remains unchanged (some objects deleted/changed due to license change but no structural change).

Full History Planet File

Redacted object versions will now be missing. It is possible that we decide to emit placeholder objects with limited metadata, this has not yet been decided. All deleted nodes will now lack lat/lon attributes.

changesets-latest.osm.bz2

No change at this time; expect to drop tags from decliner changesets later.