Ko:API v0.6

API v0.6은 OSM 편집 API의 최신 버전입니다. OSM API는 2009년 4월 17일~21일에 처음으로 개발되었습니다.

이 문서와 OSM API는 2009년 4월부터 계속 확장되고 업데이트되었습니다. 2012년 3월에 작은 변화를 반영한 이후부터 2013년 4월에 Map Notes API를 추가하고, 2016년 1월에 바뀜집합 논의를 추가, 마지막 업데이트한 2018년 7월에 수많은 내부 호환성 변화를 추가했습니다. 의미 있는 변화가 없었기 때문에, 또 버전 숫자를 업데이트한다면 나중에 합리적이지 않은 이유로 큰 숫자를 업데이트해야 하기 때문에 버전 숫자는(작은 숫자라 할지라도) 업데이트되지 않았습니다.

기본 정보

본 API 문서는 RESTful API의 아이디어를 기반으로 제작되었습니다. RESTful API에 대한 더 많은 정보는 위키피디아의 Representational State Transfer 문서에서 확인하실 수 있습니다.

API는 REST 요청을 받는 서버 측의 요소입니다. REST 요청은 HTTP GET, PUT, POST, DELETE 메시지 형식을 취합니다. 주고받는 데이터는 MIME 형식의 "text/xml"와 UTF-8 문자 인코딩을 사용한 XML 형식으로 이루어져야 합니다. 그리고 만약 클라이언트가 압축된 메시지를 처리하는 HTTP "Accept" 헤더를 통해 지시하고 있다면 주고받는 데이터는 압축될 수도 있습니다.

데이터베이스 수정 요청은 HTTP Basic Authorization 또는 OAuth를 통한 인증을 사용합니다. 읽기 요청은 인증을 필요로 하지 않습니다.(이용자의 세부 사항 제외)

예비 Full DTD(제작 및 논의 중).

API v0.6에서의 변경사항

URL + 인증

OSM API는 현재 https://api.openstreetmap.org/ URL로 접근할 수 있습니다.

OSM API를 이용한 자신의 소프트웨어를 테스트할 때에는 반드시 live-api를 사용하는 대신 http://api06.dev.openstreetmap.org/를 사용하는 것을 고려해 보아야 합니다. 라이브 서비스용 계정은 같은 데이터베이스에 있지 않기 때문에, 테스트용으로 아마 새로운 이름과 비밀번호가 필요할 것입니다. 위 페이지에 들어가서 회원가입해 주세요.

데이터를 업데이트하거나, 생성하거나, 삭제하는 요청을 API에 하려면 등록된 이용자가 해야 합니다. HTTP 기본 등록을 사용해서 등록하거나 OAuth를 사용해서 등록할 수 있습니다.

오류 코드

HTTP 상태 코드 400 (Bad request)

만약 API의 cgimap 버전에 접근하고 있다면, OAuth가 "부적절한 OAuth 요청입니다."(Bad OAuth request.)을 반환했을 때 이 오류 코드를 반환할 것입니다.

HTTP 상태 코드 401 (Unauthorized)

로그인을 실패했습니다.

HTTP 상태 코드 403 (Forbidden)

로그인은 성공했지만 이용자가 차단되어 있을 때, 프로그램은 이 메시지(가능하다면 번역문으로)을 출력하고, 최종 사용자 인터페이스로 오류 코드를 표시하고 있다면 openstreetmap.org에 접근하는 쉬운 방법을 제시하고 메시지를 표시할 것입니다.

요소

오픈스트리트맵의 지도 데이터를 구성하는 세 기본 요소를 업데이트하거나, 읽거나, 생성하거나, 삭제하기 위해 API 호출을 할 수 있습니다. API 요청에서는 XML 형식으로 요소의 데이터를 각각 반환하거나 접수합니다.

바뀜집합

요소의 변경 사항은 하나의 열린 바뀜집합에 속해 있어야 합니다.

태그

모든 요소와 바뀜집합은 태그를 가지고 있을 수 있습니다. 태그 하나는 각각 유니코드 문자열(최대 255자, 바이트로 계산하지 않음)로 이루어진 키-값 쌍을 이루고 있습니다.

최대 문자열 길이

현재 API의 실행을 위해서 개체의 키와 값 문자열, 바뀜집합과 환경 설정 태그, 관계 구성원 역할의 길이를 최대 255자로 제한하고 있습니다.

참고: 이 제한은 실제로 255자이며 256자가 아닙니다.

확실히 인증된 이용자

기존 API v0.5는 이용자 이름만 반환했습니다. 이용자들은 언제나 데이터를 업데이트할 수 있었고, 이름 변경을 대비해서까지 역사를 저장하지는 않았습니다. 이는 어느 이용자가 변경 사항을 만들었는지 확실히 식별할 방법이 없다는 것을 의미합니다. API v0.6은 표시되는 이름에 더해서 숫자로 이루어진 이용자의 계정 ID를 포함하고 있습니다. 예를 들어 다음과 같이 나타낼 수 있습니다.

<node id="68" ... user="fred" uid="123"/>

이는 여전히 이용자가 자신의 편집 사항을 공개적으로 밝히길 요구하고 있습니다. 기존에 익명으로 편집한 이용자의 이용자 ID는 보이지 않을 것입니다. OSM 재단 위원회의 권장 사항에 따라서, 익명 편집은 이제 불가능합니다.

버전 숫자·낙관적인 보안

planet 덤프와 차이점(diff) 요소, API 호출은 각 '노드', '길', '관계'별로 version 속성을 반환합니다.

<node id="68" ... version="12"/>

이 버전 숫자들은 '낙관적인 보안(optimistic locking)'에 사용됩니다. 개체의 새로운 버전을 업로드하려면 클라이언트가 변경할 개체의 현재 버전을 제공해야 합니다. 클라이언트가 제공한 버전이 서버의 현재 버전과 일치하지 않다면 오류를 반환합니다(HTTP 상태 코드 409: Conflict). 이는 데이터를 업데이트하는 기능을 가진 어떤 클라이언트든지 기존 개체 데이터의 버전 숫자를 저장해야 한다는 것을 의미합니다. 바뀜집합 한 개 안에서 개체 하나를 여러 번 업데이트할 수 있고, 그때마다 업데이트한 개체의 버전 숫자가 증가하기 때문에 바뀜집합 하나에 속한 요소 하나에 '역사에 표시되는 버전'이 여러 개 존재할 수 있습니다.

