API v0.4

From OpenStreetMap Wiki
Jump to navigation Jump to search


Logo.png
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 Protocol role client

The OSM client sends request messages to the OSM server.

Examples of OSM clients are:

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:

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