Talk:API v0.6

From OpenStreetMap Wiki
Jump to: navigation, search

Better history mechanism

The API 0.5 allows object-based history queries. Unfortunately there are many operations that destroy this history. Furthermore, there is no reliable way to determine which objects (nodes / ways / relations) were inside a given region at a certain historic date, because someone may have moved a node that was inside the region hundreds of miles.

To implement, such region-based historic queries, we need 3 dimensional database queries. If a node has n versions, it's represented as n line segments e.g.

(lat_1, lon_1, start_time_1) - (lat_1, lon_1, start_time_2)

(lat_2, lon_2, start_time_2) - (lat_2, lon_2, start_time_3)


(lat_n, lon_n, start_time_n) - (lat_n, lon_n, infinite)

The answer is then all the nodes that intersect the plane created by keeping the query time constant. It may be easier to implement only the search by lat,lon and then filter by time. Few objects have extensive histories.

The database can already store multiple versions of ways. The start and end times are known. So to find ways that were inside the target region at the specified time, we just need to find all versions of all ways that refer to any of the nodes inside the region and for which the start and end times lie on either side of the specified time.

The upside of all this will be that JOSM (or another editor) will be able to draw the map exactly as it was on any historic date. Now that the TIGER import is complete, the servers will surely have the capacity to implement this, even if they always return all the history.

Perhaps it's not for Protocol 0.6, but it's food for thought -- Nic 21:37, 11 June 2008 (UTC)


To compare the current map with a historic map, an editor may e.g. paint the one as usual and the other with an XOR device-context / graphics context. This will highlight changes in most cases.

Restoring an older version of an object will require a number of sanity checks and special cases. For example way 1 may have been extended and then split into way 1 and way 2 such that the new way 1 and the original way 1 share no segments. If the user now wants to delete way 2 and restore the original way 1 without deleting the current way 1, a new way must be created. Whenever it's difficult to preserve the object history, don't. There are already many other operations (e.g. combine ways) that don't -- Nic 17:35, 15 June 2008 (UTC)

Moved info

Some things discussed just aren't going to happen. Where they might happen in the future, I'm putting them here. And the front page is becoming unreadable.

  • Limiting trackpoints age [1]
Can I suggest that limiting the age of trackpoints is not always desirable. It is very useful to be able to average out errors over two or more tracks. Some areas are still very sparsely populated with trackpoints. Some older tracks will still be perfectly valid. I agree, however, that in certain areas it would be useful to mark trackpoints as out of date - e.g. if the road layout changes. Richard B 14:33, 7 May 2008 (UTC)
This doesn't require an API change. --GabrielEbner 09:06, 8 May 2008 (UTC)

Why specifying user and uid? Uid should be a ref to another object. For example:

  <user uid="123" user="fred" />

--Skinkie 17:41, 5 June 2008 (UTC)

  • The history will be thrown away, again. Because... someone please justify this action
    • The basic issue is that with the node tags being split into a seperate table, this table needs to be created. Also with the restriction of only one value per key a lot of the old data becomes invalid. This is the only reason as far as I know. I think that it's possible we could keep it, but I'm not the person writing the code... - Kleptog
    • To put that into perspective, I have written the code to split the node tags into a separate table. This will not remove history. It's just multiple tags with the same key that might cause problems, but it should be relatively easy to modify the historical tags instead of throwing them away. As far as I remember, at the hackathon it was proposed to delete the history once again; but we had a general consensus to keep it (also to facilitate determining authors viz. copyright for an eventual switch to another license.) --GabrielEbner 13:30, 6 May 2008 (UTC)

    • Are there cases where new version number != old version number + 1? --Frederik Ramm 14:06, 5 May 2008 (UTC)
      • Possibly no. But in the future with transactional updates we decided we couldn't necessarily rule out the possibility that numbers might be skipped, depending on where exactly the numbers were generated. So we decided to play it safe: less assumptions is good. -- Kleptog
        • But it will always increase, won't it?--Bartv 11:47, 19 May 2008 (UTC)

Late comments on the interface

Overloading of PUT method

API methods use a "create" URL interface with PUT, rather than the more standard POST on the parent class.


PUT /api/0.6/node/create


POST /api/0.6/node

Is there a good reason for this departure from standard practice? If there isn't, should support POST method as well. Suspect clients have already implemented PUT form, so would need to deprecate it eventually if POST is agreed preferable.