추가로, 클라이언트는 현재 요소 하나의 특정 버전을 요청할 수 있습니다.

버전 숫자는 항상 1로 시작되며, 요소가 한 번 변화할 때마다 1씩 증가합니다. 하지만 클라이언트는 반드시 요소 하나를 업데이트할 때마다 숫자를 1씩 증가시켜야 할 필요는 없습니다. 대신 서버와 통신할 때는 버전 숫자를 1 늘려서 전달해야 합니다.

XML 형식

서버에서 오는 모든 XML 응답은 일부 예외(차이점(diff) 업로드나 바뀜집합 다운로드)를 제외하고 <osm> 요소로 싸여 있습니다. 이후의 예시 대부분에서는 다음 요소를 빼고 설명할 것입니다.

<osm version="0.6" generator="OpenStreetMap server">
  ...
  ...
</osm>

API에게 하는 모든 요청은 <osm> 요소로 둘러싸여야 합니다. 단, version과 generator 속성은 뺄 수 있습니다.

올바른 HTTP 메서드 위장하기

많은 API 호출은 PUT과 DELETE 메서드를 사용하는데, 당신이 사용하고 있는 클라이언트 HTTP 스택에서 이 메서드를 사용할 수 없을 수도 있습니다. 당신은 전체(full) HTTP 구현이 되지 않은 이 스택을 제작한 제작자에게 불평을 제기할 수도 있을 것입니다. 만약 이 스택이 잘 작동하지 않는다면, X_HTTP_METHOD_OVERRIDE 헤더를 위장하고 싶은 메서드의 값과 같이 넣는 제2의 해결책이 있습니다. 예를 들어, PUT 핸들러를 사용하지 않고 cURL이 POST를 하게 하고 싶으면, 다음과 같이 하면 됩니다.

curl -v -v -d @changeset.osm -H "X_HTTP_METHOD_OVERRIDE: PUT" "http://server/api/0.6/changeset/create"

API 호출

다양한 방법

기능: GET /api/capabilities

이 API 호출이 현재 API의 제한 사항과 기능에 관한 정보를 제공하도록 하는 것을 의미합니다.

응답

XML 문서 반환(컨텐츠 유형 text/xml)

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
  <api>
    <version minimum="0.6" maximum="0.6"/>
    <area maximum="0.25"/>
    <note_area maximum="25"/>
    <tracepoints per_page="5000"/>
    <waynodes maximum="2000"/>
    <changesets maximum_elements="10000"/>
    <timeout seconds="300"/>
    <status database="online" api="online" gpx="online"/>
  </api>
  <policy>
    <imagery>
      <blacklist regex=".*\.google(apis)?\..*/(vt|kh)[\?/].*([xyz]=.*){3}.*"/>
      <blacklist regex="http://xdworld\.vworld\.kr:8080/.*"/>
      <blacklist regex=".*\.here\.com[/:].*"/>
    </imagery>
  </policy>
</osm>

실제로 반환되는 값은 언제나 변경될 수 있고, 이 XML 문서는 한 예시일 뿐이라는 점을 참고해 주세요.

• 저작권(copyright), 속성(attribution), 라이선스(license): 법적인 정보를 나타내고 있습니다.

API:

• version에서 minimum과 maximum은 서버가 받을 API 호출 버전입니다.
• area에서 maximum은 API 호출이 질의할 수 있는 최대 영역을 평방도(square degree)로 나타낸 것입니다.
• tracepoints에서 per_page는 단일 GPS 궤적에 나타낼 수 있는 점 개수의 최댓값입니다(경우에 따라 부정확).
• waypoints에서 maximum은 길 하나가 포함할 수 있는 노드 개수의 최댓값입니다.
• changesets에서 maximum은 바뀜집합 하나에 들어 있는 노드, 길, 관계의 개수를 모두 합한 개수의 최댓값입니다.
• status 요소에서 데이터베이스, API, GPX API에 각각 'online' 또는 'readonly', 'offline' 중 하나를 반환합니다. 데이터베이스 난은 정보를 제공하는 칸이며, API와 GPX-API 난은 클라이언트가 작업하기 위해 읽기 및 쓰기 요청('online'), 읽기 요청만('readonly'), 또는 요청 없음('offline') 중 어느 것을 요구할지 여부를 나타냅니다.

정책:

• imagery blacklist에는 저작권 문제로 OSM에 사용할 수 없는 모든 항공 사진과 지도 출처를 나열합니다. 편집자들은 이 자료들을 배경 레이어로 사용할 수 없습니다.

참고

• URL에는 버전이 없다는 것을 참고하세요. 편의상의 이유로, 서버는 요청 /api/0.6/capabilities를 지원하며, 클라이언트는 모든 요청에 같은 URL 접두사 http:/.../api/0.6을 사용할 수 있습니다.
• 요소와 관계 구성원의 ID는 현재 64비트 정수형으로 제한되어 있습니다. 이는 문제가 되지 않을 것입니다. :-)

테두리 상자로 지도 데이터 가져오기: GET /api/0.6/map

GET /api/0.6/map?bbox=left,bottom,right,top

이 명령어는 다음 요소들을 반환합니다.

• 주어진 테두리 상자 안에 있는 모든 노드와 이 노드를 하나라도 포함하는 모든 관계
• 주어진 테두리 상자 안에 있는 노드를 하나라도 참조하는 모든 길과 이 길을 하나라도 포함하는 모든 관계, 이 길에 속하는 모든 노드(테두리 상자 바깥의 노드도 포함)
• 위 규칙으로 반환된 모든 요소를 하나라도 포함하는 모든 관계(재귀적으로 적용하지 않습니다. 아래에 있는 설명을 참조하세요.)

• left는 테두리 상자 왼쪽 테두리의 경도입니다.
• bottom은 테두리 상자 아래쪽 테두리의 위도입니다.
• right는 테두리 상자 오른쪽 테두리의 경도입니다.
• top은 테두리 상자 위쪽 테두리의 위도입니다.

이 명령어는 앞서 언급한 노드와 길을 포함하는 관계를 반환하지만, 역은 성립하지 않는다는 점을 알아 두세요. 즉 테두리 상자 안의 관계에 속하는 노드와 길 전체를 반환하지는 않습니다(반환할 필요가 없습니다). 이는 비합리적으로 큰 결과 집합을 반환하는 것을 막아 줍니다. 예를 들어, 다음 상황을 상상해 보세요.

