This page describes a historic artifact in the history of OpenStreetMap. It does not reflect the current situation, but instead documents the historical concepts, issues, or ideas.

Historical Interest Only. Version 0.4 no longer in use

This document describes OSM API v0.4 which is no longer in use. We stopped using version 0.4 in October 2007. See the API page for a link to the currently active protocol specifications.

OSM API Version 0.4

In order to keep the specification unambiguous, this specification uses terms shall, may and can in line with the IEEE Style Guide.

The OSM API is based on the HTTP-Protocol. Please have a look at the corresponding OSM document HTTP Protocol Specification.

The RESTful API

This Protocol is based on the ideas of the RESTful API. For more information on RESTful APIs see wikipedia's Representational State Transfer page.

As this protocol described below, the REST APIs uses HTTP-Methods like GET_request, PUT and DELETE in conjunction with XML payload send to URLs.

Protocol Roles

This OSM Protocol currently has two different protocol protocol roles.

OSM client
OSM server

OSM Protocol role client

The OSM client sends request messages to the OSM server.

Examples of OSM clients are:

JOSM
Potlatch and the old Java Applet
Tiles@home client (read-only)
Coastline import script (write-only)

OSM Protocol role server

Upon reception of a request from the OSM client, the OSM server shall answer with a response message.

Examples of OSM servers are:

https://api.openstreetmap.org/api/0.4/

Transport

The OSM Protocol Version 0.4 uses the URL of the HTTP-request to transport data from the OSM client to the OSM server. It uses HTTP/1.1 commands to transfer data between the OSM client and the OSM server.

General HTTP-Transport format

According to RFC 2616 the HTTP URLs have the following format:

http_URL = "http:"  "//" host [ ":" port ] [ abs_path ["?" query ]]


Where the content with brackets [ ] is optional.

OSM specific HTTP-Transport format configuration

When the HTTP-Transport is used in conjunction with the OSM-Protocol, the absolute path ('abs_path') is split into an identifier of the OSM Protocol Version e.g. "api/0.3" or "api/0.4" and the OSM_Protocol_Command separated by a slash "/".

When HTTP is used as transport for the OSM protocol, the URL is shall be created from the OSM_Protocol_Version, the OSM_Protocol_Command and the optional OSM_Command_Parameters as following:

http_URL = OSM_Protocol_Version OSM_Protocol_Command ["?" OSM_Command_Parameters]


Where:
OSM_Protocol_Version:
  Specifies the used OSM Protocol Version and shall for the OSM Protocol Version 0.4
  always be defined as "/api/0.4".


OSM_Protocol_Command:
  Specifies the OSM Command to be executed at the OSM Server.


OSM_Command_Parameters:
  Specifies the OSM Command Parameters to be passed with the OSM Command to the OSM Server. 
  If OSM_Command_Parameters is empty, they shall just be left away. 
  If OSM_Command_Parameters is not empty, the parameters shall become preceded with a "?".

Examples:

/api/0.4/way/search?type=highway&value=motorway


/api/0.4/segment/create

For the OSM Protocol Version 0.4 all applicable commands and their parameters are defined in the following sections.

Used HTTP Methods

The OSM protocol uses the following methods provided by the lower HTTP-protocol layer:

Additionally are prvovided by lower HTTP-protocol layer:

HTTP GET-Method based commands

The following OSM-protocol commands use the HTTP-Method GET provided by the lower HTTP-protocol layer.

Get node by NodeID

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/node/NodeID

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method

get_response_body

GET_response

XML DTD Schema:

<!ELEMENT osm (node)>
<!ATTLIST osm version CDATA #REQUIRED>
<!ATTLIST osm generator CDATA #REQUIRED>

<!ELEMENT node (tag*)>
<!ATTLIST node id CDATA #REQUIRED>
<!ATTLIST node lat CDATA #REQUIRED>
<!ATTLIST node lon CDATA #REQUIRED>
<!ATTLIST node timestamp CDATA #REQUIRED>
<!ATTLIST node user CDATA #IMPLIED>
<!ATTLIST node visible CDATA #IMPLIED>

<!ELEMENT tag EMPTY>
<!ATTLIST tag k CDATA #REQUIRED>
<!ATTLIST tag v CDATA #REQUIRED>