--Hubne 12:48, 8 November 2008 (UTC)

  • I couldn't agree more. There are several places where we should be using POST, but we're using PUT instead. This should be a simple change for clients and is certainly a simple change for the API code, so I recommend we do it. --Matt 13:42, 8 November 2008 (UTC)
  • I also agree completely. RFC 2616 section 9.6 is quite clear that the purpose of PUT is to write a new resource with the URI specified: "The PUT method requests that the enclosed entity be stored under the supplied Request-URI". I'd expect a subsequent GET on that URI to retrieve the object put (or some equivalent transformed version of it - say in a different format, maybe JSON instead of XML). A request like:
PUT /api/0.6/changeset/create

should write a resource with a URL like which is clearly not what is intended here. Instead this request creates a new resource with a URL like which is specifically prohibited by RFC 2616: "...and the server MUST NOT attempt to apply the request to some other resource". --EdD 12:03, 1 April 2009 (UTC)

Identifying changeset closes by path

I can't quite put my finger on why, but it seems more natural and safe to signal the intention to close a changeset from within the payload (e.g. with an attribute on the changeset element).


PUT /api/0.6/changeset/#id/close


PUT /api/0.6/changeset/#id

with payload starting with:

  <changeset id=".." close="yes">

Again, if accepted, would need to support two forms of API calls for a period and deprecate the current one.

--Hubne 12:48, 8 November 2008 (UTC)

  • I don't like this, as it implies that you could PUT with changeset attribute close="no", when that isn't possible. Again, I favour a POST to changeset/#id/close (with or without a payload) rather than a PUT. --Matt 13:46, 8 November 2008 (UTC)
I guess the use of a verb at the end of the URL path was the weirdness.
So why is close="no" not possible? It would be the same as leaving it open, I would think (so ignored) ?? It's basically the same call as the others, with an extra (closure) directive. --Hubne 02:56, 9 November 2008 (UTC)

Identifying ordered relations

If ordered relations make it in, I suggest using a new attribute on the relation element (e.g. ordered="yes|no").

  • its absence could indicate that the relation was created before ordering was supported in the API, and that it has not been explicitly set. Clients should not make assumptions either way.
  • new relations should probably default to the "unordered" value for clients which don't support setting the attribute

--Hubne 12:48, 8 November 2008 (UTC)

  • Maybe a tag instead of an attribute? As there will be no difference for the server: all relations might be ordered (if it makes it in). --Matt 13:46, 8 November 2008 (UTC)
Not sure why you are preferring element/tag over attribute. It's an aesthetic thing, ultimately, but I consider it metadata to the contents, so i like attributes for this. --Hubne 03:18, 9 November 2008 (UTC)
  • This is not necessary, because any existing relations would have already taken into account that relations are unordered. The only way it could be a problem is if the definition of existing relations were to change to make the order significant. And even then, it would not be terribly difficult to use a script to fix up any existing relations after putting the ordered relation into use. --Karl Newman 18:42, 8 November 2008 (UTC)
So you are saying there's no need to distinguish between explicitly unordered and legacy unordered? You may be right. I suppose if not sure I prefer to err on the side of caution, though. (I'm a little confused who you are talking to.) --Hubne 03:18, 9 November 2008 (UTC)

XML namespace

The XML vocabularies should have XML namespaces to make working with them easier. The easiest solution would be to choose good URLs in a tree off (For example, xmlns="".) There's no need for the URLs to even resolve, though it would be useful to do so when we can, and use it to describe the XML documents, both formally and informally.

--Hubne 12:48, 8 November 2008 (UTC)

Reliably identifying users

The description says "User id for anonymous users will not be visible.". Anonymous users ? I tought we all agreed in the past that anonymous users would not be possible anymore in OSM... -- Pieren 21:43, 8 November 2008 (UTC)

Good pickup. I thought that was weird, too, but let it go. --Hubne 02:49, 9 November 2008 (UTC)

Downloading properties of relations without members

I've scanned the page but I can't see a method to download just the properties of a relation. Why is that? I'd say it would make it a lot easier on data transmitting if you don't need to download and upload entire relations with their members. If you're programming and want to edit some vector, you also don't make a complete copy of it in a local function, add some item in there and copy that to the original vector again. You'd just call a function "add item bla to vector". But I can't see anything here like "add way X to relation Y", just "relation Y is now (a,b,c,d,e,...,X)". I can understand you may want to do that with ways, but with relations it just looks very bad to me. If your relation has 5000 members and there's just one in the part of the data you're looking at, there's absolutely no reason why you need to know the other 4999. --Eimai 19:03, 18 November 2008 (UTC)

Getting historic ways

AFAICT, there is no easy way of getting a full version of a historic way - even the historic XML only states node IDs and not versions, so it'd be hard to lookup historic versions of the nodes. So to recap:

  • Add versions to nd members of ways (particularly history)
  • Consider /api/0.6/way/#id/#version/full to return a full historic version of a way.

