Talk:API v0.6

From OpenStreetMap Wiki
Jump to navigation Jump to 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)

Editors

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: 

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

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

e.g. 

PUT /api/0.6/node/create

over 

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 http://example.com/api/0.6/changeset/create which is clearly not what is intended here. Instead this request creates a new resource with a URL like http://example.com/api/0.6/changeset/12345 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).

Current: 

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

Suggest: 

PUT /api/0.6/changeset/#id

with payload starting with: 

<osm>
  <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 openstreetmap.org. (For example, xmlns="http://openstreetmap.org/schemas/osmChange".) 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

ZoneImport

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 http://api.openstreetmap.org/api 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)

Resolved: added in September 2020 Mateusz Konieczny (talk) 21:29, 19 November 2020 (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)

HTTPS

Mention if plans are in place to employ HTTPS, as user credentials are being transmitted. Jidanni (talk) 14:15, 24 August 2017 (UTC)

Resolved: it is now https only Mateusz Konieczny (talk) 21:28, 19 November 2020 (UTC)

Recursive identification of object parents should be available in RESTful calls

The point of the OSM API, as specified in the terms of use, is as follows:

https://operations.osmfoundation.org/policies/api/ : The editing API is provided in order to edit the map data, not for read-only purposes or projects.

When I download objects in a bbox or area as defined by coordinates, I will recursively receive parents of objects, specifically:

  • All ways that a node belongs to (and that way's parents if any)
  • All relations that a node belongs to (and that relation's parents if any)
  • All relations that a way belongs to (and that relation's parents if any)
  • All relations that a relation belongs to (and that relation's parents if any)
  • All parents of a relation's objects, whatever they may be

There is a valid editing use case for selectively downloading objects and editing them. (For example, in JOSM, this can be done using 'Download object' https://josm.openstreetmap.de/wiki/Help/Action/DownloadObject or using the 'Download using Overpass API' section in the Download dialogs https://wiki.openstreetmap.org/wiki/Overpass_API/Sparse_Editing . http://level0.osmz.ru/ does this in text, but again does not download parents in this way, because there's no easy way to so.) I can download the parents of an object, but that does not check for parents of parents. Just "downloading an object" on its own - which is a standard function in JOSM - doesn't safely allow me to edit it without going through a tedious process to ensure I'm not going to hit an object dependency conflict.

There is no clean way, at (explicit) object download time, to say 'I want to download way 1000000. I want the way itself, all 150 of its nodes, all parents of those 150 nodes, and all parents of those parents until I run out of parents'. It so happens that when you download an area that contains a way, this "happens", and quickly, but if you do this at the object level, you must make 150 calls to the API after the fact to check parents of a way's children nodes one at a time - which still doesn't check for parents of parents of those nodes.

There should be a call that makes this possible without hitting the API to check parents one object at a time. It probably would be best to make this a new RESTful query, since existing calls already are heavily used as they are for area downloads. The point is that 'just downloading a way without knowing its nodes' parents', in the case where I only download "that object", isn't actually useful for editing because I still need to know parents. Some RESTful queries would want parents returned recursively, and others would not, depending on the download. Skybunny (talk)

Overpass api has a „complete“ statement which just landed in release 0.7.55. Documentation and further details to follow soon. Mmd (talk) 15:41, 7 May 2018 (UTC)
If and when that exists somewhere, please reply, because I'll then log a feature request against JOSM to make 'Get dependencies/Complete/WhateverItIsCalled, against "Complete"' an option at Overpass API download time. Thanks! Skybunny (talk) 15:53, 7 May 2018 (UTC)
It's documented since today: https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#The_block_statement_complete Mmd (talk) 08:14, 8 May 2018 (UTC)
Thank you! I appended the blog entry for this, https://dev.overpass-api.de/blog/loop_and_group.html , to the 9 year old JOSM ticket https://josm.openstreetmap.de/ticket/4142 . Skybunny (talk) 17:42, 16 May 2018 (UTC)

CORS error

I have a map that displays notes and has been working fine up to today using leaflet.js in Firefox. Today I'm getting several errors reported in FF 60.0 console, including this:

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at http://api.openstreetmap.org/api/0.6/notes.json?closed=10&limit=200&bbox=-0.04961457444248102,51.535636847229284,-0.020725425557518985,51.55360315277072. (Reason: CORS header 'Access-Control-Allow-Origin' missing).

Has anything changed? As I understand it, the CORS header has to be installed on the server -- it's not something I can add to the client.

Harg (talk) 11:18, 16 May 2018 (UTC)

Note that this is *not* an issue tracker, you need to create your issue here: https://github.com/openstreetmap/operations/issues
Try accessing the API per HTTPS. HTTP got disabled a couple of hours ago. --Michi (talk) 19:47, 16 May 2018 (UTC)

Swagger definition

Is there a Swagger definition available that allows for the automatic generation of clients?

If not: - Are there plans to create one? - How would one go about if they wanted to create one and make it available to the community?

Thanks in advance for your input! 666nQWv342323tJ9 (talk) 11:12, 8 March 2020 (UTC)

I'm putting some effort to making a OAS document for the current version 0.6. my progress can be found here jonycoo (talk) 22:40, 08 May 2022 (UTC)

Is the semantic version number incorrect?

As stated at the top of this page, semantic versioning isn't used for various reasons. However it can be "thought of" as v0.6.6

This seems incorrect because with the 7 listed updates to the v0.6 API, wouldn't we be at v0.6.7?

Makes sense, I changed it (and moved semantic versioning section to the end) Mateusz Konieczny (talk) 21:28, 19 November 2020 (UTC)
Thanks :) GoodClover (talk) 21:36, 19 November 2020 (UTC)

Changeset bounding box computation

I have a few clarification questions:

  • What happens when a relation is created or deleted?
  • What happens when a member role is modified? --TimSC (talk) 11:28, 8 January 2021 (UTC)

Simpler section anchors

Simple and clean section anchors would facilitate linking specific sections from other articles ... there are currently two problems with that:

  1. Some section headings are duplicate (under General information as well as under API calls), so e.g. there is:
    (the _2 is added automatically by MediaWiki since the heading is duplicate)
  2. Section headings include the API endpoint e.g. API v0.6#Hide changeset comment: POST /api/0.6/changeset/comment/#comment_id/hide is quite unwieldy.

The former could be resolved by turning the Elements, Changesets & Tags headings under General information into definition lists, so e.g:

Elements
There are API calls to create, read, update and delete the three basic elements that make up the map data for OpenStreetMap. They each return or expect the data for the elements in a XML format.
Changesets
Every modification of one or more of the elements has to reference an open changeset.
Tags
Every element and changeset may have any number of tags. A tag is a Key-Value pair of Unicode strings of up to 255 full unicode characters (not bytes) each.

The latter could be resolved by moving the URL paths out of the headings.

What do you think about this? --Push-f (talk) 20:41, 29 July 2022 (UTC)

Sections 1.2 Elements, 1.3 Changesets, and 1.4 Tags are really a bit silly, and could be turned into a definition list.
Having the URL path as part as part of the heading is in fact a feature, as it allows you to quickly navigate to the relevant endpoint based on the TOC only. Please don't change this! Mmd (talk) 11:03, 13 August 2022 (UTC)

What is the API call to hide/redact note?

https://wiki.openstreetmap.org/wiki/API_v0.6#Hide_changeset_comment:_POST_/api/0.6/changeset/comment/#comment_id/hide is documented but equivalent for notes is not

It is usable by DWG, not by regular mappers but I am trying to write script for DWG to help with large scale note spam (low quality onosm.org notes in Iran).

Mateusz Konieczny (talk)

[2]. Moderate scale spam can be handled with my note viewer, which has a Hide button in its Interact tool and can hide selected notes. The button is only visible for users with moderator role. --Anton Khorev (talk) 16:08, 3 August 2023 (UTC)

Dead link to date format

"Time format: Anything that this Ruby function will parse" links to 404 page Mateusz Konieczny (talk) 09:30, 27 December 2022 (UTC)

XML headers

Users go through great lengths to strip the XML headers, as the example shows them gone.

But it turns out they didn't need to.

So please show them in that example. Thanks.

They exist for a purpose!

Jidanni (talk) 06:09, 26 February 2023 (UTC)

Clarify the required OAuth2 scopes for a completely functional API

I guess that the required scopes to be able to use the full API 0.6 are:

  • read_prefs
  • write_api
  • read_gpx
  • write_gpx
  • write_notes

I.e., the scopes not needed by any API calls are:

  • write_prefs
  • write_diary".

Is that right? --Jmaspons (talk) 10:10, 30 June 2023 (UTC)

write_prefs is presumably used by put requests for PUT /api/0.6/user/preferences - right? Mateusz Konieczny (talk) 12:14, 30 June 2023 (UTC)
Yes, I missed this and the DELETE calls, as they don't appear in the TOC. --Jmaspons (talk) 17:54, 30 June 2023 (UTC)
Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=Talk:API_v0.6&oldid=2580599"