Where NodeID identifies a node and shall be of the type OSMIdentifierType.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	The requested node identified by the given NodeID could be successfully be retrieved.
Bad Request	Not applicable.
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	The node identified by NodeID had never existed.
Gone	The node identified by NodeID had existed, however does no longer exist.
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Example GET_request message:

https://api.openstreetmap.org/api/0.4/node/156804

Example GET_response message:

<?xml version="1.0" encoding="UTF-8"?>

<osm version="0.4" generator="OpenStreetMap server">
 <node id="156804" lat="61.8083953857422" lon="10.8497076034546" visible="true" timestamp="2005-07-30T14:27:12+01:00"/>
</osm>

Get segment by SegmentID

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/segment/SegmentID

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method

get_response_body

GET_response

XML DTD Schema:

<!ELEMENT osm (segment)>
<!ATTLIST osm version CDATA #REQUIRED>
<!ATTLIST osm generator CDATA #REQUIRED>
 
<!ELEMENT segment (tag*)>
<!ATTLIST segment id CDATA #REQUIRED>
<!ATTLIST segment from CDATA #REQUIRED>
<!ATTLIST segment to CDATA #REQUIRED>
<!ATTLIST segment user CDATA #IMPLIED> 
<!ATTLIST segment visible CDATA #IMPLIED>
<!ATTLIST segment timestamp CDATA #REQUIRED>
 
<!ELEMENT tag EMPTY>
<!ATTLIST tag k CDATA #REQUIRED>
<!ATTLIST tag v CDATA #REQUIRED>

Where SegemntID identifies a segment and shall be of the type OSMIdentifierType.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	The requested segment identified by the given SegementID could be successfully be retrieved.
Bad Request	Not applicable.
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	The segment identified by SegmentID had never existed.
Gone	The segment identified by SegmentID had existed, however does no longer exist.
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Example GET_request message:

https://api.openstreetmap.org/api/0.4/segment/156804

Example GET_response message:

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.4" generator="OpenStreetMap server">
  <segment id="156804" from="200542" to="200550" user="blackadder" visible="true" timestamp="2005-11-08T17:28:52+00:00">
    <tag k="name" v="Fire Route"/>
  </segment>
</osm>

Get way history by ID

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/way/WayID/history

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method

get_response_body

GET_response

XML DTD Schema:

<!ELEMENT osm (way+)>
<!ATTLIST osm version CDATA #REQUIRED>
<!ATTLIST osm generator CDATA #REQUIRED>

<!ELEMENT way (seg+, tag*)>
<!ATTLIST way id CDATA #REQUIRED>
<!ATTLIST way visible CDATA #IMPLIED>
<!ATTLIST way timestamp CDATA #REQUIRED>
<!ATTLIST way user CDATA #IMPLIED> 

<!ELEMENT seg EMPTY>
<!ATTLIST seg id CDATA #REQUIRED>

<!ELEMENT tag EMPTY>
<!ATTLIST tag k CDATA #REQUIRED>
<!ATTLIST tag v CDATA #REQUIRED>

Where WayID identifies a way and shall be of the type OSMIdentifierType.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	The requested history of the way identifed by the given WayID could be successfully be retrieved.
Bad Request	Not applicable.
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	The way identified by WayID had never existed.
Gone	Not applicable.
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Example GET_request message:

https://api.openstreetmap.org/api/0.4/way/35/history

Example GET_response message:

<osm version="0.4" generator="OpenStreetMap server">
 <way id="35" visible="true" timestamp="2006-03-14T10:07:23+00:00" user="blackadder">
  <seg id="156804"/>
  <seg id="156805"/>
  <seg id="156806"/>
  <tag k="created_by" v="JOSM"/>
</way>

 <way id="35" visible="true" timestamp="2006-03-14T10:10:44+00:00" user="blackadder">
  <seg id="156804"/>
  <seg id="156805"/>
  <seg id="156806"/>
  <tag k="created_by" v="aj.robinson@blueyonder.co.uk - JOSM"/>
  <tag k="construction" v="paved"/>
  <tag k="type" v="Footway"/>
 </way>

 <way id="35" visible="true" timestamp="2006-03-14T10:17:44+00:00" user="blackadder">
  <seg id="156804"/>
  <seg id="156805"/>
  <seg id="156806"/>
  <tag k="created_by" v="aj.robinson@blueyonder.co.uk - JOSM"/>
  <tag k="id" v="AJR000002"/>
  <tag k="construction" v="paved"/>
  <tag k="type" v="Footway"/>