My reasoning behind this is so we could add maps to each change in the browse section of the site - so we can get a quick visual change history. --Thomas Wood 21:29, 26 November 2008 (UTC)

The problem is that a way can have many versions of a node, for example by moving a node that is part of a way. It however won't touch the way. Hence the way won't get a new version. Smsm1 16:04, 11 December 2008 (UTC)

Use relation to define download area

I know that it is probably too late to add features to 0.6, so maybe this ends up on ideas for 0.7, but I'll try anyway. Could it be possible to use a boundary relation to define a download area? That way I can download my entire municipal before editing on it, or even download predefined areas for making routing maps. This shouldn't give much more strain in the server as when people want to download such an area today they tend to do several downloads with largely over leaping areas. The boundary relation gives a predefined area of interest, and it should not be much of a problem to restrict the data to what is contained within the boundary. It seems also that 0.6 allows for poligonic shaped download areas, so it should also support this. --Skippern 10:57, 13 December 2008 (UTC)

Getting deleted ways?

Would there be added functionality to querying for deleted ways, given a bbox?

Something that is available in Potlatch with current API, but it is currently not part of the public 0.5 API.

--Bilbo 17:30, 8 February 2009 (UTC)

Restrict a GET to certain node type(s)?

Is it possible to restrict a GET to only return certain node types? For example, to download XML for all peaks (hills, mountains) over a large area. Is it currently necessary to download _all_ elements for the area (in quarter-degree squares) and parse the huge XML to just find the node types of interest? Eric2 18:12, 26 August 2009 (UTC)

XAPI can answer such queries. Alv 07:48, 27 August 2009 (UTC)
Great, thanks for the tip, I probably should have seen that already but that's perfect! Eric2 12:53, 27 August 2009 (UTC)

Bash example


API URL wrong

It might be better to include exactly the url needed by josm or other tools? (josm need the additional /api in the directory path) - User:Larsf 20:56, 30 November 2009

That might have been easier and I have no objections but now the /api part is documented in each call by itself e.g. "Create: PUT /api/0.6/[node|way|relation]/create". So if you want to change it remember to change these too --LarsF 15:20, 1 December 2009 (UTC)
Hmmm. LarsF talking to Larsf. confusing.
It looks like Larsf came here searching for 'API', when actually he was after JOSM help, and this page specifically. Incidentally I think the JOSM developers should make it easier to "reset to default" somehow on that particular preference setting.
-- Harry Wood 16:15, 1 December 2009 (UTC)

Link to ruby datetime function

The link to ruby's datetime function is dead (in changesets). I'm not a ruby person myself, but is the to_datetime method of this class meant?

Is this API 0.6 documentation old ?

After a few tests on the deployed API 0.6 at I found a few little differences with what the documentation here says. I am not sure If I should update the documentation acordingly or if I should create a new page to express the few differences ? I'll choose to update this documentation but feel free to revert my changes if that is not what this documentation is for. sletuffe 12:41, 28 March 2012 (BST)

Well, after carefull reading, the documentation is ok, Maybe it was me not understanding some sentences. I've re-worded them just a bit sletuffe 13:35, 28 March 2012 (BST)
Missing Error code documentation for GPX upload API --Skippern (talk) 19:07, 27 March 2016 (UTC)

Timestamp in osmChange uploads

The timestamp attribute is required for osmChange payloads to changeset/x/upload calls, but doesn't actually get read - JOSM just gives you some date in 2007. Should this be noted? Tmcw 22:03, 19 November 2012 (UTC)

I had a look at the code and tests, and you're right - it doesn't get read. I can't see anywhere that requires it, either. Do you have an example where an upload is failing due to the lack of a timestamp that I can include in the test suite? --Matt 14:55, 22 November 2012 (UTC)

User-Details in JSON?

Is there a way to get the user-details of the logged in user as a json string? api/0.6/user/details.json sends the data xml-formated... --CMartin (talk) 16:36, 15 November 2013 (UTC)

Map Notes API

We have the parameter closed to limit retrieval to the specified number of days.

It would be useful to have two additional parameters: age to similarly limit retrieval to bugs created in the specified number of days (eg 30) and updated to limit retrieval to bugs created or updated in the specified number of days. These could be used either together with closed (to include closed bugs meeting the specified age, or to suppress them) or on its own (to include closed bugs with the default 7 day limit).

In the results, we presently have date_created but I didn't see a date_updated -- this would be useful to add. --Harg (talk) 11:01, 14 September 2016 (UTC)

Last modified time can be found by looking at the date of the last comment. Every note action creates a new comment element, even if there is no user-supplied comment text. ToeBee (talk) 14:33, 14 September 2016 (UTC)