API v0.6 - OpenStreetMap Wiki ThisIsANote
API v0.6
From OpenStreetMap Wiki
Jump to navigation
Jump to search
Help
API v0.6
In other languages
Afrikaans
asturianu
azərbaycanca
Bahasa Indonesia
Bahasa Melayu
bosanski
brezhoneg
català
čeština
Crnogorski
dansk
eesti
Esperanto
euskara
Frysk
Gàidhlig
galego
hrvatski
Ido
interlingua
íslenska
italiano
Kreyòl ayisyen
kréyòl gwadloupéyen
kurdî
latviešu
Lëtzebuergesch
lietuvių
magyar
Nederlands
norsk
norsk nynorsk
occitan
polski
português
română
sardu
shqip
slovenčina
slovenščina
srpski (latinica)
suomi
svenska
Tagalog
Tiếng Việt
Türkçe
Zazaki
Ελληνικά
беларуская
български
македонски
монгол
русский
српски / srpski
українська
հայերեն
עברית
العربية
سرائیکی
فارسی
پنجابی
پښتو
नेपाली
मराठी
हिन्दी
বাংলা
ਪੰਜਾਬੀ
தமிழ்
മലയാളം
සිංහල
ไทย
မြန်မာဘာသာ
한국어
ქართული
ⵜⴰⵎⴰⵣⵉⵖⵜ
中文（简体）
中文（繁體）
粵語
Other languages...
API v0.6
is the
current
version of the
OSM Editing API
originally deployed 17-21 April 2009.
This page and the API has been extended and updated multiple times since April 2009:
In March 2012 to reflect small changes
In April 2013 after the addition of the Map Notes API
In January 2016 after the addition of changeset discussions
In January 2018, compression for diff uploads was added in
Supporting Input decompression
GitHub
In July 2018 after numerous other smaller backwards compatible changes.
In December 2019, the
expand_bbox
endpoint was removed.
In March 2020, JSON support for OSM element endpoints was added.
In September 2020, JSON support for user details was added.
In February 2021, the undocumented, unused and obsolete
/changes
endpoint was removed.
In February 2022, limiting the maximum number of relation members in
Limits on number of tags and relation members
GitHub
and
Introduce relation member limit
GitHub
In March 2022, the permissions endpoint was added.
In April 2022,
JSON support for some changeset endpoints
GitHub
was added
In July 2023,
the
limit
parameter for changeset queries
GitHub
was added
In September 2023,
the
bbox
parameter for note searches
GitHub
was added
In September 2023,
the comment id for changeset discussion comments
GitHub
was included in API responses
In September 2023,
the ability to read user blocks
GitHub
was added
In November 2023,
Added the ability to rate limit edits
GitHub
In June 2024,
OAuth 1.0a and HTTP Basic Auth were shut down.
In June 2024,
Add the ability to limit changeset size
GitHub
In July 2024, the
Messaging API
was added.
On August 25, 2024, with the release of openstreetmap-cgimap 2.0.0, the changeset GET endpoint
GET /api/0.6/changeset/#id?include_discussion=true
JSON response was changed, to align it with the existing Rails implementation. See the
GitHub discussion
GitHub
for more details.
In November 2024,
the ability to subscribe to note discussions
GitHub
was added
In December 2024 - March 2025, various changes were made to align with Rails default REST routes and for consistency between different endpoints:
GET /api/0.6/gpx/#id/details
was deprecated in favor of
GET /api/0.6/gpx/#id
GitHub
POST /api/0.6/gpx
was added to upload gpx files and
POST /api/0.6/gpx/create
was deprecated.
GitHub
PUT /api/0.6/user/messages/#id
was added to update read status of a message and its
POST
equivalent was deprecated.
GitHub
Wrapper
element was removed from
GET /api/0.6/user/messages/inbox
XML Response.
GitHub
POST /api/0.6/[nodes|ways|relations]
was added to create elements and
PUT /api/0.6/[node|way|relation]/create
was deprecated.
GitHub
POST /api/0.6/changeset/comment/#comment_id/hide
and
POST /api/0.6/changeset/comment/#comment_id/unhide
were deprecated in favor of new
DELETE /api/0.6/changeset_comments/#id/visibility
and
POST /api/0.6/changeset_comments/#id/visibility
GitHub
POST /api/0.6/changeset/#id/subscribe
and
POST /api/0.6/changeset/#id/unsubscribe
were deprecated in favor of new
POST /api/0.6/changeset/#id/subscription
and
DELETE /api/0.6/changeset/#id/subscription
GitHub
In February 2025, the abilities
to block users
GitHub
and
to read active blocks of a current user
GitHub
were added
In February 2025, the ability
to search changeset comment by author or time
GitHub
was added
In April 2025,
GET /api/0.6/gpx_files.json
was added to support JSON response for this API
GitHub
In November 2025, the
company
and
social_links
properties from the website were added to the
GET /api/0.6/user/#id
endpoint in the API
In February 2026, 3 new properties for
enhanced changeset statistics
GitHub
were added to
GET /api/0.6/changeset/#id
and
GET /api/0.6/changesets
Forthcoming / planned changes:
(none)
Contents
General information
1.1
URL + authentication
1.1.1
Required scopes for Oauth 2.0
1.1.2
Error codes
1.2
Elements
1.3
Changesets
1.4
Tags
1.5
Maximum string lengths
1.6
Reliably identifying users
1.7
Version numbers/optimistic locking
1.8
XML Format
1.9
JSON Format
1.10
Faking the correct HTTP methods
1.11
Internal errors while generating a response
API calls
2.1
Miscellaneous
2.1.1
Available API versions: GET /api/versions
2.1.1.1
Response XML
2.1.1.2
Response JSON
2.1.2
Capabilities: GET /api/capabilities
2.1.2.1
Response
2.1.2.2
Notes
2.1.3
Retrieving map data by bounding box: GET /api/0.6/map
2.1.3.1
Error codes
2.1.4
Retrieving permissions: GET /api/0.6/permissions
2.1.4.1
Response XML
2.1.4.2
Response JSON
2.1.4.3
Notes
2.2
Changesets
2.2.1
Bounding box computation
2.2.2
Create: PUT /api/0.6/changeset/create
2.2.2.1
Response
2.2.2.2
Error codes
2.2.2.3
Notes
2.2.3
Read: GET /api/0.6/changeset/#id?
include_discussion=
true
2.2.3.1
Parameters
2.2.3.2
Response XML
2.2.3.3
Response JSON
2.2.3.4
Error codes
2.2.3.5
Notes
2.2.4
Update: PUT /api/0.6/changeset/#id
2.2.4.1
Parameters
2.2.4.2
Response
2.2.4.3
Error codes
2.2.4.4
Notes
2.2.5
Close: PUT /api/0.6/changeset/#id/close
2.2.5.1
Parameters
2.2.5.2
Response
2.2.5.3
Error codes
2.2.6
Download: GET /api/0.6/changeset/#id/download
2.2.6.1
Parameters
2.2.6.2
Response
2.2.6.3
Error codes
2.2.6.4
Notes
2.2.7
Expand Bounding Box: POST /api/0.6/changeset/#id/expand_bbox
(deprecated, gone)
2.2.8
Query: GET /api/0.6/changesets
2.2.8.1
Parameters
2.2.8.2
Response
2.2.8.3
Error codes
2.2.8.4
Notes
2.2.9
Diff upload: POST /api/0.6/changeset/#id/upload
2.2.9.1
Parameters
2.2.9.2
Response
2.2.9.3
Error codes
2.2.9.4
Notes
2.2.10
Changeset summary
2.3
Changeset discussion
2.3.1
Comment: POST /api/0.6/changeset/#id/comment
2.3.1.1
Parameters
2.3.1.2
Error codes
2.3.1.3
Notes
2.3.2
Subscribe: POST /api/0.6/changeset/#id/subscription
2.3.2.1
Error codes
2.3.3
Unsubscribe: DELETE /api/0.6/changeset/#id/subscription
2.3.3.1
Error codes
2.3.4
Search changeset comments: GET /api/0.6/changeset_comments
2.3.4.1
Parameters
2.3.4.2
Examples
2.3.4.3
Error codes
2.3.5
Hide changeset comment: DELETE /api/0.6/changeset_comments/#id/visibility
2.3.5.1
Error codes
2.3.5.2
Notes
2.3.6
Unhide changeset comment: POST /api/0.6/changeset_comments/#id/visibility
2.3.6.1
Error codes
2.3.6.2
Notes
2.4
Elements
2.4.1
Create: POST /api/0.6/[nodes|ways|relations]
2.4.1.1
Response
2.4.1.2
Error codes
2.4.1.3
Notes
2.4.2
Read: GET /api/0.6/[node|way|relation]/#id
2.4.2.1
Response XML
2.4.2.2
Response JSON
2.4.2.3
Error codes
2.4.3
Update: PUT /api/0.6/[node|way|relation]/#id
2.4.3.1
Response
2.4.3.2
Error codes
2.4.3.3
Notes
2.4.4
Delete: DELETE /api/0.6/[node|way|relation]/#id
2.4.4.1
Response
2.4.4.2
Error codes
2.4.4.3
Notes
2.4.5
History: GET /api/0.6/[node|way|relation]/#id/history
2.4.5.1
Error codes
2.4.6
Version: GET /api/0.6/[node|way|relation]/#id/#version
2.4.6.1
Error codes
2.4.7
Multi fetch: GET /api/0.6/[nodes|ways|relations]?#parameters
2.4.7.1
Parameters
2.4.7.2
Error codes
2.4.7.3
Notes
2.4.8
Relations for element: GET /api/0.6/[node|way|relation]/#id/relations
2.4.8.1
Notes
2.4.9
Ways for node: GET /api/0.6/node/#id/ways
2.4.9.1
Notes
2.4.10
Full: GET /api/0.6/[way|relation]/#id/full
2.4.10.1
Error codes
2.4.11
Redaction: POST /api/0.6/[node|way|relation]/#id/#version/redact?redaction=#redaction_id
2.4.11.1
Notes
2.4.11.2
Error codes
2.5
GPS traces
2.5.1
Get GPS Points: Get /api/0.6/trackpoints?bbox=
left
bottom
right
top
&page=
pageNumber
2.5.1.1
Examples
2.5.1.2
Response
2.5.2
Create: POST /api/0.6/gpx
2.5.2.1
Error codes
2.5.3
Update: PUT /api/0.6/gpx/#id
2.5.4
Delete: DELETE /api/0.6/gpx/#id
2.5.5
Download Metadata: GET /api/0.6/gpx/#id
2.5.6
Download Data: GET /api/0.6/gpx/#id/data
2.5.7
List: GET /api/0.6/user/gpx_files
2.6
Methods for user data
2.6.1
Details of a user: GET /api/0.6/user/#id
2.6.1.1
Response XML
2.6.1.2
Response JSON
2.6.2
Details of multiple users: GET /api/0.6/users?users=#id1,#id2,...,#idn
2.6.2.1
Response XML
2.6.2.2
Response JSON
2.6.3
Details of the logged-in user: GET /api/0.6/user/details
2.6.3.1
Response XML
2.6.3.2
Response JSON
2.6.4
Preferences of the logged-in user: GET|PUT|DELETE /api/0.6/user/preferences
2.6.4.1
Response XML
2.6.4.2
Response JSON
2.7
Map Notes API
2.7.1
Retrieving notes data by bounding box: GET /api/0.6/notes
2.7.1.1
Response XML
2.7.1.2
Response JSON
2.7.1.3
Error codes
2.7.2
Read: GET /api/0.6/notes/#id
2.7.2.1
Error codes
2.7.3
Create a new note: POST /api/0.6/notes
2.7.3.1
XML
2.7.3.2
JSON
2.7.3.3
Parameters
2.7.3.4
Error codes
2.7.4
Create a new comment: POST /api/0.6/notes/#id/comment
2.7.4.1
Error codes
2.7.5
Close: POST /api/0.6/notes/#id/close
2.7.5.1
Error codes
2.7.6
Reopen: POST /api/0.6/notes/#id/reopen
2.7.6.1
Error codes
2.7.7
Hide: DELETE /api/0.6/notes/#id
2.7.7.1
Error codes
2.7.8
Subscribe: POST /api/0.6/notes/#id/subscription
2.7.8.1
Error codes
2.7.9
Unsubscribe: DELETE /api/0.6/notes/#id/subscription
2.7.9.1
Error codes
2.7.10
Search for notes: GET /api/0.6/notes/search
2.7.10.1
Examples
2.7.10.2
Error codes
2.7.11
RSS Feed: GET /api/0.6/notes/feed
2.8
User Blocks
2.8.1
Create: POST /api/0.6/user_blocks
2.8.1.1
Parameters
2.8.1.2
Error codes
2.8.2
Read: GET /api/0.6/user_blocks/#id
2.8.2.1
Response XML
2.8.2.2
Response JSON
2.8.3
List active blocks: GET /api/0.6/user/blocks/active
2.8.3.1
Response XML
2.8.3.2
Response JSON
When
NOT
to use the API
Semantic versioning
Further reading
References
General information
Please note that this is not official documentation
. Documented here behavior may change in the future
The code powering the API can be found on GitHub at
openstreetmap/openstreetmap-website/tree/master/app/controllers/api
GitHub
Some of the API calls on osm.org are handled by
CGImap
and its source code is also available on GitHub at
zerebubuth/openstreetmap-cgimap
GitHub
This Editing API is based on the ideas of the RESTful API. For more information on RESTful APIs see
wikipedia's Representational State Transfer page
The REST API is the server component to which client requests are addressed. RESTful API requests use HTTP
GET
PUT
POST
, and
DELETE
request types to perform certain actions. The request payload, if present, is returned as XML, (MIME type "
application/xml
") and UTF-8 character encoding. The HTTP
Accept-Encoding
header can be used to request compressed data. The
Content-Type
and
Content-Encoding
headers aren't strictly necessary, since the OSM API defaults to the aforementioned XML/UTF-8 format. See
#JSON Format
for information about JSON responses.
Requests to modify the database are authorized using
OAuth
. Read requests do not require authorization (except user details).
Changes between API v0.5 and API v0.6
For downloading data for purposes other than editing see
Downloading data
- you will likely use
Overpass API
(maybe with
Overpass turbo
),
Planet.osm
or
extracts
URL + authentication
For more information about using OAuth, also see the main article about
OAuth
The API is currently accessible using the following URL:
When testing your software against the API you should consider using
instead of the live-api. Your account for the live service is not in the same database, so you probably need a new username and password for the test service; please visit that page in a browser to sign up.
All of the calls to the API which update, create or delete data have to be made by an authenticated and authorized user. Authentication works by using
OAuth
2.0.
Required scopes for Oauth 2.0
The required OAuth scopes to be able to use the full API v0.6 are:
read_prefs
write_prefs
write_api
write_changeset_comments
(currently included in
write_api
read_gpx
write_gpx
write_notes
write_diary
(Supported scope by OAuth2 but is not required by the API v0.6)
write_redactions
write_blocks
consume_messages
send_messages
Error codes
HTTP status code 400 (Bad request)
If you are accessing the cgimap version of the API, this error code will be returned when OAuth fails with a "Bad OAuth request.".
HTTP status code 401 (Unauthorized)
Login was unsuccessful.
HTTP status code 403 (Forbidden)
Login was successful but the user is not allowed to carry out the operation.
The user may have been blocked, or the OAuth application may not have been given the required permissions. An application should display the error message (which will be translated if necessary) and, if it has an end-user UI, provide an easy way to access openstreetmap.org and view any messages there.
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.
Maximum string lengths
The current rails and CGImap implementation of the API limits the length of key and value strings for object, changeset and user preference tags, and relation member roles, to a maximum of 255 UTF-8 unicode codepoints.
Note: the limit is in unicode codepoints, not bytes, grapheme clusters, code units, or other measures.
Reliably identifying users
The previous API v0.5 returned only the user display name. The user can update this at any time and there is no history stored for display name changes. This means there was no way to reliably identify which user made a specific change. API v0.6 includes the numeric user ID of the account in addition to the display name. E.g.,
"68"
...
user=
"fred"
uid=
"123"
/>
This still requires the user to have made his edits public. User ID for users who have previously made anonymous changes will not be visible. In accordance with a recommendation from the OpenStreetMap Foundation Board,
anonymous edits
are no longer allowed.
Version numbers/optimistic locking
The planet dump, diffs and the API calls for elements will return a
version
attribute for each
Node
Way
and
Relation
"68"
...
version=
"12"
/>
These version numbers are used for
optimistic locking
. To upload a new version of an object, the client will need to provide the version of the object it is modifying. If the version supplied is not the same as the server's current version, an error will be returned (HTTP status code 409: Conflict). This means that any client that is updating data will need to save the version numbers of the original data. One element can be updated multiple times during one changeset and its version number is increased each time so there can be multiple
history versions
of a single element for one changeset.
In addition, clients can now ask for specific versions of an element.
Version numbers will always begin at
and increase by 1 every time an element is changed. Clients should not, however, rely on the increase by 1 when updating an element, but instead retrieve the new version number from the server response.
XML Format
Main article:
OSM XML
Every XML response from the server is wrapped in an
element unless specified otherwise (e.g., for diff uploads, or changeset downloads). In most of the later examples this wrapper is left out.
"0.6"
generator=
"OpenStreetMap server"
...
...
Every call to the API has to be wrapped in an
element as well but the
version
and
generator
attributes can be left out.
JSON Format
Main article:
OSM JSON
The
OSM API JSON format
is based on (but is not completely compatible with) the
Overpass API JSON format description
and is supported for the following endpoints:
Retrieving map data by bounding box:
GET /api/0.6/map
Read:
GET /api/0.6/[node|way|relation]/#id
History:
GET /api/0.6/[node|way|relation]/#id/history
Version:
GET /api/0.6/[node|way|relation]/#id/#version
Multi fetch:
GET /api/0.6/[nodes|ways|relations]?#parameters
Relations for element:
GET /api/0.6/[node|way|relation]/#id/relations
Ways for node:
GET /api/0.6/node/#id/ways
Full:
GET /api/0.6/[way|relation]/#id/full
In addition, the following endpoints support JSON format:
Retrieving API versions:
GET /api/versions
Retrieving API capabilities:
GET /api/capabilities
and
GET /api/0.6/capabilities
Retrieving permissions:
GET /api/0.6/permissions
Methods for user data
Details of a user:
GET /api/0.6/user/#id
Details of multiple users:
GET /api/0.6/users?users=#id1,#id2,...,#idn
Details of the logged-in user:
GET /api/0.6/user/details
Preferences of the logged-in user:
GET /api/0.6/preferences
Map Notes API
Retrieving notes data by bounding box:
GET /api/0.6/notes
Read:
GET /api/0.6/notes/#id
Create a new note:
POST /api/0.6/notes
Search for notes:
GET /api/0.6/notes/search
Changesets
Query:
GET /api/0.6/changesets
Read:
GET /api/0.6/changeset/#id?include_discussion=true
Subscribe:
POST /api/0.6/changeset/#id/subscribe
(JSON response)
Unsubscribe:
POST /api/0.6/changeset/#id/unsubscribe
(JSON response)
Comment:
POST /api/0.6/changeset/#id/comment
(JSON response)
Search changeset comments:
GET /api/0.6/changeset_comments
(JSON response)
Hide changeset comment:
POST /api/0.6/changeset/comment/#comment_id/hide
(JSON response)
Unhide changeset comment:
POST /api/0.6/changeset/comment/#comment_id/unhide
(JSON response)
To request JSON format, either set the HTTP
Accept
header to
application/json
, or use a
.json
URL path suffix.
Github issue
Faking the correct HTTP methods
Faking the HTTP request method by providing an X_HTTP_METHOD_OVERRIDE header is not supported anymore (as of February 2024). It is not known when this feature was removed.
Internal errors while generating a response
In the unlikely event of an internal error occurring while generating the response to an API call, an
error
element will be inserted. Further processing stops at this point.
Even though the HTTP return code is 200, and the response is syntactically correct, the message will be incomplete, and MUST be discarded by editing applications. For further analysis, editing applications SHOULD report an internal API error back to the user, along with the error message returned by the API call.
XML example payload containing an
error
element
"0.6"
generator=
"CGImap 0.8.7 (26234 ubuntu)"
copyright=
"OpenStreetMap and contributors"
attribution=
"http://www.openstreetmap.org/copyright"
license=
"http://opendatacommons.org/licenses/odbl/1-0/"
"4000392204"
visible=
"true"
version=
"1"
changeset=
"1874689"
timestamp=
"2022-07-26T20:56:27Z"
user=
"mmd2"
uid=
"1"
"5004686582"
/>
"5004686236"
/>
"5004686540"
/>
"5004686705"
/>
"5004686546"
/>
"5004686468"
/>
"5004686472"
/>
"bicycle"
v=
"use_sidepath"
/>
"highway"
v=
"secondary"
/>
"maxspeed"
v=
"50"
/>
"name"
v=
"Bunderstraat"
/>
"old_ref"
v=
"N586"
/>
"surface"
v=
"asphalt"
/>
Mismatch
in
tags
key
and
value
size
JSON example payload containing an
error
element
"version"
"0.6"
"generator"
"CGImap 0.8.7 (22730 ubuntu)"
"copyright"
"OpenStreetMap and contributors"
"attribution"
"http://www.openstreetmap.org/copyright"
"license"
"http://opendatacommons.org/licenses/odbl/1-0/"
"elements"
"type"
"way"
"id"
4000392204
"timestamp"
"2022-07-26T20:56:27Z"
"version"
"changeset"
1874689
"user"
"mmd2"
"uid"
"nodes"
5004686582
5004686236
5004686540
5004686705
5004686546
5004686468
5004686472
],
"tags"
"bicycle"
"use_sidepath"
"highway"
"secondary"
"maxspeed"
"50"
"name"
"Bunderstraat"
"old_ref"
"N586"
"surface"
"asphalt"
},
"error"
"Mismatch in tags key and value size"
API calls
Miscellaneous
Available API versions:
GET /api/versions
Returns a list of API versions supported by this instance.
Response XML
GET /api/versions
"OpenStreetMap server"
copyright=
"OpenStreetMap and contributors"
attribution=
"https://www.openstreetmap.org/copyright"
license=
"https://opendatacommons.org/licenses/odbl/1-0/"
0.6
Response JSON
GET /api/versions.json
"version"
"0.6"
"generator"
"OpenStreetMap server"
"api"
"versions"
"0.6"
Capabilities:
GET /api/capabilities
Also available as:
GET /api/0.6/capabilities
This API call is meant to provide information about the capabilities and limitations of the current API.
Response
Returns a XML document (content type
application/xml
"0.6"
generator=
"OpenStreetMap server"
copyright=
"OpenStreetMap and contributors"
attribution=
"https://www.openstreetmap.org/copyright"
license=
"https://opendatacommons.org/licenses/odbl/1-0/"
"0.6"
maximum=
"0.6"
/>
"0.25"
/>
"25"
/>
"5000"
/>
"2000"
/>
"32000"
/>
"10000"
default_query_limit=
"100"
maximum_query_limit=
"100"
/>
"100"
maximum_query_limit=
"10000"
/>
"300"
/>
"online"
api=
"online"
gpx=
"online"
/>
".*\.google(apis)?\..*/(vt|kh)[\?/].*([xyz]=.*){3}.*"
/>
"http://xdworld\.vworld\.kr:8080/.*"
/>
".*\.here\.com[/:].*"
/>
Please note that actual returned values may change at any time and this XML document only serves as an example.
Copyright, attribution, and license: referring to legal information
API:
version
minimum
and
maximum
are the API call versions that the server will accept.
area
maximum
is the maximum area in square degrees that can be queried by API calls.
tracepoints
per_page
is the maximum number of points in a single GPS trace. (Possibly incorrect)
waynodes
maximum
is the maximum number of nodes that a way may contain.
relationmembers
maximum
is the maximum number of members that a relation may contain. (
added in February 2022
changesets
maximum_elements
is the maximum number of combined nodes, ways and relations that can be contained in a changeset.
changesets
default_query_limit
and
maximum_query_limit
are the default and maximum values of the limit parameter of
changeset queries
. (
added in
August 2023
GitHub
notes
default_query_limit
and
maximum_query_limit
are the default and maximum values of the limit parameter of notes
bounding box queries
and
. (
added in
August 2023
GitHub
The
status
element returns either
online
readonly
or
offline
for each of the database, API and GPX API. The
database
field is informational, and the
api
gpx
fields indicate whether a client should expect read and write requests to work (
online
), only read requests to work (
readonly
) or no requests to work (
offline
).
Policy:
Imagery blacklist lists all aerial and map sources, which are not permitted for OSM usage due to copyright. Editors must not show these resources as background layer.
Notes
Currently both versioned (
/api/0.6/capabilities
) and unversioned (
/api/capabilities
) version of this call exist. The unversioned one is
deprecated
GitHub
in favor of
checking the available versions
first, then accessing the capabilities of a particular version.
Element and relation member ids are currently implementation dependent limited to 64bit signed integers, this should not be a problem :-).
Retrieving map data by bounding box:
GET /api/0.6/map
The following command returns:
All nodes that are inside a given bounding box and any relations that reference them.
All ways that reference at least one node that is inside a given bounding box, any relations that reference them [the ways], and any nodes outside the bounding box that the ways may reference.
All relations that reference one of the nodes, ways or relations included due to the above rules. (Does
not
apply recursively, see explanation below.)
GET /api/0.6/map?bbox=
left
bottom
right
top
where:
left
is the longitude of the left (westernmost) side of the bounding box.
bottom
is the latitude of the bottom (southernmost) side of the bounding box.
right
is the longitude of the right (easternmost) side of the bounding box.
top
is the latitude of the top (northernmost) side of the bounding box.
Note that, while this command returns those relations that reference the aforementioned nodes and ways, the reverse is not true: it does not (necessarily) return all of the nodes and ways that are referenced by these relations. This prevents unreasonably-large result sets. For example, imagine the case where:
There is a relation named "England" that references every node in England.
The nodes, ways, and relations are retrieved for a bounding box that covers a small portion of England.
While the result would include the nodes, ways, and relations as specified by the rules for the command, including the "England" relation, it would (fortuitously)
not
include
every
node and way in England. If desired, the nodes and ways referenced by the "England" relation could be retrieved by their respective IDs.
Also note that ways which intersect the bounding box but have no nodes within the bounding box will not be returned.
Error codes
HTTP status code 400 (Bad Request)
When any of the node/way/relation limits are exceeded, in particular if the call would return more than 50'000 nodes. See above for other uses of this code.
HTTP status code 509 (Bandwidth Limit Exceeded)
"Error: You have downloaded too much data. Please try again later." See
Developer FAQ
Retrieving permissions:
GET /api/0.6/permissions
Returns the permissions granted to the current API connection.
If the API client is not authorized, an empty list of permissions will be returned.
If the API client uses OAuth 2.0, the list will be based on the granted scopes.
For previously available Basic Auth, the list of permissions contained all permissions. Basic Auth was removed in June 2024.
Note that for compatibility reasons, all OAuth 2.0 scopes will be prefixed by "allow_", e.g. scope "read_prefs" will be shown as permission "allow_read_prefs".
Response XML
GET /api/0.6/permissions
Returns the single permissions element containing the permission tags (content type
application/xml
"0.6"
generator=
"OpenStreetMap server"
"allow_read_prefs"
/>
...
"allow_read_gpx"
/>
"allow_write_gpx"
/>
Response JSON
GET /api/0.6/permissions.json
Returns the single permissions element containing the permission tags (content type
application/json
"version"
"0.6"
"generator"
"OpenStreetMap server"
"permissions"
"allow_read_prefs"
...
"allow_read_gpx"
"allow_write_gpx"
Notes
Currently the following permissions can appear in the result, corresponding directly to the ones used in the OAuth 2.0 application definition:
allow_read_prefs (read user preferences)
allow_write_prefs (modify user preferences)
allow_write_diary (create diary entries, comments and make friends)
allow_write_api (modify the map)
allow_write_changeset_comments (comment on changesets)
allow_write_redactions (redact element versions)
allow_read_gpx (read private GPS traces)
allow_write_gpx (upload GPS traces)
allow_write_notes (modify notes)
allow_write_redactions (redact map data)
allow_write_blocks (create and revoke user blocks)
allow_consume_messages (read, update status and delete user messages)
allow_send_messages (send private messages to other users)
Changesets
To make it easier to identify related changes the concept of changesets is introduced. Every modification of the standard OSM elements has to reference an open changeset. A changeset may contain tags just like the other elements. A recommended tag for changesets is the key
comment
=*
with a short human readable description of the changes being made in that changeset, similar to a commit message in a revision control system. A new changeset can be opened at any time and a changeset may be referenced from multiple API calls. Because of this it can be closed manually as the server can't know when one changeset ends and another should begin. To avoid stale open changesets a mechanism is implemented to automatically close changesets upon one of the following three conditions:
10,000 edits on a single changeset (see the
capabilities endpoint
for 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)
Note that some older changesets may contain slightly more than 10k (or previously 50k) changes due to some glitches in the API.
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.
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 as a 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 is the metadata of this changeset. The body of the request has to include one or more
changeset
elements, which optionally include an arbitrary number of tags (such as 'comment', 'created_by", ...). All
changeset
elements need to be enclosed in an
osm
element.
"created_by"
v=
"JOSM 1.61"
/>
"comment"
v=
"Just adding some streetnames"
/>
...
...
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.
The maximum length of changeset tags is 255 characters, just like regular tags. This applies separately to the key and value.
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.
Parameters
id
The id of the changeset to retrieve
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 XML
Returns the single changeset element containing the changeset tags with a content type of
application/xml
GET /api/0.6/changeset/#id?include_discussion=true
"0.6"
generator=
"CGImap 0.9.3 (987909 spike-08.openstreetmap.org)"
copyright=
"OpenStreetMap and contributors"
attribution=
"http://www.openstreetmap.org/copyright"
license=
"http://opendatacommons.org/licenses/odbl/1-0/"
"10"
created_at=
"2008-11-08T19:07:39+01:00"
open=
"true"
user=
"fred"
uid=
"123"
min_lon=
"7.0191821"
min_lat=
"49.2785426"
max_lon=
"7.0197485"
max_lat=
"49.2793101"
comments_count=
"3"
changes_count=
"10"
created_count=
"2"
modified_count=
"5"
deleted_count=
"3"
"created_by"
v=
"JOSM 1.61"
/>
"comment"
v=
"Just adding some streetnames"
/>
...
"1234"
date=
"2015-01-01T18:56:48Z"
uid=
"1841"
user=
"metaodi"
Did
you
verify
those
street
names?
"5678"
date=
"2015-01-01T18:58:03Z"
uid=
"123"
user=
"fred"
sure!
...
Response JSON
Returns the single changeset element containing the changeset tags with a content type of
application/json
GET /api/0.6/changeset/#id.json?include_discussion=true
Please note that the JSON format has changed on August 25, 2024 with the release of openstreetmap-cgimap 2.0.0, to align it with the existing Rails format.
"version"
"0.6"
"generator"
"openstreetmap-cgimap 2.0.0 (4003517 spike-08.openstreetmap.org)"
"copyright"
"OpenStreetMap and contributors"
"attribution"
"http://www.openstreetmap.org/copyright"
"license"
"http://opendatacommons.org/licenses/odbl/1-0/"
"changeset"
"id"
10
"created_at"
"2005-05-01T16:09:37Z"
"open"
false
"comments_count"
"changes_count"
10
"created_count"
"modified_count"
"deleted_count"
"closed_at"
"2005-05-01T17:16:44Z"
"min_lat"
59.9513092
"min_lon"
10.7719727
"max_lat"
59.9561501
"max_lon"
10.7994537
"uid"
24
"user"
"Petter Reinholdtsen"
"comments"
"id"
836447
"visible"
true
"date"
"2022-03-22T20:58:30Z"
"uid"
15079200
"user"
"Ethan White of Cheriton"
"text"
"wow no one have said anything here 3/22/2022\n"
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
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.
"comment"
v=
"Just adding some streetnames and a restaurant"
/>
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
application/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
application/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.
There is a
separate call
to get only information about the changeset itself
Expand Bounding Box:
POST /api/0.6/changeset/#id/expand_bbox
(deprecated, gone)
Note: This endpoint was removed in December 2019. See this
GitHub issue
Query:
GET /api/0.6/changesets
This is an API method for getting a list of changesets. It supports filtering 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
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.
This call returns changesets matching criteria, ordered by their creation time. The default ordering is newest first, but you can specify
order=oldest
to reverse the sort order
. Reverse ordering cannot be combined with
time
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. Compare with
from=T1
which filters by creation time instead.
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.
from=T1 [& to=T2]
Find changesets
created
at or after T1, and (optionally) before T2.
to
requires
from
, but not vice-versa. If
to
is provided alone, it has no effect.
open=true
Only finds changesets that are still
open
but excludes changesets that are closed or have reached the element limit for a changeset (10.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
order=[newest|oldest]
If
newest
(default), sort newest changesets first. If
oldest
, reverse order.
limit=N
Specifies the maximum number of changesets returned. A number between 1 and the maximum limit value (currently 100). If omitted, the default limit value is used (currently 100). The actual maximum and default limit values can be found with
a capabilities request
Time format:
Anything that
Time.parse
Ruby function
will parse.
Response
Returns a list of all changeset ordered by creation date. The
element may be empty if there were no results for the query. The response is sent with a content type of
application/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
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
application/xml
) is returned in the following format
"OpenStreetMap Server"
version=
"0.6"
old_id=
"#"
new_id=
"#"
new_version=
"#"
/>
...
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
new ID
or
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 (this will occur for circular relation references)
HTTP status code 404 (Not Found)
When no changeset with the given id could be found
Or when the diff contains elements that could not be found for the given id
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
HTTP status code 413 (Payload too large/Content too large)
If, while uploading, the permitted bounding box size is exceeded, an error "
Changeset bounding box size limit exceeded.
" is returned.
HTTP status code 429 (Too many requests)
When the request has been blocked due to rate limiting
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.
Refer to
/api/capabilities
-->
changesets
->
maximum_elements
for the maximum number of changes permitted in a changeset.
There is currently no limit in the diff size on the Rails port. CGImap limits diff size to 50MB (uncompressed size).
Forward referencing of placeholder ids is not permitted and will be rejected by the API.
Changeset summary
The procedure for successful creation of a changeset is summarized in the following picture.
Note that the picture demonstrates single object operations to create/update/delete elements as per API 0.5. For performance reasons, API users are advised to use the API 0.6 diff upload endpoint instead.
Changeset discussion
Changeset discussions were added 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:
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
Notes
requires either
write_api
or
write_changeset_comments
OAuth scope
Subscribe:
POST /api/0.6/changeset/#id/subscription
Also available at
POST /api/0.6/changeset/#id/subscribe
(deprecated)
Subscribe to the discussion of a changeset to receive notifications for new comments.
URL:
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:
DELETE /api/0.6/changeset/#id/subscription
Also available at
POST /api/0.6/changeset/#id/unsubscribe
(deprecated)
Unsubscribe from the discussion of a changeset to stop receiving notifications.
URL:
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
Search changeset comments:
GET /api/0.6/changeset_comments
Returns changeset comments that match the specified query. If no query is provided, the most recent changeset comments are returned.
URL:
Parameters
Parameter
Description
Allowed values
Default value
display_name
Search for changeset comments created by the given user.
String; User display name
none, optional parameter
user
Same as
display_name
, but search based on user id instead of display name. When both options are provided,
display_name
takes priority.
Integer; User id
none, optional parameter
from
Beginning date range.
Date; Preferably in
ISO 8601
format
none, optional parameter
to
End date range. Only works when
from
is supplied.
Date; Preferably in
ISO 8601
format
none, optional parameter
Examples
See the latest changeset comments globally:
Search for changeset comments by a specific user:
Search for changeset comments between January 1st and January 2nd, 2015:
Error codes
HTTP status code 400 (Bad Request)
When any of the limits are crossed
Hide changeset comment:
DELETE /api/0.6/changeset_comments/#id/visibility
Also available at
POST /api/0.6/changeset/comment/#comment_id/hide
(deprecated)
Sets visible flag on changeset comment to false.
URL:
Return type:
application/xml
This request needs to be done as an authenticated user with moderator role.
Note that the changeset comment id differs from the changeset id.
Error codes
HTTP status code 403 (Forbidden)
if the user is not a moderator
HTTP status code 404 (Not Found)
if the changeset comment id is unknown
Notes
requires either
write_api
or
write_changeset_comments
OAuth scope
Unhide changeset comment:
POST /api/0.6/changeset_comments/#id/visibility
Also available at
POST /api/0.6/changeset/comment/#comment_id/unhide
(deprecated)
Sets visible flag on changeset comment to true.
URL:
Return type:
application/xml
This request needs to be done as an authenticated user with moderator role.
Note that the changeset comment id differs from the changeset id.
Error codes
HTTP status code 403 (Forbidden)
if the user is not a moderator
HTTP status code 404 (Not Found)
if the changeset comment id is unknown
Notes
requires either
write_api
or
write_changeset_comments
OAuth scope
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:
POST /api/0.6/[nodes|ways|relations]
Also available at
PUT /api/0.6/[node|way|relation]/create
(deprecated)
Creates a new element of the specified type. Note that the entire request should be wrapped in a
element.
A Node:
"12"
lat=
"..."
lon=
"..."
"note"
v=
"Just a node"
/>
...
A Way:
"12"
"note"
v=
"Just a way"
/>
...
"123"
/>
"4345"
/>
...
A Relation:
"12"
"note"
v=
"Just a relation"
/>
...
"node"
role=
"stop"
ref=
"123"
/>
"way"
ref=
"234"
/>
If multiple elements are provided only the first is created. The rest is discarded (this behavior 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}
HTTP status code 429 (Too many requests)
When the request has been blocked due to rate limiting
Notes
This updates the bounding box of the changeset.
The
role
attribute for relations is optional. An empty string is the default.
To avoid performance issues when uploading multiple objects, the use of the
Diff upload
endpoint is highly recommended.
Read:
GET /api/0.6/[node|way|relation]/#id
Returns the XML representation of the element.
Response XML
GET /api/0.6/[node|way|relation]/#id
XML representing the element, wrapped in an
element:
"123"
lat=
"..."
lon=
"..."
version=
"142"
changeset=
"12"
user=
"fred"
uid=
"123"
visible=
"true"
timestamp=
"2005-07-30T14:27:12Z"
"note"
v=
"Just a node"
/>
...
Response JSON
GET /api/0.6/[node|way|relation]/#id.json
JSON representing the element, wrapped in an
element:
"version"
"0.6"
"elements"
"type"
"node"
"id"
4326396331
"lat"
31.9016302
"lon"
-81.5990471
"timestamp"
"2016-07-31T00:08:11Z"
"version"
"changeset"
41136027
"user"
"maven149"
"id"
136601
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, it
must match
the current version of the element in the database.
This example is an update of the node 4326396331, updating the version 1 to alter existing tags. This change is made while the changeset with id 188021 is still open:
"188021"
id=
"4326396331"
lat=
"50.4202102"
lon=
"6.1211032"
version=
"1"
visible=
"true"
"foo"
v=
"barzzz"
/>
Example for way 22935194 adding a new key zoning_code with value B. Remember that when making the PUT to an existing way, you need to add all existing tags (excluded here some for brevity) and the same version as the version from OSM
"22935194"
changeset=
"152700179"
version=
"9"
"highway"
v=
"residential"
/>
"zoning_code"
v=
"B"
/>
"name"
v=
"Strada Desseanu"
/>
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. (Example: Version is required when updating) 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
HTTP status code 409 (Conflict) -
text/plain
When the version of the provided element does not match the current database version of the element
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}
HTTP status code 429 (Too many requests)
When the request has been blocked due to rate limiting
Notes
This updates the bounding box of the changeset.
To avoid performance issues when updating multiple objects, the use of the
Diff upload
endpoint is highly recommended. This is also the only way to ensure that multiple objects are updated in a single database transaction.
If you can't use the Diff upload and plan to update more items, mind to do it sequentially (not in parallel)
Delete:
DELETE /api/0.6/[node|way|relation]/#id
Expects a valid XML representation of the element to be deleted.
For example:
"..."
version=
"..."
changeset=
"..."
lat=
"..."
lon=
"..."
/>
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/lon 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 separated by commas. Note that the Rails API and CGIMAP have inconsistent behaviour wrt the plural "s".
HTTP status code 429 (Too many requests)
When the request has been blocked due to rate limiting
Notes
In earlier API versions no payload was required. It is needed now because of the need for changeset IDs and version numbers.
To avoid performance issues when updating multiple objects, the use of the Diff upload endpoint is highly recommended. This is also the only way to ensure that multiple objects are updated in a single database transaction.
History:
GET /api/0.6/[node|way|relation]/#id/history
Retrieves all old versions of an element, sorted by version number from oldest to newest. (
example
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 (Currently supported only in CGImap, used on osm.org
[1]
GitHub
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 or its requested version was redacted, 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 (tested to be > 8207 characters in the URI, or > 725 elements for 10 digit IDs when not specifying versions)
Notes
As the multi fetch call returns deleted objects it is the practical way to determine the version at which an object was deleted (useful for example for conflict resolution), the alternative to using this would be the history call that however may potentially require 1000's of version to be processed.
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
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
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 originally 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)
requires
write_redactions
OAuth scope; before September 2024 required either
write_api
or
write_redactions
, and before December 2023 required
write_api
; those older scope requirements may still be around on other openstreetmap-website-based servers such as
OpenHistoricalMap
the #redaction_id is listed on
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
In violation of the
GPX standard
when downloading public GPX traces through the API, all waypoints of non-trackable traces are randomized (or rather sorted by lat/lon) and delivered as one trackSegment for privacy reasons. Trackable traces are delivered, sorted by descending upload time, before the waypoints of non-trackable traces.
Get GPS Points: Get /api/0.6/trackpoints?bbox=
left
bottom
right
top
&page=
pageNumber
Use this to retrieve the GPS track points that are inside a given bounding box (formatted in a GPX format).
where:
left
is the longitude of the left (westernmost) side of the bounding box.
bottom
is the latitude of the bottom (southernmost) side of the bounding box.
right
is the longitude of the right (easternmost) side of the bounding box.
top
is the latitude of the top (northernmost) side of the bounding box.
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.
The maximal width (right - left) and height (top - bottom) of the bounding box is 0.25 degree.
Examples
Retrieve the first 5,000 points for a bounding box:
Retrieve the next 5,000 points (points 5,001–10,000) for the same bounding box:
Response
This response is NOT wrapped in an OSM xml parent element.
The file format is GPX Version 1.0 which is not the current version. Verify that your tools support it.
"1.0"
creator=
"OpenStreetMap.org"
xmlns=
"http://www.topografix.com/GPX/1/0"
20190626.gpx
Footpaths
near
Blackweir
Pond,
Epping
Forest
"51.6616100"
lon=
"0.0534560"
...
...
...
Create:
POST /api/0.6/gpx
Also available at
POST /api/0.6/gpx/create
(deprecated)
Use this to upload a GPX file or archive of GPX files. Requires authentication.
The following parameters are required 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 (
), 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. Cannot be empty. Maximum length is 255 characters.
tags
A string containing tags for the trace. Can be empty.
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
Response:
A number representing the ID of the new gpx
Error codes
HTTP status code 400 (Bad Request)
When the description is empty
Update:
PUT /api/0.6/gpx/#id
Use this to update the metadata of a GPX file. Only usable by the owner account. Requires authentication. The request body is an xml file with the same structure as the responses of
Download Metadata
The response body will be empty.
Delete:
DELETE /api/0.6/gpx/#id
Use this to delete a GPX file. Only usable by the owner account. Requires authentication.
The response body will be empty.
Download Metadata:
GET /api/0.6/gpx/#id
Also available at
GET /api/0.6/gpx/#id/details
(deprecated)
Use this to access the metadata about a GPX file. Available without authentication if the file is marked public. Otherwise only usable by the owner account and requires authentication.
Example "details" response:
"0.6"
generator=
"OpenStreetMap server"
"836619"
name=
"track.gpx"
lat=
"52.0194"
lon=
"8.51807"
uid=
"1234"
user=
"Hartmut Holzgraefe"
visibility=
"public"
pending=
"false"
timestamp=
"2010-10-09T09:24:19Z"
PHP
upload
test
test
php
Note: the
uid
attribute was added in
September 2023
GitHub
This API call also supports a JSON response.
Download Data:
GET /api/0.6/gpx/#id/data
Use this to download the full GPX file. Available without authentication if the file is marked public. Otherwise only usable by the owner account and requires authentication.
The response will always be a GPX format file if you use a
.gpx
URL suffix, a XML file in an undocumented format if you use a
.xml
URL suffix, otherwise the response will be the exact file that was uploaded.
NOTE: if you request refers to a multi-file archive the response when you force gpx or xml format will consist of a non-standard simple concatenation of the files.
List:
GET /api/0.6/user/gpx_files
Use this to get a list of GPX traces owned by the authenticated user: Requires authentication.
Note that
/user/
is a literal part of the URL, not a user's display name or user id. (This call always returns GPX traces for the current authenticated user
only
.)
The response is similar to the one of
Download Metadata
, except with multiple possible
elements. Example:
"0.6"
generator=
"OpenStreetMap server"
"836619"
name=
"track.gpx"
lat=
"52.0194"
lon=
"8.51807"
uid=
"1234"
user=
"Hartmut Holzgraefe"
visibility=
"public"
pending=
"false"
timestamp=
"2010-10-09T09:24:19Z"
PHP
upload
test
test
php
"836620"
name=
"track.gpx"
lat=
"52.1194"
lon=
"8.61807"
uid=
"1234"
user=
"Hartmut Holzgraefe"
visibility=
"public"
pending=
"false"
timestamp=
"2010-10-09T09:27:31Z"
PHP
upload
test
test
php
This API call also supports a JSON response.
Methods for user data
Details of a user:
GET /api/0.6/user/#id
This API method was added in September 2012 (
code
).
You can get the home location and the displayname of the user, by using
Response XML
GET /api/0.6/user/#id
this returns for example
"0.6"
generator=
"OpenStreetMap server"
"12023"
display_name=
"jbpbis"
account_created=
"2007-08-16T01:35:56Z"
bitbetter
GmbH
"mastodon"
"false"
/>
"http://www.gravatar.com/avatar/somehash"
/>
"1"
/>
"0"
/>
"0"
active=
"0"
/>
"68"
active=
"45"
/>
Response JSON
GET /api/0.6/user/#id.json
"version"
"0.6"
"generator"
"OpenStreetMap server"
"user"
"id"
12023
"display_name"
"jbpbis"
"account_created"
"2007-08-16T01:35:56Z"
"description"
""
"company"
"MyCompany Ltd."
"social_links"
"url"
"https://mastodon.social/@jbpbis"
"platform"
"mastodon"
],
"contributor_terms"
"agreed"
false
},
"img"
"href"
"https://www.gravatar.com/avatar/somehash"
},
"roles"
[],
"changesets"
"count"
},
"traces"
"count"
},
"blocks"
"received"
"count"
"active"
or an empty file if no user found for given identifier.
Note that user accounts which made edits may be deleted. Such users are listed at
Details of multiple users:
GET /api/0.6/users?users=#id1,#id2,...,#idn
This API method was added in July 2018 (
code
).
You can get the details of a number of users via
Response XML
GET /api/0.6/users?users=#id1,#id2,...,#idn
this returns for example
"0.6"
generator=
"OpenStreetMap server"
"12023"
display_name=
"jbpbis"
account_created=
"2007-08-16T01:35:56Z"
"false"
/>
"http://www.gravatar.com/avatar/c8c86cd15f60ecca66ce2b10cb6b9a00.jpg?s=256&d=http%3A%2F%2Fwww.openstreetmap.org%2Fassets%2Fusers%2Fimages%2Flarge-39c3a9dc4e778311af6b70ddcf447b58.png"
/>
"1"
/>
"0"
/>
"0"
active=
"0"
/>
"210447"
display_name=
"siebh"
account_created=
"2009-12-20T10:11:42Z"
"true"
/>
"267"
/>
"1"
/>
"0"
active=
"0"
/>
Response JSON
GET /api/0.6/users.json?users=#id1,#id2,...,#idn
"version"
"0.6"
"generator"
"OpenStreetMap server"
"users"
"user"
"id"
12023
"display_name"
"jbpbis"
"account_created"
"2007-08-16T01:35:56Z"
"description"
""
"contributor_terms"
"agreed"
False
},
"roles"
[],
"changesets"
"count"
},
"traces"
"count"
},
"blocks"
"received"
"count"
"active"
}}}},
"user"
"id"
210447
"display_name"
"siebh"
"account_created"
"2009-12-20T10:11:42Z"
"description"
""
"contributor_terms"
"agreed"
True
},
"roles"
[],
"changesets"
"count"
363
},
"traces"
"count"
},
"blocks"
"received"
"count"
"active"
}}}}
or an empty file if no user found for given identifier.
Note: Since
Pull request 4203 (deployed on August 26 2023)
, both XML and JSON based variants of the users endpoint will skip any non-existing/suspended/deleted users, rather than reporting a previously undocumented HTTP 404 error.
Details of the logged-in user:
GET /api/0.6/user/details
You can get the home location and the displayname of the user, by using
Response XML
GET /api/0.6/user/details
this returns an XML document of the from
"0.6"
generator=
"OpenStreetMap server"
"Max Muster"
account_created=
"2006-07-21T19:28:26Z"
id=
"1234"
"true"
pd=
"true"
/>
"https://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"
/>
"4182"
/>
"513"
/>
"0"
active=
"0"
/>
"49.4733718952806"
lon=
"8.89285988577866"
zoom=
"3"
/>
The
description
of
your
profile
de-DE
de
en-US
en
"1"
unread=
"0"
/>
"0"
/>
Response JSON
GET /api/0.6/user/details.json
this returns an JSON document of the from
"version"
"0.6"
"generator"
"OpenStreetMap server"
"user"
"id"
1234
"display_name"
"Max Muster"
"account_created"
"2006-07-21T19:28:26Z"
"description"
"The description of your profile"
"contributor_terms"
"agreed"
True
"pd"
True
},
"img"
"href"
"https://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"
},
"roles"
[],
"changesets"
"count"
4182
},
"traces"
"count"
513
},
"blocks"
"received"
"count"
"active"
}},
"home"
"lat"
49.4733718952806
"lon"
8.89285988577866
"zoom"
},
"languages"
"de-DE"
"de"
"en-US"
"en"
],
"messages"
"received"
"count"
"unread"
},
"sent"
"count"
}}
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:
GET|PUT|DELETE /api/0.6/user/preferences
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. For an overview of applications using the preferences-API and which key-schemes they use, see
this wiki page
You can retrieve the list of current preferences using
Response XML
GET /api/0.6/user/preferences
this returns an XML document of the form
"0.6"
generator=
"OpenStreetMap server"
"somekey"
v=
"somevalue"
/>
...
Response JSON
GET /api/0.6/user/preferences.json
this returns an JSON document of the form
"version"
"0.6"
"generator"
"OpenStreetMap server"
"preferences"
"somekey"
"somevalue, ...}
PUT /api/0.6/user/preferences
The same structure in the body of the a PUT will upload preferences. All existing preferences are replaced by the newly uploaded set.
GET /api/0.6/user/preferences/[your_key] (without the brackets)
Returns a string with that preference's value.
PUT /api/0.6/user/preferences/[your_key] (without the brackets)
Will set a single preference's value to a string passed as the content of the request.
PUT /api/0.6/user/preferences/[your_key]
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.
A single preference entry can be deleted with
DELETE /api/0.6/user/preferences/[your_key]
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 ). As this was intended as a compatible replacement for the
OpenStreetBugs
API there are numerous idiosyncrasies relative to how the other parts of the OSM API work.
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.
Note:
the XML format returned by the API is different from the, equally undocumented, format used for "osn" format files, available from
planet.openstreetmap.org
, and as output from JOSM and Vespucci.
URL:
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
, 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
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.
see
capabilities
and
this line in settings
for the current value
2.0
2.1
may change, see
capabilities
for current value
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.
The comment properties [uid, user, user_url] will be omitted if the comment was anonymous.
Response XML
GET /api/0.6/notes
"0.6"
generator=
"OpenStreetMap server"
copyright=
"OpenStreetMap and contributors"
attribution=
"https://www.openstreetmap.org/copyright"
license=
"https://opendatacommons.org/licenses/odbl/1-0/"
"0.1000000"
lat=
"51.0000000"
16659
2019-06-15
08:26:04
UTC
open
2019-06-15
08:26:04
UTC
1234
userName
opened
ThisIsANote
<
>
ThisIsANote
<
/p
>
...
...
Response JSON
GET /api/0.6/notes.json
"type"
"FeatureCollection"
"features"
"type"
"Feature"
"geometry"
"type"
"Point"
"coordinates"
0.1000000
51.0000000
]},
"properties"
"id"
16659
"url"
"https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659.json"
"comment_url"
"https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/comment.json"
"close_url"
"https://master.apis.dev.openstreetmap.org/api/0.6/notes/16659/close.json"
"date_created"
"2019-06-15 08:26:04 UTC"
"status"
"open"
"comments"
"date"
"2019-06-15 08:26:04 UTC"
"uid"
1234
"user"
"userName"
"user_url"
"https://master.apis.dev.openstreetmap.org/user/userName"
"action"
"opened"
"text"
"ThisIsANote"
"html"
"
},
...
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:
xml
json
Return type:
application/xml
Error codes
HTTP status code 404 (Not Found)
When no note with the given id could be found. This should only be returned for not yet existing notes.
HTTP status code 410 (Gone)
When the note has been hidden by a moderator. Note that the error message "The note with the id nnnnnnnnn has already been deleted" is misleading, as it isn't actually possible for non-moderators to delete/hide Notes via the API.
Create a new note:
POST /api/0.6/notes
XML
URL:
use Postman or similar tools to test the endpoint - note that it must be a POST request
Return type:
application/xml
An XML-file with the details of the note will be returned
JSON
URL:
Body content
{"lat":51.00, "lon": 0.1&, "text":"This is a note\n\nThis is another line"}
Return type:
application/json
A JSON-file with the details of the note will be returned
Parameters
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. If the OAuth access token used does not have the
allow_write_notes
permission, it is created as an anonymous note instead.
Error codes
HTTP status code 400 (Bad Request)
if the text field was not present
HTTP status code 404 (Not found)
This applies, if the request is not a HTTP POST request
HTTP status code 405 (Method Not Allowed)
If the request is not a HTTP POST request
Create a new comment:
POST /api/0.6/notes/#id/comment
Add a new comment to note #id
URL:
use Postman or similar tools to test the endpoint - note that it must be a POST request
Return type:
application/xml
Since 28 August 2019, this request needs to be done as an authenticated user.
The response will contain the XML of note.
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. This should only happen for not yet existing notes.
This also applies, if the request is not a HTTP POST request
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
HTTP status code 410 (Gone)
When the note has been hidden by a moderator. Note that the error message "The note with the id nnnnnnnnn has already been deleted" is misleading, as it isn't actually possible for non-moderators to delete (hide) Notes via the API.
Close:
POST /api/0.6/notes/#id/close
Close a note as fixed.
URL:
use Postman or similar tools to test the endpoint - note that it must be a POST request
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. This should only happen for not yet existing notes.
This also applies, if the request is not a HTTP POST request
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
HTTP status code 410 (Gone)
When the note has been hidden by a moderator. Note that the error message "The note with the id nnnnnnnnn has already been deleted" is misleading, as it isn't actually possible for a non-moderator to delete/hide Notes via the API.
Reopen:
POST /api/0.6/notes/#id/reopen
Reopen a closed note.
URL:
use Postman or similar tools to test the endpoint
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
This also applies, if the request is not a HTTP POST request
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
Hide:
DELETE /api/0.6/notes/#id
Hide (delete) a note.
URL:
use Postman or similar tools to test the endpoint
Return type:
application/xml
This request needs to be done as an authenticated user with moderator role.
Use
Reopen
request to make the note visible again.
Error codes
HTTP status code 403 (Forbidden)
if the user is not a moderator
HTTP status code 404 (Not Found)
When no note with the given id could be found
HTTP status code 410 (Gone)
When hiding a note that is already hidden
Subscribe:
POST /api/0.6/notes/#id/subscription
Subscribe to the discussion of a note to receive notifications for new comments.
URL:
Return type:
(empty response)
This request needs to be done as an authenticated user.
Error codes
HTTP status code 404 (Not Found)
if the note doesn't exist
HTTP status code 409 (Conflict)
if the user is already subscribed to this note
Unsubscribe:
DELETE /api/0.6/notes/#id/subscription
Unsubscribe to the discussion of a note.
URL:
Return type:
(empty response)
This request needs to be done as an authenticated user.
Error codes
HTTP status code 404 (Not Found)
if the note doesn't exist or the user is not subscribed to this note
Search for notes:
GET /api/0.6/notes/search
Returns notes that match the specified query. If no query is provided, the most recently updated notes are returned.
The result can be encoded in several different formats (XML, RSS, JSON, or GPX), depending on the file extension provided.
URL:
Parameter
Description
Allowed values
Default value
Text search query, matching either note text or comments.
String
none, optional parameter
limit
Maximum number of results.
Integer between 1 and 10000
100
closed
Maximum number of days a note has been closed for.
Number; Value of 0 returns only open notes, Negative numbers return all notes
display_name
Search for notes which the given user interacted with.
String; User display name
none, optional parameter
user
Same as
display_name
, but search based on user id instead of display name. When both options are provided,
display_name
takes priority.
Integer; User id
none, optional parameter
bbox
Search area.
Bounding box
; Area of at most 25 square degrees
none, optional parameter
from
Beginning date range for
created_at
or
updated_at
(specified by
sort
).
Date; Preferably in
ISO 8601
format
none, optional parameter
to
End date range for
created_at
or
updated_at
(specified by
sort
). Only works when
from
is supplied.
Date; Preferably in
ISO 8601
format
none, optional parameter
sort
Sort results by creation or update date.
created_at
or
updated_at
created_at
order
Sorting order.
oldest
is ascending order,
newest
is descending order.
oldest
or
newest
newest
1.0
1.1
may change, see
capabilities
for the current value
see
capabilities
and
this line in settings
for the current value
Examples
See latest note updates globally:
Search for a text in comments:
See notes of a single user:
Search for oldest notes near Null Island:
Error codes
HTTP status code 400 (Bad Request)
When any of the limits are crossed
RSS Feed:
GET /api/0.6/notes/feed
Gets an RSS feed for notes within an area.
URL:
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
[2]
, not overlapping the dateline.
none, optional parameter
User Blocks
Create:
POST /api/0.6/user_blocks
Parameters
Parameter
Description
Allowed values
Default value
user
Blocked user id
Integer; User id
No default, needs to be specified
reason
Reason for block shown to the blocked user
Markdown text
No default, needs to be specified
period
Block duration in hours
Integer between 0 and maximum block period, currently 87660
No default, needs to be specified
needs_view
Whether the user is required to view the block page for the block to be lifted
true
None, optional parameter
Error codes
HTTP status code 400 (Bad Request)
When any of the required parameters is missing or has invalid value
HTTP status code 404 (Not found)
When blocked user is not found
Read:
GET /api/0.6/user_blocks/#id
Response XML
GET /api/0.6/user_blocks/#id
"0.6"
generator=
"OpenStreetMap server"
copyright=
"OpenStreetMap and contributors"
attribution=
"http://www.openstreetmap.org/copyright"
license=
"http://opendatacommons.org/licenses/odbl/1-0/"
"96"
created_at=
"2025-01-21T23:23:50Z"
updated_at=
"2025-01-21T23:24:16Z"
ends_at=
"2025-01-21T23:24:16Z"
needs_view=
"false"
"3"
user=
"fakeuser1"
/>
"5"
user=
"fakemod1"
/>
"5"
user=
"fakemod1"
/>
reason
text
more
reason
text
Response JSON
GET /api/0.6/user_blocks/#id.json
"version"
"0.6"
"generator"
"OpenStreetMap server"
"copyright"
"OpenStreetMap and contributors"
"attribution"
"http://www.openstreetmap.org/copyright"
"license"
"http://opendatacommons.org/licenses/odbl/1-0/"
"user_block"
:{
"id"
96
"created_at"
"2025-01-21T23:23:50Z"
"updated_at"
"2025-01-21T23:24:16Z"
"ends_at"
"2025-01-21T23:24:16Z"
"needs_view"
false
"user"
:{
"uid"
"user"
"fakeuser1"
},
"creator"
:{
"uid"
"user"
"fakemod1"
},
"revoker"
:{
"uid"
"user"
"fakemod1"
},
"reason"
"reason text\r\n\r\nmore reason text"
List active blocks:
GET /api/0.6/user/blocks/active
Allows the applications to check if the currently authorized user is blocked.
This endpoint is accessible even with an active block, unlike some other endpoints requiring authorization.
Response XML
GET /user/blocks/active
"0.6"
generator=
"OpenStreetMap server"
copyright=
"OpenStreetMap and contributors"
attribution=
"http://www.openstreetmap.org/copyright"
license=
"http://opendatacommons.org/licenses/odbl/1-0/"
"101"
created_at=
"2025-02-22T02:11:55Z"
updated_at=
"2025-02-22T02:11:55Z"
ends_at=
"2025-02-22T03:11:55Z"
needs_view=
"true"
"5"
user=
"fakemod1"
/>
"115"
user=
"fakemod2"
/>
"100"
created_at=
"2025-02-22T02:11:10Z"
updated_at=
"2025-02-22T02:11:10Z"
ends_at=
"2025-02-22T02:11:10Z"
needs_view=
"true"
"5"
user=
"fakemod1"
/>
"115"
user=
"fakemod2"
/>
...
Empty
Response JSON
GET /user/blocks/active.json
"version"
"0.6"
"generator"
"OpenStreetMap server"
"copyright"
"OpenStreetMap and contributors"
"attribution"
"http://www.openstreetmap.org/copyright"
"license"
"http://opendatacommons.org/licenses/odbl/1-0/"
"user_blocks"
:[
"id"
101
"created_at"
"2025-02-22T02:11:55Z"
"updated_at"
"2025-02-22T02:11:55Z"
"ends_at"
"2025-02-22T03:11:55Z"
"needs_view"
true
"user"
:{
"uid"
"user"
"fakemod1"
},
"creator"
:{
"uid"
115
"user"
"fakemod2"
},
"id"
100
"created_at"
"2025-02-22T02:11:10Z"
"updated_at"
"2025-02-22T02:11:10Z"
"ends_at"
"2025-02-22T02:11:10Z"
"needs_view"
true
"user"
:{
"uid"
"user"
"fakemod1"
},
"creator"
:{
"uid"
115
"user"
"fakemod2"
},
...
Empty
user_blocks
array indicates no active blocks.
When
NOT
to use the API
For bulk upload scripts or data modification, the direct API use 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
Semantic versioning
At the time of first deployment, semantic versioning (with a minor version number) wasn't an established concept. As a result, the API doesn't follow this scheme. Many applications wouldn't be able to handle minor version number changes correctly, thus no attempt is made to add it, although the current version can be thought of as being 0.6.9.
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
Category:OSM API library
- libraries or language wrappers for some or all of the OpenStreetMap API, potentially useful for people writing editors
References
- see the current state at
"
Retrieved from "
Category
OSM API
Hidden categories:
Pages unavailable in French
Pages unavailable in Italian
Pages unavailable in Dutch
Translate to German
Translate to Spanish
Navigation menu