It has been proposed that this page be deleted or replaced by a redirect. (Discuss)

Software described on this page or in this section is unlikely to be compatible with API v0.6 deployed on April 20, 2009. If you have fixed the software, or concluded that this notice does not apply, remove it.

WARNING this document is incomplete and or wrong, feel free to fix See API v0.6

The focus of this document is to inform about the general principles of http-protocol, not about the URL-format which is part of the OSM Protocol Specification. If you are looking for that URL-format, please look here API for the latest version of the OSM Protocol Specification.

Notes for API Users

• As of May 2009, the OSM protocol uses the version 0.6 of the OSM protocol. This the URLs will now have the format /api/0.6/.

• As of March 16 2008, this page documents API version 0.4. However, attempting to interact with /api/0.4/ is resulting in HTTP errors - the production server does not appear to support version 0.4 any more. I succeeded with /api/0.5/ instead - I figured this out by watching packets while JOSM was working. I'm not going to replace all the URLs in this page because I'm not familiar with the API and don't want to pretend that version 0.5 is correctly documented here.

The OSM protocol is HTTP based. Within (as a payload of) the HTTP requests/responses, we use XML structure messages, the structure of which is detailed is the protocol layer above called OSM Protocol.

This page provides a description of those aspects of the HTTP-Protocol which are used by OpenStreetMap (e.g. which HTTP headers do we send/receive, in various use circumstances). This document shall not be considered as a replacement HTTP-Specification itself.

Notes for API Users

• As of March 16 2008, this page documents API version 0.4. However, attempting to interact with /api/0.4/ is resulting in HTTP errors - the production server does not appear to support version 0.4 any more. I succeeded with /api/0.5/ instead - I figured this out by watching packets while JOSM was working. I'm not going to replace all the URLs in this page because I'm not familiar with the API and don't want to pretend that version 0.5 is correctly documented here.

Protocol Roles

The normative specification of the HTTP-Protocol is found here: RFC 2616.

This HTTP-Protocol has 2 protocol roles.

• HTTP client
• HTTP server

The following image shows the HTTP-Methods used by the OSM-Protocols.

HTTP-Protocol role client

Before sending any messages to the HTTP server, the HTTP client shall open a TCP/IP connection to the HTTP server using the lower layers. The HTTP server is addressed using its DNS or IP-Address and the corresponding Port Number.

???Which IP-Address and Port Number applies for the Openstreetmap Server??? Please help fixing!! (I think the address is openstreetmap.org. And the port is 80.)

Then the HTTP client may send one or more HTTP-Request messages to the HTTP server and should wait for receiving the corresponding HTTP-Response message. When the HTTP client no longer intends to send or to receive information from the HTTP server, the HTTP client should close the TCP/IP connection.

???How about more details here like Keeping the TCP/IP connection alive???Please help fixing!!!! (the TCP/IP connection is alive until you close it. 'alive' is a only a state.)

The HTTP-Request messages sent contain the following fields:

• The HTTP-Method GET-, PUT or DELETE.

(http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)

• The URL.
• If the HTTP-Method PUT is used, the HTTP-Request shall contain a message body carrying payload data.
• What else???? Please help fixing!!!!

The HTTP-Response messages received the following fields:

• Status Code
• If the HTTP-Method GET was used and the status code is OK, the HTTP-Response should (shall?) contain a message body carrying payload data.
• If the status code is other than OK, the HTTP-Response may contain an additional Error text.
• What else???? Please help fixing!!!!

According to RFC 2616 the URLs have the following format:

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

HTTP-Protocol role server

Upon reception of a HTTP-Request from the HTTP client, the HTTP server answers with a response message.

Transport

The HTTP-Protocol TCP/IP as transport.

HTTP Methods

The OSM protocol uses the following HTTP methods:

• GET
• PUT
• DELETE

HTTP-Method GET

To request data from the server the OSM client shall send a GET_request message to the OSM server. The GET_request message shall contain the parameter get_request_command.

Upon reception of the GET_request message, the OSM server shall respond with a GET_response message.

• If the received parameter get_request_command contains invalid data, the GET_response message shall contain:
  • The status_code parameter set to Bad Request.
  • The error_text parameter.

• If the user authentication with the given user name and password failed, the GET_response message shall contain:
  • The status_code parameter to Unauthorized.
  • The error_text parameter.

• If the object identified by the get_request_command received within the GET_request message does exist on the OSM server:
  • The [OSM server] shall retrieve the object from the database
    
  • The GET_response message shall contain:
    • the status_code parameter set to OK.
    • The #get_response_body parameter.

• If the object identified by the get_request_command received within the GET_request message had never been existing before, the GET_response message shall contain:
  • The status_code parameter set to Not Found.
  • The error_text parameter.

• If the object identified by the get_request_command received within the GET_request message had been existing before, however does no longer exist, the GET_response message shall contain:
  • The status_code parameter set to Gone.
  • The error_text parameter.