</way>

Get way by ID

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/way/WayID

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method

get_response_body

GET_response

XML DTD Schema:

<!ELEMENT osm (way)>
<!ATTLIST osm version CDATA #REQUIRED>
<!ATTLIST osm generator CDATA #REQUIRED>

<!ELEMENT way (seg+, tag*)>
<!ATTLIST way id CDATA #REQUIRED>
<!ATTLIST way visible CDATA #IMPLIED>
<!ATTLIST way timestamp CDATA #REQUIRED>
<!ATTLIST way user CDATA #IMPLIED>

<!ELEMENT seg EMPTY>
<!ATTLIST seg id CDATA #REQUIRED>

<!ELEMENT tag EMPTY>
<!ATTLIST tag k CDATA #REQUIRED>
<!ATTLIST tag v CDATA #REQUIRED>

Where WayID identifies a way and shall be of the type OSMIdentifierType.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	The requested way identified by the given WayID could be successfully be retrieved.
Bad Request	Not applicable.
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	The way identified by WayID had never existed.
Gone	The way identified by WayID had existed, however does no longer exist.
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Example GET_request message:

https://api.openstreetmap.org/api/0.4/way/35

Example GET_response message:

<osm version="0.4" generator="OpenStreetMap server">
   <way id="35" visible="true" timestamp="2006-03-22T21:55:13+00:00" user="blackadder">
     <seg id="156804"/>
     <seg id="156805"/>
     <seg id="156806"/>
     <tag k="place_name" v="Sutton Coldfield"/>
     <tag k="highway" v="footway"/>
     <tag k="surface" v="paved"/>
     <tag k="note" v="fire access route"/>
     <tag k="created_by" v="JOSM"/>
   </way>
</osm>

Get ways

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/ways	?ways=id1,id2,id3...

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method

get_response_body

GET_response

XML DTD Schema:

<!ELEMENT osm (way*)>
<!ATTLIST osm version CDATA #REQUIRED>
<!ATTLIST osm generator CDATA #REQUIRED>

<!ELEMENT way (seg+, tag*)>
<!ATTLIST way id CDATA #REQUIRED>
<!ATTLIST way visible CDATA #IMPLIED>
<!ATTLIST way timestamp CDATA #REQUIRED>
<!ATTLIST way user CDATA #IMPLIED>

<!ELEMENT seg EMPTY>
<!ATTLIST seg id CDATA #REQUIRED>

<!ELEMENT tag EMPTY>
<!ATTLIST tag k CDATA #REQUIRED>
<!ATTLIST tag v CDATA #REQUIRED>

Where WayID identifies a way and shall be of the type OSMIdentifierType.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	The requested ways identfied by the given list of WayIDs could be successfully be retrieved. Please clarify what happens when none of the ways identified by the given list of WayIDs could be successfully retrieved. Does error code 'not found' apply then? Please help fixing!!!!!!!!!!!!!!! Please clarify what happens when only some of the ways identified by the given list of WayIDs could be successfully retrieved, however at least one way identified by the list of WayIDs could not be supplied. Is any information provided within the error code or the payload supplied within the Get_response message? Please help fixing!!!!!!!!!!!!!!!
Bad Request	No wayIDs were provided.
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	Not applicable.
Gone	Not applicable.
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Example GET_request message:

https://api.openstreetmap.org/api/0.4/ways?ways=35,38

Example GET_response message:

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.4" generator="OpenStreetMap server">
 <way id="35" visible="true" timestamp="2006-03-22T21:55:13+00:00" user="blackadder">
   <seg id="156804"/>
   <seg id="156805"/>
   <seg id="156806"/>
   <tag k="place_name" v="Sutton Coldfield"/>
   <tag k="highway" v="footway"/>
   <tag k="surface" v="paved"/>
   <tag k="note" v="fire access route"/>
   <tag k="created_by" v="JOSM"/>
 </way>
 <way id="38" visible="true" timestamp="2006-03-16T09:50:36+00:00" user="blackadder">
   <seg id="230688"/>
   <seg id="230689"/>
   <seg id="230690"/>
   <seg id="230691"/>
   <seg id="230693"/>
   <seg id="230694"/>
   <seg id="230696"/>
   <tag k="created_by" v="JOSM"/>
   <tag k="construction" v="paved"/>
   <tag k="place" v="Sutton Coldfield"/>
   <tag k="highway" v="footway"/>
   <tag k="id" v="AJR000003"/>
 </way>
</osm>

Get map

Map is the heart of things here. It will provide a bundle of nodes, line segments, and ways given some bounding box. The XML returned will give you the ways that any of the segments within that bounding box belong to, and (as opposed to protocol version 0.3) will also give you all the segments that those ways own and their nodes, even if these lie outside the given bounding box.

The bounding box is specified in one parameter, bbox, giving the longitude and latitude of the bottom left corner first, then the longitude and latitude of the top right corner.

Note: In the interests of keeping the API snappy, it is restricted to providing data for only moderately sized areas (currently 0.25 deg). If you don't need the very latest data, or if you need lots of data, you should use Planet.osm instead.

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/map	?bbox=bllon,bllat,trlon,trlat

Upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method

get_response_body

GET_response

XML DTD Schema:

<!ELEMENT osm (node+, segment*, way*)>
<!ATTLIST osm version CDATA #REQUIRED>
<!ATTLIST osm generator CDATA #REQUIRED>

<!ELEMENT node (tag*)>
<!ATTLIST node id CDATA #REQUIRED>
<!ATTLIST node lat CDATA #REQUIRED>
<!ATTLIST node lon CDATA #REQUIRED>
<!ATTLIST node timestamp CDATA #REQUIRED>
<!ATTLIST node user CDATA #IMPLIED>
<!ATTLIST node visible CDATA #IMPLIED>
 
<!ELEMENT segment (tag*)>
<!ATTLIST segment id CDATA #REQUIRED>
<!ATTLIST segment from CDATA #REQUIRED>
<!ATTLIST segment to CDATA #REQUIRED>
<!ATTLIST segment user CDATA #IMPLIED> 
<!ATTLIST segment visible CDATA #IMPLIED>
<!ATTLIST segment timestamp CDATA #REQUIRED>

<!ELEMENT way (seg+,tag*)>
<!ATTLIST way id CDATA #REQUIRED>
<!ATTLIST way visible CDATA #IMPLIED>
<!ATTLIST way timestamp CDATA #REQUIRED>
<!ATTLIST way user CDATA #IMPLIED> 

<!ELEMENT seg EMPTY>
<!ATTLIST seg id CDATA #REQUIRED>

<!ELEMENT tag EMPTY>
<!ATTLIST tag k CDATA #IMPLIED>
<!ATTLIST tag v CDATA #REQUIRED>

Method	status_code
GET_response	Bad Request

Where:

Parameter	Type Definition	Description
bllon	OSMlonType	longitude of the bottom left corner of the bounding box (minimum longitude)
bllat	OSMlatType	latitude of the bottom left corner of the bounding box (minimum latitude)
trlon	OSMlonType	longitude of the top right corner of the bounding box (maximum longitude)
trlat	OSMlatType	latitude of the top right corner of the bounding box (maximum latitude)
GMT_Time	OSMDateType	optional, the time to fetch the data for (default is latest data)

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	The map data of the requested bounding box has successfully been retrieved.
Bad Request	If the requested area is too large. The area limit is currently ~0.1 square degrees. If a larger area is needed, please use Planet.osm.
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	applicable? please help fixing!!!
Gone	applicable? please help fixing!!!
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Get map trace examples are found here: Get map trace example

Example GET_request message:

https://api.openstreetmap.org/api/0.4/map?bbox=11.54,48.14,11.543,48.145

Example GET_response message:

GET_response message

Search objects (ways, segments and nodes)

You can search by type, value, or both. This will search the tags on all the objects (nodes, segments and ways)

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	search	type=keyA value=keyB or type=keyA&value=keyB

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_response	tbd.	tbd.

The URL to GET is /search and the parameters are type and value

Example:

/search?type=highway
/search?value=Cambridge
/search?type=railway&value=rail

The response is all the matching nodes, segments and ways

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	applicable? please help fixing!!!
Gone	applicable? please help fixing!!!
Precondition Failed	applicable? please help fixing!!!
Internal Server Error	The server encountered an unexpected problem.

Search nodes

This command is used to search by node type, node value, or both.

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/nodes/search	type=keyA value=keyB or type=keyA&value=keyB

Examples:

The URL to GET is /nodes/search and the parameters are type and value.

eg:

/nodes/search?type=highway
/nodes/search?value=Oxford
/nodes/search?type=place&value=town

If matching nodes are found the OSM server shall respond with a GET_response message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_response	tbd.	tbd.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	applicable? please help fixing!!!
Gone	applicable? please help fixing!!!
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Search segments

You can search by segment type, segment value, or both

This command might be incorrect. Please help fixing it. If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/segments/search	type=keyA value=keyB or type=keyA&value=keyB

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_response	tbd.	tbd.

The URL to GET is /segments/search and the parameters are type and value

Example:

/segments/search?type=highway
/segments/search?value=Oxford Street
/segments/search?type=highway&value=secondary

The response contains the segments that match.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	applicable? please help fixing!!!
Gone	applicable? please help fixing!!!
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Search ways

You can search by way type, node value, or both

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/ways/search	type=keyA value=keyB or type=keyA&value=keyB

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_response	tbd.	tbd.

The URL to GET is /ways/search and the parameters are type and value

Example:

/ways/search?type=highway
/ways/search?value=M1
/ways/search?type=highway&value=motorway

The response contains all matching ways.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	applicable? please help fixing!!!
Gone	applicable? please help fixing!!!
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Get gpx files of the user

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/user/gpx_files

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_response	tbd.	tbd.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	applicable? please help fixing!!!
Gone	applicable? please help fixing!!!
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Create gpx file

Operation purpose is unclear. Is this GET or PUT procedure used for this method. Please fix! If the OSM server receives a POST_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
POST_request	/gpx/create	description, tags, public, file

upon successful command execution, the OSM server shall respond with a POST_response message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
POST_response	tbd.	tbd.

Where:

Parameter	Type Definition	Description
description	OSMTextStringType	Description for GPX file.
tags	OSMTextStringType	Tags to associate with GPX file.
public	OSMTextStringType	Boolean flag to indicate whether file is public or not.
file	OSMTextStringType	GPX file contents.

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	The supplied arguments were not acceptable.
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	Not applicable.
Gone	Not applicable.
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Get GPX file details by ID

This command might be incorrect. Please help fixing it. If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/gpx/NameID/details

upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_response	tbd.	tbd.

Where NameID identifies a filename and shall be of the type OSMIdentifierType

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	If the gpx file identified by NameID has not been found? for all or for this user? please help fixing!!!
Gone	If the gpx file identified by NameID had existed, however does no longer exist? for all or for this user? please help fixing!!!
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Get Trackpoints

The XML returned will give you a page of uploaded track points within the bounding box. Newer points are returned first.

The bounding box is specified in one parameter, bbox, giving the longitude and latitude of the bottom left corner first, then the longitude and latitude of the top right corner.

Results are divided into pages of 5000 points. The zero based page parameter specifies which page of results is required.

If the OSM server receives the GET_request message containing:

Method	OSM_Protocol_Command	OSM_Command_Parameters
GET_request	/trackpoints	?bbox=bllon,bllat,trlon,trlat&page=pagenumber

Upon successful command execution, the OSM server shall respond with a GET_response message containing:

Method

get_response_body

GET_response

<!ELEMENT gpx (trk)>
<!ATTLIST gpx version CDATA #REQUIRED>
<!ATTLIST gpx creator CDATA #REQUIRED>

<!ELEMENT trk (trkseg)>

<!ELEMENT trkseg (trkpt*)>

<!ELEMENT trkpt EMPTY>
<!ATTLIST node lat CDATA #REQUIRED>
<!ATTLIST node lon CDATA #REQUIRED>

Where:

Parameter	Type Definition	Description
bllon	OSMlonType	longitude of the bottom left corner of the bounding box (minimum longitude)
bllat	OSMlatType	latitude of the bottom left corner of the bounding box (minimum latitude)
trlon	OSMlonType	longitude of the top right corner of the bounding box (maximum longitude)
trlat	OSMlatType	latitude of the top right corner of the bounding box (maximum latitude)
page	OSMTrackpointPageType	The zero based page parameter indicating which page of 5000 points required

Example GET_request message:

 https://api.openstreetmap.org/api/0.4/trackpoints?bbox=-1.22,51.86,-1.10,51.97&page=0

Example GET_response message:

<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.0" creator="OpenStreetMap.org" xmlns="http://www.topografix.com/GPX/1/0/">
  <trk>
    <trkseg>
      <trkpt lat="51.896232" lon="-1.148553"/>
      <trkpt lat="51.896255" lon="-1.148459"/>
      <trkpt lat="51.896275" lon="-1.148361"/>
    </trkseg>
  </trk>
</gpx>

Applicable Status Codes of the GET_response message are:

Status Code	Description
OK	The page of track points within the requested bounding box has successfully been retrieved.
Bad Request	If the requested area is too large. The area limit is currently ~0.1 square degrees. If the page parameter is not greater than or equal to 0.
Unauthorized	User authentication of HTTP Protocol failed.
Internal Server Error	The server encountered an unexpected problem.

HTTP PUT-Method based commands

The following OSM-protocol commands use the HTTP-Method PUT provided by the lower HTTP-protocol layer.

Create new node

Method	OSM_Protocol_Command	OSM_Command_Parameters	put_request_body
PUT_request	/node/create		node_payload

upon successful command execution, the OSM server shall respond with a PUT_response message containing:

HTTP Method	HTTP Message-Body
PUT_response	tbd.

Applicable Status Codes of the PUT_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	Not applicable.
Gone	Not applicable.
Precondition Failed	The XML data transported as node_payload contained a NodeID.
Internal Server Error	The server encountered an unexpected problem.

Create new node trace examples are found here: Create new node trace example

Create new segment

Method	OSM_Protocol_Command	OSM_Command_Parameters	put_request_body
PUT_request	/segment/create		segment_payload

upon successful command execution, the OSM server shall respond with a PUT_response message containing:

HTTP Method	HTTP Message-Body
PUT_response	tbd.

Applicable Status Codes of the PUT_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	Not applicable.
Gone	Not applicable.
Precondition Failed	The XML data transported as segment_payload contained a SegmentID. The XML data transported as segment_payload contained less or more than two NodeIDs. The XML data transported as segment_payload contained two identical NodeIDs for segment start and segment end. The XML data transported as segment_payload contained the NodeID of one or more deleted nodes. The XML data transported as segment_payload contained the NodeID of one or more not existing. nodes.
Internal Server Error	The server encountered an unexpected problem.

Create new segment trace examples are found here: Create new segment trace example

Create new way

Method	OSM_Protocol_Command	OSM_Command_Parameters	put_request_body
PUT_request	/way/create		way_payload

upon successful command execution, the OSM server shall respond with a PUT_response message containing:

HTTP Method	HTTP Message-Body
PUT_response	tbd.

Applicable Status Codes of the PUT_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	Not applicable.
Gone	Not applicable.
Precondition Failed	The XML data transported as way_payload contained a WayID. The XML data transported as way_payload contained zero SegmentIDs. The XML data transported as way_payload contained the SegmentID of one or more deleted segments. The XML data transported as way_payload contained the SegmentID of one or more not existing segments.
Internal Server Error	The server encountered an unexpected problem.

Create new way trace examples are found here: Create new way trace example

Store node by ID

Method	OSM_Protocol_Command	OSM_Command_Parameters	put_request_body
PUT_request	/node/NodeID		node_payload

upon successful command execution, the OSM server shall respond with a PUT_response message containing:

HTTP Method	HTTP Message-Body
PUT_response	tbd.

Where NodeID identifies a node and shall be of the type OSMIdentifierType.

Applicable Status Codes of the PUT_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	ID in XML didn't match ID in request
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	Node to update did not exist
Gone	Node to update has been deleted (resurrection is not possible this way)
Precondition Failed	The XML data transported as node_payload contained a NodeID.
Internal Server Error	The server encountered an unexpected problem.

Store segment by ID

Method	OSM_Protocol_Command	OSM_Command_Parameters	put_request_body
PUT_request	/segment/SegmentID		segment_payload

upon successful command execution, the OSM server shall respond with a PUT_response message containing:

HTTP Method	HTTP Message-Body
PUT_response	tbd.

Where SegmentID identifies a segment and shall be of the type OSMIdentifierType.

Applicable Status Codes of the PUT_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	Not applicable.
Gone	Not applicable.
Precondition Failed	The XML data transported as segment_payload contained a SegmentID. The XML data transported as segment_payload contained less or more than two NodeIDs. The XML data transported as segment_payload contained two identical NodeIDs for segment start and segment end. The XML data transported as segment_payload contained the NodeID of one or more deleted nodes. The XML data transported as segment_payload contained the NodeID of one or more not existing. nodes.
Internal Server Error	The server encountered an unexpected problem.

Store way by ID

Method	OSM_Protocol_Command	OSM_Command_Parameters	put_request_body
PUT_request	/way/WayID		way_payload

upon successful command execution, the OSM server shall respond with a PUT_response message containing:

HTTP Method	HTTP Message-Body
PUT_response	tbd.

Where WayID identifies a way and shall be of the type OSMIdentifierType.

Applicable Status Codes of the PUT_response message are:

Status Code	Description
OK	Provide description here. Please help fixing!!!
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	Not applicable.
Gone	Not applicable.
Precondition Failed	The XML data transported as way_payload contained a WayID. The XML data transported as way_payload contained zero SegmentIDs. The XML data transported as way_payload contained the SegmentID of one or more deleted segments. The XML data transported as way_payload contained the SegmentID of one or more not existing segments.
Internal Server Error	The server encountered an unexpected problem.

HTTP DELETE-Method based commands

The following OSM-protocol commands use the HTTP-Method DELETE provided by the lower HTTP-protocol layer.

Delete node by ID

Method	OSM_Protocol_Command	OSM_Command_Parameters
DELETE_response	/node/NodeID

upon successful command execution, the OSM server shall respond with a DELETE_response message containing:

HTTP Method	HTTP Message-Body
DELETE_response	tbd.

Applicable Status Codes of the DELETE_response message are:

Status Code	Description
OK	The node identified by NodeID had been successfully deleted.
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	The node identified by NodeID had never existed.
Gone	The node identified by NodeID had existed, however does not longer exist.
Precondition Failed	The node could not be deleted because it is in use by a segment.
Internal Server Error	The server encountered an unexpected problem.

Delete node by ID trace examples are found here: Delete node by ID trace example

Delete segment by ID

Method	OSM_Protocol_Command	OSM_Command_Parameters
DELETE_response	/segment/SegmentID

upon successful command execution, the OSM server shall respond with a DELETE_response message containing:

HTTP Method	HTTP Message-Body
DELETE_response	tbd.

Applicable Status Codes of the DELETE_response message are:

Status Code	Description
OK	The segment identified by SegmentID had been successfully deleted.
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	The segment identified by SegmentID had never existed.
Gone	The segment identified by SegmentID had existed, however does not longer exist.
Precondition Failed	The segmnet could not be deleted because it is in use by a way.
Internal Server Error	The server encountered an unexpected problem.

Delete segment by ID trace examples are found here: Delete segment by ID trace example. Please help by providing a suitable trace file!!!!

Delete way by ID

Method	OSM_Protocol_Command	OSM_Command_Parameters
DELETE_response	/way/WayID

upon successful command execution, the OSM server shall respond with a DELETE_response message containing:

HTTP Method	HTTP Message-Body
DELETE_response	tbd.

Applicable Status Codes of the DELETE_response message are:

Status Code	Description
OK	The way identified by WayID
Bad Request	applicable? please help fixing!!!
Unauthorized	User authentication of HTTP Protocol failed.
Not Found	The way identified by WayID had never existed.
Gone	The way identified by WayID had existed, however does not longer exist.
Precondition Failed	Not applicable.
Internal Server Error	The server encountered an unexpected problem.