• 영국의 모든 노드가 속한 "England"라는 이름의 관계가 있습니다.
• 영국의 극히 일부분을 수정하기 위해 테두리 상자를 생성할 때 이 노드, 길, 관계를 전부 가져옵니다.

역이 성립한다면 "England" 관계에 의해 영국 전체의 노드, 길, 관계를 가져올 수도 있는 반면에, 역이 성립하지 않는다면 영국 '전체'의 노드와 길을 포함하지 '않을' 것입니다. 원한다면, "England" 관계에 속한 노드와 길을 개개별 ID를 통해 가져올 수 있습니다.

또한 테두리 상자 안으로 길이 들어오지만 테두리 상자 안에 노드가 없는 길은 반환되지 않는다는 점을 알아 두세요.

오류 코드

HTTP 오류 코드 400 (Bad Request)

노드·길·관계 제한을 초과했을 때, 특히 호출이 50,000개가 넘는 노드를 반환하려 할 때 발생합니다. 위에서 이 코드가 뜨는 다른 경우도 참조하세요.

HTTP 오류 코드 509 (Bandwidth Limit Exceeded)

"오류: 너무 많은 데이터를 다운로드했습니다. 나중에 다시 시도해 주세요."(Error: You have downloaded too much data. Please try again later.) 개발자 FAQ를 참조하세요.

권한 가져오기: GET /api/0.6/permissions

현재 API에 연결할 수 있도록 허가된 권한을 반환합니다.

• 만약 API 클라이언트가 등록되지 않았다면, 권한 목록이 빈 목록으로 반환됩니다.
• 만약 API 클라이언트가 Basic Auth를 사용한다면, 권한 목록에 모든 권한이 포함됩니다.
• 만약 API 클라이언트가 OAuth를 사용한다면, 권한 목록에 실제로 이용자가 허가한 권한만이 포함됩니다.

GET /api/0.6/permissions

응답

권한 태그(컨텐츠 유형 text/xml)를 포함하는 단일 권한 요소를 반환

 <?xml version="1.0" encoding="UTF-8"?>
 <osm version="0.6" generator="OpenStreetMap server">
   <permissions>
     <permission name="allow_read_prefs"/>
     ...
     <permission name="allow_read_gpx"/>
     <permission name="allow_write_gpx"/>
   </permissions>
 </osm>
 

참고

현재 다음 권한들은 결과에 나타날 수 있으며, OAuth 프로그램 정의에 있는 권한들과 직접적으로 대응합니다.

• allow_read_prefs (이용자 환경설정 읽기)
• allow_write_prefs (이용자 환경설정 수정)
• allow_write_diary (일기 항목 생성, 댓글 달기, 친구 사귀기)
• allow_write_api (지도 수정)
• allow_read_gpx (비공개 GPS 궤적 읽기)
• allow_write_gpx (GPS 궤적 업로드)
• allow_write_notes (참고 수정)

바뀜집합

연관된 변경 사항을 더 쉽게 식별하기 위해 바뀜집합이라는 개념을 도입했습니다. 표준 OSM 요소를 변경한 모든 내역은 열린 바뀜집합에 속해 있어야 합니다. 바뀜집합에는 다른 요소들처럼 태그를 포함할 수도 있습니다. 바뀜집합에 권장되는 태그로는 comment=* 키가 있습니다. 이 키의 값에는 사람이 읽을 수 있는 설명을 바뀜집합을 통해서 변경할 사항을 잘 나타낼 수 있도록 짧게 적습니다. 버전 관리 시스템의 접수 메시지처럼 적으면 됩니다. 새로운 바뀜집합을 언제든 열 수 있고, API 호출 여러 개가 바뀜집합 하나를 가리킬 수도 있습니다. 이 때문에 서버는 바뀜집합이 어디에서 끝나고 어디서부터 새로운 바뀜집합을 열어야 하는지 알 수 없기 때문에 바뀜집합은 수동으로 닫을 수 있습니다. To avoid stale open changesets a mechanism is implemented to automatically close changesets upon one of the following three conditions:

• More than 10,000 edits on a single changeset See more specific limits
• The changeset has been open for more than 24 hours
• There have been no changes/API calls related to a changeset in 1 hour (i.e., idle timeout)

Changesets are specifically not atomic - elements added within a changeset will be visible to other users before the changeset is closed. Given how many changes might be uploaded in one step it's not feasible. Instead optimistic locking is used as described above. Anything submitted to the server in a single request will be considered atomically. To achieve transactionality for multiple changes there is the new diff upload API call.

Changesets facilitate the implementation of rollbacks. By providing insight into the changes committed by a single person it becomes easier to identify the changes made, rather than just rolling back a whole region. Direct support for rollback will not be in the API, instead they will be a form of reverse merging, where client can download the changeset, examine the changes and then manipulate the API to obtain the desired results. Rolling back a changeset can be be an extremely complex process especially if the rollback conflicts with other changes made in the mean time; we expect (hope) that in time, expert applications will be created that make rollback on various levels available to the average user.

To support easier usage, the server stores a bounding box for each changeset and allows users to query changesets in an area. This will be calculated by the server, since it needs to look up the relevant nodes anyway. Client should note that if people make many small changes in a large area they will be easily matched. In this case clients should examine the changeset directly to see if it truly overlaps. A client can expand the bounding box manually using an API call, which can be useful when the client already knows the full extent of the data it is about to upload.

It is not possible to delete changesets at the moment, even if they don't contain any changes. The server may at a later time delete changesets which are closed and which do not contain any changes. This is not yet implemented.

Bounding box computation

This is how the API computes the bounding box associated with a changeset:

• Nodes: Any change to a node, including deletion, adds the node's old and new location to the bbox.
• Ways: Any change to a way, including deletion, adds all of the way's nodes to the bbox.
• Relations:

• adding or removing nodes or ways from a relation causes them to be added to the changeset bounding box.
• adding a relation member or changing tag values causes all node and way members to be added to the bounding box.
• this is similar to how the map call does things and is reasonable on the assumption that adding or removing members doesn't materially change the rest of the relation.

As an optimisation the server will create a buffer slightly larger than the objects to avoid having to update the bounding box too often. Thus a changeset may have a different bounding box than its reversion, and the distance between bounding box and the next node may not be constant for all four directions.

Create: PUT /api/0.6/changeset/create

The payload of a changeset creation request has to be one or more changeset elements optionally including an arbitrary number of tags.

<osm>
  <changeset>
    <tag k="created_by" v="JOSM 1.61"/>
    <tag k="comment" v="Just adding some streetnames"/>
    ...
  </changeset>
  ...
</osm>

If there are multiple changeset elements in the XML the tags from all of them are used, later ones overriding the earlier ones in case of duplicate keys.

Response

The ID of the newly created changeset with a content type of text/plain

Error codes

HTTP status code 400 (Bad Request)

When there are errors parsing the XML

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP PUT request

Notes

Any number of possibly editor-specific, tags are allowed. An editor might, for example, automatically include information about which background image was used, or even a bit of internal state information that will make it easier to revisit the changeset with the same editor later, etc.

Clients should include a created_by=* tag. Clients are advised to make sure that a comment=* is present, which the user has entered. It is optional at the moment but this might change in later API versions. Clients should not automatically generate the comment tag, as this tag is for the end-user to describe their changes. Clients may add any other tags as they see fit.

Read: GET /api/0.6/changeset/#id?include_discussion=true

Returns the changeset with the given id in OSM-XML format.

<osm>
  <changeset id="10" user="fred" uid="123" created_at="2008-11-08T19:07:39+01:00" open="true" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101">
    <tag k="created_by" v="JOSM 1.61"/>
    <tag k="comment" v="Just adding some streetnames"/>
    ...
    <discussion>
     <comment date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
       <text>Did you verify those street names?</text>
     </comment>
     <comment date="2015-01-01T18:58:03Z" uid="123" user="fred">
       <text>sure!</text>
     </comment>
     ...
   </discussion>
 </changeset>
</osm>

Parameters

id

The id of the changeset to retrieve

(new) include_discussion

Indicates whether the result should contain the changeset discussion or not. If this parameter is set to anything, the discussion is returned. If it is empty or omitted, the discussion will not be in the result.

Response

Returns the single changeset element containing the changeset tags with a content type of text/xml

Error codes

HTTP status code 404 (Not Found)

When no changeset with the given id could be found

Notes

• The uid might not be available for changesets auto generated by the API v0.5 to API v0.6 transition?
• The bounding box attributes will be missing for an empty changeset.
• The changeset bounding box is a rectangle that contains the bounding boxes of all objects changed in this changeset. It is not necessarily the smallest possible rectangle that does so.
• This API call only returns information about the changeset itself but not the actual changes made to elements in this changeset. To access this information use the download API call.

Update: PUT /api/0.6/changeset/#id

For updating tags on the changeset, e.g. changeset comment=foo.

Payload should be an OSM document containing the new version of a single changeset. Bounding box, update time and other attributes are ignored and cannot be updated by this method. Only those tags provided in this call remain in the changeset object. For updating the bounding box see the expand_bbox method.

<osm>
  <changeset>
    <tag k="comment" v="Just adding some streetnames and a restaurant"/>
  </changeset>
</osm>

Parameters

id

The id of the changeset to update. The user issuing this API call has to be the same that created the changeset

Response

An OSM document containing the new version of the changeset with a content type of text/xml

Error codes

HTTP status code 400 (Bad Request)

When there are errors parsing the XML

HTTP status code 404 (Not Found)

When no changeset with the given id could be found

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP PUT request

HTTP status code 409 (Conflict) - text/plain

If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned

Or if the user trying to update the changeset is not the same as the one that created it

Notes

Unchanged tags have to be repeated in order to not be deleted.

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

Closes a changeset. A changeset may already have been closed without the owner issuing this API call. In this case an error code is returned.

Parameters

id

The id of the changeset to close. The user issuing this API call has to be the same that created the changeset.

Response

Nothing is returned upon successful closing of a changeset (HTTP status code 200)

Error codes

HTTP status code 404 (Not Found)

When no changeset with the given id could be found

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP PUT request

HTTP status code 409 (Conflict) - text/plain

If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned

Or if the user trying to update the changeset is not the same as the one that created it

Download: GET /api/0.6/changeset/#id/download

Returns the OsmChange document describing all changes associated with the changeset.

Parameters

id

The id of the changeset for which the OsmChange is requested.

Response

The OsmChange XML with a content type of text/xml.

Error codes

HTTP status code 404 (Not Found)

When no changeset with the given id could be found

Notes

• The result of calling this may change as long as the changeset is open.
• The elements in the OsmChange are sorted by timestamp and version number.

Expand Bounding Box: POST /api/0.6/changeset/#id/expand_bbox

POSTing a XML document containing node elements (these node elements have nothing to do with the Nodes mentioned elsewhere in this page, they are merely a container for lat and lon attributes) that are to this location will cause the bounding box of the changeset to expand to exactly the smallest containing rectangle of the points given and the bounding box automatically calculated by the API. So this call can only increase the size of the bounding box and later additions to the changeset may override the expanded bounding box.

The input document should look like this:

<osm>
  <node lat=".." lon=".."/>
  <node lat=".." lon=".."/>
  ...
</osm>

The osm element may contain other elements than node, but these are ignored. The node element may contain other attributes (including id) than lat and lon, but these are ignored as well.

This call is supported to give editors the chance to expand the bounding box that the API automatically computes for the changeset. There are cases where the editor will have extra knowledge that make it advisable to flag a larger area as changed than the API would guess from the changes alone. This call may also be used before uploading a large number of changes as a hint for the server which area will be affected.

Parameters

id

The id of the changeset for which the OsmChange is requested.

Response

Returns the updated changeset containing with a content type of text/xml.

Error codes

HTTP status code 404 (Not Found)

When no changeset with the given id could be found

HTTP status code 409 (Conflict) - text/plain

If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned

Or if the user trying to update the changeset is not the same as the one that created it

Notes

• Issuing an expand_bbox call before a large chunk of changes is uploaded has no impact on the runtime of the upload itself.
• As the reuse of node as a XML element name is confusing and the format of this call might change in a later API version.

Query: GET /api/0.6/changesets

This is an API method for querying changesets. It supports querying by different criteria.

Where multiple queries are given the result will be those which match all of the requirements. The contents of the returned document are the changesets and their tags. To get the full set of changes associated with a changeset, use the download method on each changeset ID individually.

Modification and extension of the basic queries above may be required to support rollback and other uses we find for changesets.

Parameters

bbox=min_lon,min_lat,max_lon,max_lat (W,S,E,N)

Find changesets within the given bounding box

user=#uid or display_name=#name

Find changesets by the user with the given user id or display name. Providing both is an error.

time=T1

Find changesets closed after T1

time=T1,T2

Find changesets that were closed after T1 and created before T2. In other words, any changesets that were open at some time during the given time range T1 to T2.

open=true

Only finds changesets that are still open but excludes changesets that are closed or have reached the element limit for a changeset (50.000 at the moment)

closed=true

Only finds changesets that are closed or have reached the element limit

changesets=#cid{,#cid}

Finds changesets with the specified ids (since 2013-12-05)

Time format: Anything that this Ruby function will parse. The default str is ’-4712-01-01T00:00:00+00:00’; this is Julian Day Number day 0.

Response

Returns a list of all changeset ordered by creation date. The <osm> element may be empty if there were no results for the query. The response is send with a content type of text/xml.

Error codes

HTTP status code 400 (Bad Request) - text/plain

On misformed parameters. A text message explaining the error is returned. In particular, trying to provide both the UID and display name as user query parameters will result in this error.

HTTP status code 404 (Not Found)

When no user with the given uid or display_name could be found.

Notes

• Only changesets by public users are returned.
• Returns at most 100 changesets

Diff upload: POST /api/0.6/changeset/#id/upload

With this API call files in the OsmChange format can be uploaded to the server. This is guaranteed to be running in a transaction. So either all the changes are applied or none.

To upload an OSC file it has to conform to the OsmChange specification with the following differences:

• each element must carry a changeset and a version attribute, except when you are creating an element where the version is not required as the server sets that for you. The changeset must be the same as the changeset ID being uploaded to.

• a <delete> block in the OsmChange document may have an if-unused attribute (the value of which is ignored). If this attribute is present, then the delete operation(s) in this block are conditional and will only be executed if the object to be deleted is not used by another object. Without the if-unused, such a situation would lead to an error, and the whole diff upload would fail. Setting the attribute will also cause deletions of already deleted objects to not generate an error.

• OsmChange documents generally have user and uid attributes on each element. These are not required in the document uploaded to the API.

Parameters

id

The ID of the changeset this diff belongs to.

POST data

The OsmChange file data

Response

If a diff is successfully applied a XML (content type text/xml) is returned in the following format

<diffResult generator="OpenStreetMap Server" version="0.6">
  <node|way|relation old_id="#" new_id="#" new_version="#"/>
  ...
</diffResult>

with one element for every element in the upload. Note that this can be counter-intuitive when the same element has appeared multiple times in the input then it will appear multiple times in the output.

Attribute	create	modify	delete
old_id	same as uploaded element.
new_id	new ID	same as uploaded	not present
new_version	new version		not present

Error codes

HTTP status code 400 (Bad Request) - text/plain

When there are errors parsing the XML. A text message explaining the error is returned.

When an placeholder ID is missing or not unique

HTTP status code 404 (Not Found)

When no changeset with the given id could be found

Or when the diff contains elements where the given id could be found

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP POST request

HTTP status code 409 (Conflict) - text/plain

If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned

If, while uploading, the max. size of the changeset is exceeded. A message with the format "The changeset #id was closed at #closed_at." is returned

Or if the user trying to update the changeset is not the same as the one that created it

Or if the diff contains elements with changeset IDs which don't match the changeset ID that the diff was uploaded to

Or any of the error messages that could occur as a result of a create, update or delete operation for one of the elements

Other status codes

Any of the error codes and associated messages that could occur as a result of a create, update or delete operation for one of the elements

See the according sections in this page

Notes

• Processing stops at the first error, so if there are multiple conflicts in one diff upload, only the first problem is reported.
• There is currently no limit in the diff size but this will probably be changed later.

Changeset summary

The procedure for successful creation of a changeset is summarized in the following picture:

Changeset discussion

(new)

This is a new featured added to the website in November 2014 (See blog)

Comment: POST /api/0.6/changeset/#id/comment

Add a comment to a changeset. The changeset must be closed.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/comment (example)
Return type: application/xml

This request needs to be done as an authenticated user.

Parameters

text

The comment text. The content type is "application/x-www-form-urlencoded".

Error codes

HTTP status code 400 (Bad Request)

if the text field was not present

HTTP status code 409 (Conflict)

The changeset is not closed

Subscribe: POST /api/0.6/changeset/#id/subscribe

Subscribe to the discussion of a changeset to receive notifications for new comments.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/subscribe (example)
Return type: application/xml

This request needs to be done as an authenticated user.

Error codes

HTTP status code 409 (Conflict)

if the user is already subscribed to this changeset

Unsubscribe: POST /api/0.6/changeset/#id/unsubscribe

Unsubscribe from the discussion of a changeset to stop receiving notifications.

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/unsubscribe (example)
Return type: application/xml

This request needs to be done as an authenticated user.

Error codes

HTTP status code 404 (Not Found)

if the user is not subscribed to this changeset

Elements

There are create, read, update and delete calls for all of the three basic elements in OpenStreetMap (Nodes, Ways and Relations). These calls are very similar except for the payload and a few special error messages so they are documented only once.

Create: PUT /api/0.6/[node|way|relation]/create

Creates a new element of the specified type. Note that the entire request should be wrapped in a

<osm>...</osm>

element.

A Node:

<osm>
 <node changeset="12" lat="..." lon="...">
   <tag k="note" v="Just a node"/>
   ...
 </node>
</osm>

A Way:

<osm>
 <way changeset="12">
   <tag k="note" v="Just a way"/>
   ...
   <nd ref="123"/>
   <nd ref="4345"/>
   ...
 </way>
</osm>

A Relation:

<osm>
 <relation changeset="12">
   <tag k="note" v="Just a relation"/>
   ...
   <member type="node" role="stop" ref="123"/>
   <member type="way" ref="234"/>
 </relation>
</osm>

If multiple elements are provided only the first is created. The rest is discarded (this behaviour differs from changeset creation).

Response

The ID of the newly created element (content type is text/plain)

Error codes

HTTP status code 400 (Bad Request) - text/plain

When there are errors parsing the XML. A text message explaining the error is returned.

When a changeset ID is missing (unfortunately the error messages are not consistent)

When a node is outside the world

When there are too many nodes for a way

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP PUT request

HTTP status code 409 (Conflict) - text/plain

If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned

Or if the user trying to update the changeset is not the same as the one that created it

HTTP status code 412 (Precondition Failed)

When a way has nodes that do not exist or are not visible (i.e. deleted): "Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible."