GET request

GET /api/0.4/map?bbox=11.54327230079174,48.126027558543186,11.554470456072357,48.136380244472875
HTTP/1.1
User-Agent: Java/1.5.0_09
Host: www.openstreetmap.org
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-type: application/x-www-form-urlencoded
Authorization: Basic <credentials removed>

Where:

HTTP/1.1
User-Agent: Java/1.5.0_09
Host: www.openstreetmap.org
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-type: application/x-www-form-urlencoded
Authorization: Basic <credentials removed>

GET Response

GET Response: Successful execution example

HTTP/1.1 200 OK
Date: Sat, 28 Apr 2007 21:03:02 GMT
Server: Apache/2.0.54 (Debian GNU/Linux) mod_ruby/1.2.4 Ruby/1.8.2(2005-04-11)
Keep-Alive: timeout=3, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

fbf
<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.3" generator="OpenStreetMap server">
 <node id="20456749" lat="48.1307163942743" lon="11.5460291508286" visible="true" timestamp="2006-10-29 20:13:47">
   <tag k="name" v="Bavaria"/>
   <tag k="created_by" v="JOSM"/>
 </node>
 ....
 ...
</osm>
0

Where:

HTTP/1.1
Date: Sat, 28 Apr 2007 21:03:02 GMT
Server: Apache/2.0.54 (Debian GNU/Linux) mod_ruby/1.2.4 Ruby/1.8.2(2005-04-11)
Keep-Alive: timeout=3, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.3" generator="OpenStreetMap server">
 <node id="20456749" lat="48.1307163942743" lon="11.5460291508286" visible="true" timestamp="2006-10-29 20:13:47">
   <tag k="name" v="Bavaria"/>
   <tag k="created_by" v="JOSM"/>
 </node>
 ....
 ...
</osm>

GET Response: Failed execution example

HTTP/1.1 401 Authorization Required
Date: Sat, 28 Apr 2007 21:03:02 GMT
Server: Apache/2.0.54 (Debian GNU/Linux) mod_ruby/1.2.4 Ruby/1.8.2(2005-04-11)
WWW-Authenticate: Basic realm="Ruby Auth"
Content-Length: 401
Keep-Alive: timeout=3, max=100
Connection: Keep-Alive
Content-Type: text/html; charset=iso-8859-1

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>401 Authorization Required</title>
</head><body>
<'h1>Authorization Required</h1>
<'p>This server could not verify that you
are authorized to access the document
requested.  Either you supplied the wrong
credentials (e.g., bad password), or your
browser doesn't understand how to supply
the credentials required.</p>
</body></html>

Where:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>401 Authorization Required</title>
</head><body>
<'h1>Authorization Required</h1>
<'p>This server could not verify that you
are authorized to access the document
requested.  Either you supplied the wrong
credentials (e.g., bad password), or your
browser doesn't understand how to supply
the credentials required.</p>
</body></html>

HTTP-Method PUT

To upload data from the server the OSM client shall send a PUT_request message to the OSM server. The PUT_request message shall contain the parameter put_request_command and the #put_request_body.

Upon reception of the PUT_request message the OSM server shall respond with a PUT_response message.

• If the received parameter get_request_command contains invalid data, the PUT_response message shall contain:
  • The status_code parameter set to Bad Request.
  • The error_text parameter.

• If the user authentication with the given user name and password failed, the PUT_response message shall contain:
  • The status_code parameter set to Unauthorized.
  • The error_text parameter.

• If the object identified by the put_request_command received within the PUT_request message does exist, the PUT_response parameter message shall contain:
  • The status_code parameter set to OK.

• If the object identified by the put_request_command received within the PUT_request message had never been existing before, the PUT_response message shall contain:
  • The status_code parameter set to Not Found.
  • The error_text parameter.

PUT request

PUT /api/0.4/node/(create|NODE_NUMBER) HTTP/1.1
User-Agent: Java/1.5.0_09
Host: www.openstreetmap.org
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Authorization: Basic <credentials removed>
Content-Length: 194

<?xml version='1.0' encoding='UTF-8'?>
<osm version='0.3' generator='JOSM'>
  <node id='0' lat='48.13213250462367' lon='11.543279671866909'>
    <tag k='created_by' v='JOSM' />
  </node>
</osm>

Where:

<?xml version='1.0' encoding='UTF-8'?>
<osm version='0.3' generator='JOSM'>
  <node id='0' lat='48.13213250462367' lon='11.543279671866909'>
    <tag k='created_by' v='JOSM' />
  </node>
</osm>

HTTP/1.1
User-Agent: Java/1.5.0_09
Host: www.openstreetmap.org
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Authorization: Basic <credentials removed>
Content-Length: 194

PUT Response

PUT Response: Successful execution example