Delete way by ID trace examples are found here: Delete way by ID trace example. Please help by providing a suitable trace file!!!!

Error Text

In the event of an error, the OSM server response will have a status_code set to bad request. In some cases, it will also include an additional HTTP header, Error. Where the HTTP header Error is present, the Error header provides a textual description of the failure.

eg

 HTTP/1.1 400 Bad Request 
 Cache-Control: no-cache
 Connection: Keep-Alive
 Error: The maximum bbox size is 0.25, and your request was too large. Either request a 
 smaller area, or use planet.osm
 Date: Sun, 29 Apr 2007 09:31:51 GMT
 Content-Type: text/xml; charset=utf-8
 Server: WEBrick/1.3.1 (Ruby/1.8.5/2006-08-25)
 Content-Length: 1

Error handling

The OSM Protocol uses the Error Handling of the low HTTP Layer. For more information on Error Handling, please see HTTP Protocol Specification.

Type definitions

StatusCodeType

The status codes are defined by the HTTP Protocol Specification

OSMIdentifierType

The OSMIdentifierType shall be a unsigned 64-Bit Integer.

Encoding (as part of an OSM command):

As decimal number [1 .. ((2^64)-1)]
Leading zeros may be omitted.

Please verify that the above statement is correct!!!

OSMTextStringType

The OSMTextStringTyp shall be a sequence of UTF-8 characters.

Is UTF-8 characters correct or should it be ASCII characters? Please help fixing it.

OSMlonType

The OSMlonType shall be an integer number in the range of -180 to +180 degrees.

'Please provide more info below. How many digits after the comma or dot?' E.g. XXX.YYYY -XXX.YYYY +XXX.YYYY

Where: - the "." and YYYY may be left away if "YYYY" is equal to "0000" - tailing "0" of YYYY may be left away - leading "0"s of XXX may be left away - the "+" may be left away Are the following accepted?

179. instead of 179 or 179.0 .4 instead of 0.4

OSMlatType

The OSMlonType shall be an integer number in the range of -90 to +90.

'Please provide more info below. How many digits after the comma or dot?' E.g. XXX.YYYY -XXX.YYYY +XXX.YYYY

Where: - the "." and YYYY may be left away if "YYYY" is equal to "0000" - tailing "0" of YYYY may be left away - leading "0"s of XXX may be left away - the "+" may be left away Are the following accepted?

179. instead of 179 or 179.0 .4 instead of 0.4

OSMDateType

This should be either of the form YYYY-MM-DD or YYYY-MM-DD hh:mm:ss (Don't forget to encode the space as %20)

OSMTrackpointPageType

The OSMTrackpointPageType shall be an integer number greater than or equal to 0.

Status Codes

The OSM Database Access Protocol shall use the status_codes defined by HTTP Protocol Specification.

Encoding of Error Text

Please help fixing this part.

Encoding of error_text parameter shall be ???ASCII or UTF-8 text string???

Please provide input on the text string type!!!

API v0.4

Historical Interest Only. Version 0.4 no longer in use

OSM API Version 0.4

The RESTful API

Protocol Roles

OSM Protocol role client

OSM Protocol role server

Transport

General HTTP-Transport format

OSM specific HTTP-Transport format configuration

Used HTTP Methods

HTTP GET-Method based commands

Get node by NodeID

Get segment by SegmentID

Get way history by ID

Get way by ID

Get ways

Get map

Search objects (ways, segments and nodes)

Search nodes

Search segments

Search ways

Get gpx files of the user

Create gpx file

Get GPX file details by ID

Get Trackpoints

HTTP PUT-Method based commands

Create new node

Create new segment

Create new way

Store node by ID

Store segment by ID

Store way by ID

HTTP DELETE-Method based commands

Delete node by ID

Delete segment by ID

Delete way by ID

Error Text

Error handling

Type definitions

StatusCodeType

OSMIdentifierType

OSMTextStringType

OSMlonType

OSMlatType

OSMDateType

OSMTrackpointPageType

Status Codes

Encoding of Error Text

Navigation menu

Search