When a relation has elements that do not exist or are not visible: "Relation with id #{id} cannot be saved due to #{element} with id #{element.id}"

Notes

• This updates the bounding box of the changeset.
• The role attribute for relations is optional. An empty string is the default.

Read: GET /api/0.6/[node|way|relation]/#id

Returns the XML representation of the element.

Example

/api/0.6/node/12345

Will get the node with id 12345

Response

XML representing the element, wrapped in an <osm> element:

<osm>
 <node id="123" lat="..." lon="..." version="142" changeset="12" user="fred" uid="123" visible="true" timestamp="2005-07-30T14:27:12+01:00">
   <tag k="note" v="Just a node"/>
   ...
 </node>
</osm>

Error codes

HTTP status code 404 (Not Found)

When no element with the given id could be found

HTTP status code 410 (Gone)

If the element has been deleted

Update: PUT /api/0.6/[node|way|relation]/#id

Updates data from a preexisting element. A full representation of the element as it should be after the update has to be provided. Any tags, way-node refs, and relation members that remain unchanged must be in the update as well. A version number must be provided as well.

Response

Returns the new version number with a content type of text/plain.

Error codes

HTTP status code 400 (Bad Request) - text/plain

When there are errors parsing the XML. A text message explaining the error is returned. This can also happen if you forget to pass the Content-Length header.

When a changeset ID is missing (unfortunately the error messages are not consistent)

When a node is outside the world

When there are too many nodes for a way

When the version of the provided element does not match the current database version of the element

HTTP status code 409 (Conflict) - text/plain

If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned

Or if the user trying to update the changeset is not the same as the one that created it

HTTP status code 404 (Not Found)

When no element with the given id could be found

HTTP status code 412 (Precondition Failed)

When a way has nodes that do not exist or are not visible (i.e. deleted): "Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible."

When a relation has elements that do not exist or are not visible: "Relation with id #{id} cannot be saved due to #{element} with id #{element.id}"

Notes

• This updates the bounding box of the changeset.

Delete: DELETE /api/0.6/[node|way|relation]/#id

Expects a valid XML representation of the element to be deleted.

For example:

<osm>
 <node id="..." version="..." changeset="..." lat="..." lon="..." />
</osm>

Where the node ID in the XML must match the ID in the URL, the version must match the version of the element you downloaded and the changeset must match the ID of an open changeset owned by the current authenticated user. It is allowed, but not necessary, to have tags on the element except for lat/long tags which are required, without lat+lon the server gives 400 Bad request.

Response

Returns the new version number with a content type of text/plain.

Error codes

HTTP status code 400 (Bad Request) - text/plain

When there are errors parsing the XML. A text message explaining the error is returned.

When a changeset ID is missing (unfortunately the error messages are not consistent)

When a node is outside the world

When there are too many nodes for a way

When the version of the provided element does not match the current database version of the element

HTTP status code 404 (Not Found)

When no element with the given id could be found

HTTP status code 409 (Conflict) - text/plain

If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned

Or if the user trying to update the changeset is not the same as the one that created it

HTTP status code 410 (Gone)

If the element has already been deleted

HTTP status code 412 (Precondition Failed)

When a node is still used by a way: Node #{id} is still used by way #{way.id}.

When a node is still member of a relation: Node #{id} is still used by relation #{relation.id}.

When a way is still member of a relation: Way #{id} still used by relation #{relation.id}.

When a relation is still member of another relation: The relation #{id} is used in relation #{relation.id}.

Note when returned as a result of a OsmChange upload operation the error messages contain a spurious plural "s" as in "... still used by ways ...", "... still used by relations ..." even when only 1 way or relation id is returned, as this implies multiple ids can be returned if the deleted object was/is a member of multiple parent objects, these ids are seperated by commas.

Notes

• In earlier API versions no payload was required. It is needed now because of the need for changeset IDs and version numbers.

History: GET /api/0.6/[node|way|relation]/#id/history

Retrieves all old versions of an element.

Error codes

HTTP status code 404 (Not Found)

When no element with the given id could be found

Version: GET /api/0.6/[node|way|relation]/#id/#version

Retrieves a specific version of the element.

Error codes

HTTP status code 403 (Forbidden)

When the version of the element is not available (due to redaction)

HTTP status code 404 (Not Found)

When no element with the given id could be found

Multi fetch: GET /api/0.6/[nodes|ways|relations]?#parameters

Allows a user to fetch multiple elements at once.

Parameters

[nodes|ways|relations]=comma separated list

The parameter has to be the same in the URL (e.g. /api/0.6/nodes?nodes=123,456,789)

Version numbers for each object may be optionally provided following a lowercase "v" character, e.g. /api/0.6/nodes?nodes=421586779v1,421586779v2

Error codes

HTTP status code 400 (Bad Request)

On a malformed request (parameters missing or wrong)

HTTP status code 404 (Not Found)

If one of the elements could not be found (By "not found" is meant never existed in the database, if the object was deleted, it will be returned with the attribute visible="false")

HTTP status code 414 (Request-URI Too Large)

If the URI was too long (How long is too long?)

Relations for element: GET /api/0.6/[node|way|relation]/#id/relations

Returns a XML document containing all (not deleted) relations in which the given element is used.

Notes

• There is no error if the element does not exist.
• If the element does not exist or it isn't used in any relations an empty XML document is returned (apart from the <osm> elements)

Ways for node: GET /api/0.6/node/#id/ways

Returns a XML document containing all the (not deleted) ways in which the given node is used.

Notes

• There is no error if the node does not exist.
• If the node does not exist or it isn't used in any ways an empty XML document is returned (apart from the <osm> elements)

Full: GET /api/0.6/[way|relation]/#id/full

This API call retrieves a way or relation and all other elements referenced by it

• For a way, it will return the way specified plus the full XML of all nodes referenced by the way.
• For a relation, it will return the following:
  • The relation itself
  • All nodes, ways, and relations that are members of the relation
  • Plus all nodes used by ways from the previous step
  • The same recursive logic is not applied to relations. This means: If relation r1 contains way w1 and relation r2, and w1 contains nodes n1 and n2, and r2 contains node n3, then a "full" request for r1 will give you r1, r2, w1, n1, and n2. Not n3.

Error codes

HTTP status code 404 (Not Found)

When no element with the given id could be found

HTTP status code 410 (Gone)

If the element has been deleted

Redaction: POST /api/0.6/[node|way|relation]/#id/#version/redact?redaction=#redaction_id

This is an API method originaly created for the ODbL license change to hide contributions from users that did not accept the new CT/licence. It is now used by the DWG to hide old versions of elements containing data privacy or copyright infringements. All API retrieval request for the element #version will return an HTTP error 403.

Notes

• only permitted for OSM accounts with the moderator role (DWG and server admins)
• the #redaction_id is listed on https://www.openstreetmap.org/redactions
• more information can be found in the source
• This is an extremely specialized call

Error Codes

HTTP status code 400 (Bad Request)

"Cannot redact current version of element, only historical versions may be redacted."

GPS traces

Retrieving GPS points

The following command returns, in GPX format, the GPS track points that are inside a given bounding box.

GET /api/0.6/trackpoints?bbox=left,bottom,right,top&page=pageNumber

where:

• left, bottom, right, and top are used the same way as they are in the command to retrieve nodes, ways, and relations.
• pageNumber specifies which group of 5,000 points, or page, to return. Since the command does not return more than 5,000 points at a time, this parameter must be incremented—and the command sent again (using the same bounding box)—in order to retrieve all of the points for a bounding box that contains more than 5,000 points. When this parameter is 0 (zero), the command returns the first 5,000 points; when it is 1, the command returns points 5,001–10,000, etc.

Examples

Retrieve the first 5,000 points for a bounding box:

https://api.openstreetmap.org/api/0.6/trackpoints?bbox=0,51.5,0.25,51.75&page=0

Retrieve the next 5,000 points (points 5,001–10,000) for the same bounding box:

https://api.openstreetmap.org/api/0.6/trackpoints?bbox=0,51.5,0.25,51.75&page=1

Uploading traces

You can upload a GPX file or archive of GPX files through the API:

POST /api/0.6/gpx/create

It expects the following POST parameters in a multipart/form-data HTTP message:

parameter	description
file	The GPX file containing the track points. Note that for successful processing, the file must contain trackpoints (<trkpt>), not only waypoints, and the trackpoints must have a valid timestamp. Since the file is processed asynchronously, the call will complete successfully even if the file cannot be processed. The file may also be a .tar, .tar.gz or .zip containing multiple gpx files, although it will appear as a single entry in the upload log.
description	The trace description.
tags	A string containing tags for the trace.
public	1 if the trace is public, 0 if not. This exists for backwards compatibility only - the visibility parameter should now be used instead. This value will be ignored if visibility is also provided.
visibility	One of the following: private, public, trackable, identifiable (for explanations see OSM trace upload page or Visibility of GPS traces)

HTTP basic authentication is required.

Downloading trace metadata

You access a GPX file's details and download the full file:

GET /api/0.6/gpx/<id>/details GET /api/0.6/gpx/<id>/data

HTTP basic authentication is required, although theoretically these calls should be allowed without authentication if the trace is marked public. If the trace is not public, only the owner may access the data.

Example "details" response:

<?xml version="1.0" encoding="UTF-8"?> <osm version="0.6" generator="OpenStreetMap server"> <gpx_file id="836619" name="track.gpx" lat="52.0194" lon="8.51807" user="Hartmut Holzgraefe" visibility="public" pending="false" timestamp="2010-10-09T09:24:19Z"> <description>PHP upload test</description> <tag>test</tag> <tag>php</tag> </gpx_file> </osm>

The "data" response will be the exact file uploaded.

You can also get a list of all the GPX traces for the authenticated user using:

GET /api/0.6/user/gpx_files

Methods for user data

Details of a user

This API method was added in September 2012 (code).

You can get the home location and the displayname of the user, by using

GET /api/0.6/user/#id

this returns for example

 <osm version="0.6" generator="OpenStreetMap server">
   <user id="12023" display_name="jbpbis" account_created="2007-08-16T01:35:56Z">
     <description></description>
     <contributor-terms agreed="false"/>
     <img href="http://www.gravatar.com/avatar/c8c86cd15f60ecca66ce2b10cb6b9a00.jpg?s=256&d=http%3A%2F%2Fwww.openstreetmap.org%2Fassets%2Fusers%2Fimages%2Flarge-39c3a9dc4e778311af6b70ddcf447b58.png"/>
     <roles>
     </roles>
     <changesets count="1"/>
     <traces count="0"/>
     <blocks>
       <received count="0" active="0"/>
     </blocks>
   </user>
 </osm>

or an empty file if no user found for given identifier.

Details of multiple users

This API method was added in July 2018 (code).

You can get the details of a number of users via

GET /api/0.6/users?users=#id1,#id2,...,#idn

this returns for example

  <osm version="0.6" generator="OpenStreetMap server">
    <user id="12023" display_name="jbpbis" account_created="2007-08-16T01:35:56Z">
      <description></description>
      <contributor-terms agreed="false"/>
      <img href="http://www.gravatar.com/avatar/c8c86cd15f60ecca66ce2b10cb6b9a00.jpg?s=256&amp;d=http%3A%2F%2Fwww.openstreetmap.org%2Fassets%2Fusers%2Fimages%2Flarge-39c3a9dc4e778311af6b70ddcf447b58.png"/>
      <roles>
      </roles>
      <changesets count="1"/>
      <traces count="0"/>
      <blocks>
        <received count="0" active="0"/>
      </blocks>
    </user>
    <user id="210447" display_name="siebh" account_created="2009-12-20T10:11:42Z">
      <description></description>
      <contributor-terms agreed="true"/>
      <roles>
      </roles>
      <changesets count="267"/>
      <traces count="1"/>
      <blocks>
        <received count="0" active="0"/>
      </blocks>
  </user>
</osm>

or an empty file if no user found for given identifier.

Details of the logged-in user

You can get the home location and the displayname of the user, by using

GET /api/0.6/user/details

this returns an XML document of the from

<osm version="0.6" generator="OpenStreetMap server">
 <user display_name="Max Muster" account_created="2006-07-21T19:28:26Z" id="1234">
   <contributor-terms agreed="true" pd="true"/>
   <img href="https://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"/>
   <roles></roles>
   <changesets count="4182"/>
   <traces count="513"/>
   <blocks>
       <received count="0" active="0"/>
   </blocks>
   <home lat="49.4733718952806" lon="8.89285988577866" zoom="3"/>
   <description>The description of your profile</description>
   <languages>
     <lang>de-DE</lang>
     <lang>de</lang>
     <lang>en-US</lang>
     <lang>en</lang>
   </languages>
   <messages>
     <received count="1" unread="0"/>
     <sent count="0"/>
   </messages>
 </user>
</osm>

The messages section has been available since mid-2013. It provides a basic counts of received, sent, and unread osm messages.

Preferences of the logged-in user

The OSM server supports storing arbitrary user preferences. This can be used by editors, for example, to offer the same configuration wherever the user logs in, instead of a locally-stored configuration.

You can retrieve the list of current preferences using

 GET /api/0.6/user/preferences

this returns an XML document of the form

  <osm version="0.6" generator="OpenStreetMap server">
    <preferences>
       <preference k="somekey" v="somevalue" />
       ...
    </preferences>
  </osm>

The same structure can be used to upload preferences (using the PUT method instead of GET). All existing preferences are replaced by the newly uploaded set.

Also possible is to PUT a single preference using

 PUT /api/0.6/user/preferences/[your_key] (without the brackets)

in this instance, the payload of the request should only contain the value of the preference, i.e. not XML formatted.

The PUT call returns HTTP response code 406 (not acceptable) if the same key occurs more than once, and code 413 (request entity too large) if you try to upload more than 150 preferences at once. The sizes of the key and value are limited to 255 characters.

Map Notes API

This provides access to the notes feature, which allows users to add geo-referenced textual "post-it" notes. This feature was not originally in the API 0.6 and was only added later ( 04/23/2013 in commit 0c8ad2f86edefed72052b402742cadedb0d674d9 )

Retrieving notes data by bounding box: GET /api/0.6/notes

Returns the existing notes in the specified bounding box. The notes will be ordered by the date of their last change, the most recent one will be first. The list of notes can be returned in several different forms (e.g. as executable JavaScript, XML, RSS, json and GPX) depending on the file extension.

URL: https://api.openstreetmap.org/api/0.6/notes?bbox=left,bottom,right,top (example)
Return type: application/xml

Parameter	Description	Allowed values	Default value
bbox	Coordinates for the area to retrieve the notes from	Floating point numbers in degrees, expressing a valid bounding box, not larger than the configured size limit, 25 square degrees [1], not overlapping the dateline.	none, parameter required
limit	Specifies the number of entries returned at max	A value of between 1 and 10000 is valid	100 is the default
closed	Specifies the number of days a note needs to be closed to no longer be returned	A value of 0 means only open notes are returned. A value of -1 means all notes are returned.	7 is the default

You can specify the format you want the results returned as by specifying a file extension. E.g. example to get results in json. Currently the format RSS, XML, json and gpx are supported.

Error codes

HTTP status code 400 (Bad Request)

When any of the limits are crossed

Read: GET /api/0.6/notes/#id

Returns the existing note with the given ID. The output can be in several formats (e.g. XML, RSS, json or GPX) depending on the file extension.

URL: https://api.openstreetmap.org/api/0.6/notes/#id ([2])
Return type: application/xml

Error codes

HTTP status code 404 (Not Found)

When no note with the given id could be found

Create a new note: Create: POST /api/0.6/notes

Create a new note

URL: https://api.openstreetmap.org/api/0.6/notes?lat=51.00&lon=0.1&text=ThisIsANote (example)
Return type: application/xml

Parameter	Description	Allowed values	Default value
lat	Specifies the latitude of the note	floatingpoint number in degrees	No default, needs to be specified
lon	Specifies the longitude of the note	floatingpoint number in degrees	No default, needs to be specified
text	A text field with arbitrary text containing the note		No default, needs to be present

If the request is made as an authenticated user, the note is associated to that user account.

Error codes

HTTP status code 400 (Bad Request)

if the text field was not present

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP POST request

Create a new comment: Create: POST /api/0.6/notes/#id/comment

Add a new comment to note #id

URL: https://api.openstreetmap.org/api/0.6/notes/#id/comment?text=ThisIsANoteComment (example)
Return type: application/xml

Parameter	Description	Allowed values	Default value
text	The comment	A text field with arbitrary text	No default, needs to be present

Error codes

HTTP status code 400 (Bad Request)

if the text field was not present

HTTP status code 404 (Not found)

if no note with that id is not available

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP POST request

HTTP status code 409 (Conflict)

When the note is closed

Close: POST /api/0.6/notes/#id/close

Close a note as fixed.

URL: https://api.openstreetmap.org/api/0.6/notes/#id/close?text=Comment (example)
Return type: application/xml

This request needs to be done as an authenticated user.

Error codes

HTTP status code 404 (Not Found)

When no note with the given id could be found

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP POST request

HTTP status code 409 (Conflict)

When closing an already closed note

Reopen: POST /api/0.6/notes/#id/reopen

Reopen a closed note.

URL: https://api.openstreetmap.org/api/0.6/notes/#id/reopen?text=Comment (example)
Return type: application/xml

This request needs to be done as an authenticated user.

Error codes

HTTP status code 404 (Not Found)

When no note with the given id could be found

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP POST request

HTTP status code 409 (Conflict)

When reopening an already open note

HTTP status code 410 (Gone)

When reopening a deleted note

Search for notes on text and comments: GET /api/0.6/notes/search

Returns the existing notes matching either the initial note text or any of the comments. The notes will be ordered by the date of their last change, the most recent one will be first. The list of notes can be returned in several different forms (e.g. XML, RSS, json or GPX) depending on file extension given.

URL: https://api.openstreetmap.org/api/0.6/notes/search?q=SearchTerm (example)
Return type: application/xml

Parameter	Description	Allowed values	Default value
q	Specified the search query	String	none, parameter required
limit	Specifies the number of entries returned at max	A value of between 1 and 10000 is valid	100 is the default
closed	Specifies the number of days a note needs to be closed to no longer be returned	A value of 0 means only open notes are returned. A value of -1 means all notes are returned.	7 is the default

Error codes

HTTP status code 400 (Bad Request)

When any of the limits are crossed

When NOT to use the API

For bulk upload scripts or data modification, the API may not be the proper mechanism. The modern version of creating a bulk upload or modification script is to build a change set, load it into an editor like JOSM, and verify the work prior to commit. You can also use the API to upload a change set in an atomic manner. See also: Change File Formats, Import

The API is primarily intended for editing. For read-only purposes or projects, see API usage policy.

Further reading

• People making clients, see API v0.6 (Archive)#Changes in related_software
• People interested in the DB see API v0.6 (Archive)#Database improvements
• possible API errors