HTTP/1.1 200 OK
Date: Sat, 28 Apr 2007 21:18:12 GMT
Server: Apache/2.0.54 (Debian GNU/Linux) mod_ruby/1.2.4 Ruby/1.8.2(2005-04-11)
Keep-Alive: timeout=3, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

Where:

HTTP/1.1 200 OK
Date: Sat, 28 Apr 2007 21:18:12 GMT
Server: Apache/2.0.54 (Debian GNU/Linux) mod_ruby/1.2.4 Ruby/1.8.2(2005-04-11)
Keep-Alive: timeout=3, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

HTTP-Method DELETE

To delete an object on the server the OSM client shall send a DELETE_response message to the OSM server. The DELETE_request message shall contain the parameter delete_request_object_ID and the #delete_request_body.

Upon reception of the DELETE_response message the OSM server shall respond with a DELETE_response message.

• If the received parameter delete_request_object_ID contains invalid data, the DELETE_response message shall contain:
  • The status_code parameter set to Bad Request.
  • The error_text parameter.

• If the user authentication with the given user name and password failed, the DELETE_response message shall contain:
  • The status_code parameter set to Unauthorized.
  • The error_text parameter.

• If the object identified by the delete_request_object_ID received within the DELETE_response message does exist, the DELETE_response message shall contain:
  • The status_code parameter set to OK.

• If the object identified by the delete_request_object_ID received within the DELETE_response message had been existing before, however does no longer exist, the DELETE_response message shall contain:
  • The status_code parameter set to Gone.
  • The error_text parameter.

• If the object identified by the delete_request_object_ID received within the DELETE_response message had never been existing before, the DELETE_response message shall contain:
  • The status_code parameter set to Not Found.
  • The error_text parameter.

DELETE request

DELETE /api/0.4/node/28162633 HTTP/1.1
User-Agent: Java/1.5.0_09
Host: www.openstreetmap.org
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Authorization: Basic <credentials removed>
Content-type: application/x-www-form-urlencoded

Where:

HTTP/1.1
User-Agent: Java/1.5.0_09
Host: www.openstreetmap.org
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Authorization: Basic <credentials removed>
Content-type: application/x-www-form-urlencoded

DELETE Response

DELETE Response: Successful execution example

HTTP/1.1 200 OK
Date: Sat, 28 Apr 2007 21:19:47 GMT
Server: Apache/2.0.54 (Debian GNU/Linux) mod_ruby/1.2.4 Ruby/1.8.2(2005-04-11)
Keep-Alive: timeout=3, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

0

Where:

HTTP/1.1
Date: Sat, 28 Apr 2007 21:19:47 GMT
Server: Apache/2.0.54 (Debian GNU/Linux) mod_ruby/1.2.4 Ruby/1.8.2(2005-04-11)
Keep-Alive: timeout=3, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

0

HTTP-Authentication

The HTTP-Protocol provides user authentication. It had been specified in RFC 2617.

Please help to provide an overview how HTTP Authentication works. Examples are welcome. Please fixing me!!!

Basic HTTP authentication is used to provide a client's credentials (in the form of username and password) to the server. There is no encryption of the credentials, just obfuscation via base 64 encoding. To create a basic authentication header, simply encode a string containing the username:password as a base 64 string. An example using perl:

perl -MMIME::Base64 -e 'print "Authorization: Basic ", encode_base64("joe_smith:mypassword")'

will produce the following:

Authorization: Basic am9lX3NtaXRoOm15cGFzc3dvcmQ=

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

This section provides information on error handling.

Authentication failure

Describe here how the OSM client shall handle reception of a GET/PUT/DELETE_response with the status_code set to unauthorized· (tbd., please provide input)

Type definitions

StatusCodeType

The ReturnCodeType shall be an Integer in the Range [0 to 511].

The following StatusCodeType are used:

Status Code "OK"

The HTTP-server will use the status_code OK when the requested operation (get_request_command, put_request_command or delete_request_object_ID) has been successfully executed.

Status Code "Bad Request"

The OSM server will use the status_code Bad Request, when the get_request_command, put_request_command or delete_request_object_ID is not valid.

In a few cases, there may be an additional HTTP header Error, which will contain a user facing description of why your request was invalid.

Status Code "Unauthorized"

The OSM server will use the status_code Unauthorized when user authentication was not successful.

Status Code "Not Found"

The OSM server will use the status_code Not Found when the requested object does not exist and has never existed.

Status Code "Gone"

The OSM server will use the status_code Gone when the requested object did exist, but has since been deleted.

Status Code "Precondition Failed"

The OSM server will use the status_code Precondition Failed when the requested operation could not be executed because a precondition for execution of that operation had not been met. E.g. a node could not been deleted, because it is used by a segment.

Status Code "Internal Server Error"

The OSM server will use the status_code Internal Server Error where the server encounters an unexpected problem.

Encoding

Encoding of Status Codes

In alignment with the error codes specified in RFC 2617 the Status Codes shall be encoded with the following values: