JA:API v0.6

From OpenStreetMap Wiki
Jump to: navigation, search
Help
Available languages
• English • 日本語 • Português do Brasil • Русский
Other languages — Help us translating this wiki
• Afrikaans • አማርኛ • العربية • অসমীয়া • Asturianu • Azərbaycanca • Български • বাংলা • Brezhoneg • Bosanski • Català • Corsu • Česky • Dansk • Deutsch • ދިވެހިބަސް • Ελληνικά • Esperanto • Español • Eesti • Euskara • فارسی • Suomi • Français • Frysk • Gaeilge • Kréyòl gwadloupéyen • Gàidhlig • Galego • Alemannisch • ગુજરાતી • هَوُسَ • עברית • हिन्दी • Hrvatski • Kreyòl ayisyen • Magyar • Հայերեն • Interlingua • Bahasa Indonesia • Igbo • Íslenska • Italiano • Basa Jawa • ქართული • Қазақша • ភាសាខ្មែរ • ಕನ್ನಡ • 한국어 • Kurdî • Lëtzebuergesch • ລາວ • Lietuvių • Latviešu • Malagasy • Македонски • മലയാളം • मराठी • Bahasa Melayu • Malti • မြန်မာဘာသာ • नेपाली • Nederlands • ‪Norsk (nynorsk)‬ • ‪Norsk (bokmål)‬ • Occitan • Oromoo • ଓଡ଼ିଆ • ਪੰਜਾਬੀ • Polski • پښتو • Português • Română • Română (Moldova) • سنڌي • සිංහල • Slovenčina • Slovenščina • Soomaaliga • Shqip • Српски / Srpski • Svenska • தமிழ் • తెలుగు • Тоҷикӣ • ไทย • Türkçe • Українська • اردو • O'zbek • Tiếng Việt • Wolof • isiXhosa • Yorùbá • ‪中文(简体)‬ • ‪中文(繁體)‬ • isiZulu

OSM API の現在の最新版は、2009年4月17日-21日にデプロイした API v0.6 です。

Contents

全般情報

このAPIは、RESTful APIのアイデアを基にしています。RESTful APIの詳細は、wikipedia の REST ページ をご覧ください。

この API は REST リクエストに対応するサーバーコンポーネントです。REST リクエストは、HTTP の GET, PUT, POST, DELETE メッセージの形式を取ります。ペイロードはいずれも MIME タイプ "text/xml"、UTF-8 文字エンコーディングの XML 形式です。クライアントが HTTP "Accept" ヘッダーで圧縮メッセージを扱えると示した場合、HTTP レイヤーで圧縮を行います。

データベースを変更するようなリクエストは、HTTP Basic 認証 や OAuth で認証が必要です。読み込みリクエストには、(ユーザーの詳細を除き) 認証は必要ありません。

仮の フル DTD (作成・議論中)

API v0.5 と API v0.6 の変更点

URL + 認証

API は、現在この URL: http://api.openstreetmap.org/ でアクセスできます。

API に対応するソフトウェアのテストを行う場合、実際の API の代わりに、http://api06.dev.openstreetmap.org/ の使用を検討してください。

更新、作成、削除を行う API の呼び出しはすべて、ユーザーの認証を行わなければなりません。認証は、ユーザー名とパスワードを使う HTTP の Basic 認証か、OAuth を使用して行います。

要素(Element)

OpenStreetMap のデータを構成する 3 種の基本要素(Element)を、作成、読込、更新、削除する API があります。それぞれ XML 形式要素データを受付け、返却します。

変更セット(Changeset)

1つ以上の要素に対するすべての変更は、開いた 変更セット(changeset) に関連付けられなければなりません。

タグ(Tag)

要素や変更セットにはすべて、任意の数のタグを付けられます。タグは、255文字まで (255バイトではない) の unicode 文字であるキー・値のペアです。

確実なユーザーの識別

以前の API v0.5 では、ユーザーの表示名のみを返していました。ユーザーはこれをいつでも変更でき、表示名の変更は履歴が残りません。これは、ある変更を、どのユーザーが行ったかを確実に識別する方法がないという事になります。API v0.6 では表示名に加え、アカウントのユーザーIDを、以下のように返します。 

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

これはまだ、誰がその変更を行ったかの公開を求めています。以前に匿名で変更を行ったユーザーのユーザーIDは、見えないでしょう。OpenStreetMap 財団理事会の勧めに従い、匿名編集は、もうできなくなりました。

バージョン番号・楽観的ロック

planet のダンプや差分、要素についての API 呼び出しは、各 ノード(Node), ウェイ(Way), リレーション(Relation) に version 属性をつけて返します。 

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

このバージョン番号は、楽観的ロック に使用します。オブジェクトの新しいバージョンをアップロードするには、クライアントは、変更したオブジェクトのバージョン番号を指定する必要があります。指定したバージョンがサーバーの現在のバージョンと一致しない場合、エラーを返却します (HTTP ステータスコード 409: Conflict)。これは、データを更新するクライアントは、元データのバージョン番号を保存する必要がある、と言うことです。ある要素を、1回の変更セットで複数回更新できますし、そのバージョン番号をその都度更新します。そのため、1つの変更セットの1要素で、複数の「履歴バージョン」がありえます。

さらに、クライアントは要素の特定バージョンを取得できるようになりました。

バージョン番号は 1 から始まり、要素が変更されるごとに 1 づつ増加していきます。しかし、要素を更新すると 1 増えることを、あてにするべきではありません。サーバーのレスポンスにより、新しいバージョン番号を取得するようにしてください。

XML 形式

サーバーからの XML レスポンスはすべて、他のものを指定した時を除き (例: 差分アップロードや変更セットのダウンロード) <osm> 要素に包まれています。以下のほとんどの例では、この要素を省略しています。 

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

API への呼び出しはすべて、同様に <osm> 要素で包まなければなりません。しかし version 属性と generator 属性は省略できます。

正しい HTTP メソッドへの偽装

多くの API 呼び出しで、あなたが使っているクライアントの HTTP スタックで使用できないかもしれない、PUT, DELETE メソッドを使用します。そのスタックの作者に、HTTP をすべて実装して欲しいと申し入れるべきです。その上で動作しない場合、X_HTTP_METHOD_OVERRIDE ヘッダの値に、シミュレートしたいメソッドを設定して回避できます。例えば、curl に POST させて PUT ハンドラを使用する場合、以下のようにしてください。 

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

API 呼び出し

雑記

機能: GET /api/capabilities

この API 呼び出しは、現在の API での機能と制限についての情報を提供します。

レスポンス

XML ドキュメント (content type text/xml) を返す 

 <osm version="0.6" generator="OpenStreetMap server">
   <api>
     <version minimum="0.6" maximum="0.6"/>
     <area maximum="0.25"/>
     <tracepoints per_page="5000"/>
     <waynodes maximum="2000"/>
     <changesets maximum_elements="50000"/>
     <timeout seconds="300"/>
   </api>
 </osm>

実際に返される値はいつでも変更される可能性があり、この XML ドキュメントは例として提供していることに注意してください。

注意

境界ボックス(Bounding box)での地図データ取得: GET /api/0.6/map

以下のものをこのコマンドは返します。 

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

ここでは以下を示します。

このコマンドは、前述のノードやウェイを参照するリレーションを返しますが、逆は真ではないことに注意してください。このリレーションで参照されるノードやウェイを、(必ずしも) すべて返すとは限りません。これにより、むやみに大きな結果セットになることを防いでいます。例えば以下のような例を考えてみてください。

コマンドの規則によって指定したノード、ウェイ、リレーションが、("England" リレーション込で) 結果に含まれるとはいえ、イングランドにあるすべてのノードやウェイが、(偶然) 含まれるとは限りません。希望するなら、"England" リレーションが参照するノードやウェイを、それぞれの ID により取得できます。

また、境界ボックスと交差しても境界ボックス内にノードがないウェイは返却されないことに注意してください。

エラーコード

HTTP ステータスコード 400 (Bad Request)
ノード・ウェイ・リレーションの制限いずれかに引っかかった場合
HTTP ステータスコード 509 (Bandwidth Limit Exceeded)
"Error: You have downloaded too much data. Please try again later." Developer FAQ を参照

変更セット(changeset)

関連する変更の識別を容易にするために、変更セット(changeset)の概念を導入します。標準 OSM 要素のすべての変更は、開いた変更セットで参照されなければなりません。変更セットには、ちょうどその他の要素のように、タグが付与されていることがあります。変更セットの推奨タグは、変更セットで行った変更の短い人間可読な説明を、キー comment=* で付与します (リビジョン管理システムのコミットメッセージに似ています)。新しい変更セットはいつでも開くことができ、変更セットは複数の API 呼び出しを参照できます。そのため、サーバーが変更セットの終了や、新しい変更セットの開始を知ることができず、手動で閉じることになる場合があります。開いた変更セットの横取りを防ぐため、以下の3条件により、変更セットを自動的に閉じる機構が実装されています。

変更セットは特に不可分ではありません。変更セットで追加した要素は、変更セットを閉じる前に、他のユーザーから見えることになります。与えられたいくつもの変更を、一度にアップロードすることは、実現不可能です。その代わりに、前述の楽観的ロックを用います。サーバーに1リクエストで送られた変更は、不可分としてみなされます。複数の変更でのトランザクション性を得るには、新しい差分アップロード API 呼び出しがあります。

変更セットは、ロールバックの実装を容易にします。ひとりがコミットした変更を見抜くことにより、範囲全体をロールバックするのではなく、行った変更を識別しやすくします。API ではロールバックを直接サポートしていません。逆マージという形になるでしょう。そこでは、クライアントが変更セットをダウンロードし、変更を検証して、希望の結果となるよう API を操作することになります。変更セットのロールバックは、非常に複雑な処理になります。特に、通常時に行われた他の変更とロールバックが競合すると、複雑になります。私たちは、そのうち平均的ユーザーが利用できる、様々なレベルのロールバックを行える、エキスパートアプリケーションが作成されることを期待 (希望) しています。

もっと簡単に使えるようにするため、サーバーは各変更セットの境界ボックスを保持し、エリアにある変更セットを問い合わせられるようにしています。どのみち関係のあるノードを調べる必要があるため、サーバーで計算されることになります。最適化としては、境界ボックスを更新しすぎないように、オブジェクトよりは多少大きな余裕を持って作成します。クライアントは、大きな領域に対して小さな変更を大量に行う場合、簡単に一致するように留意してください。この場合、クライアントは本当に重なるのかどうかを確認するため、変更セットを直接検査するようにしてください。クライアントは API 呼び出しを使用して、境界ボックスを拡大できます。これは、アップロードするデータの範囲を、クライアントがすでに十分にわかっている場合に便利です。

変更セットに変更が含まれていないとしても、その変更セットをすぐには削除できません。クローズされ変更を含まない変更セットに対して、後で削除できるようになる可能性があります。これはまだ未実装です。

境界ボックスの計算

以下に変更セットに関連した境界ボックスを、APIがどのように計算するのかを述べます。

  • リレーションにノードやウェイを追加・削除すると、そのノード・ウェイを変更セットの境界ボックスに追加します。
  • リレーションのメンバーの追加や変更セットのタグ変更を行うと、メンバーであるすべてのノード・ウェイを、境界ボックスに追加します。
  • これは地図を呼び出す方法に似ており、メンバーの追加・削除では、リレーションの他の部分の変更が物理的に行われないという前提で合理的です。

作成: PUT /api/0.6/changeset/create

変更セット作成リクエストのペイロードには、1つ以上のchangeset要素があり、任意の数の tag をその中に含めることができます。 

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

XML内に複数のchangeset要素があり、その中の全てにtagがある場合、キーが重複すると、後のもので前のものを上書きします。

レスポンス

新しく作成した変更セットのIDを、コンテントタイプ text/plain で返します。

エラーコード

HTTP ステータスコード 400 (Bad Request)
XML の解析でエラー発生時
HTTP ステータスコード 405 (Method Not Allowed)
リクエストが HTTP PUT リクエストでない場合

注意

おそらくエディタ特有である任意の数のタグを使用できます。例えば、どの背景画像を使用したといった情報や、後から同じエディタで変更セットを再処理するために内部状態情報なども、エディタが自動的に記録することでしょう。

クライアントは、created_by=* タグを含めるべきです。また、ユーザーが入力した comment=* が存在するか、クライアントは確認したほうが良いでしょう。これは今のところオプションですが、今後の API バージョンで変更されるかもしれません。このタグは、エンドユーザーが自分の変更を説明するためのものですので、クライアントが自動的に comment タグを生成するべきではありません。クライアントは適切と思えるタグを、追加する場合があります。

読み込み: GET /api/0.6/changeset/#id

与えた id の変更セットを OSM-XML 形式で返します。 

<osm>
  <changeset id="10" user="fred" uid="123" created_at="2008-11-08T19:07:39+01:00" open="true" min_lon="7.0191821" min_lat="49.2785426" max_lon="7.0197485" max_lat="49.2793101">
    <tag k="created_by" v="JOSM 1.61"/>
    <tag k="comment" v="Just adding some streetnames"/>
    ...
 </changeset>
</osm>

パラメータ

id
取得する変更セットの id

レスポンス

changeset タグを含む、ひとつの changeset 要素を、コンテントタイプ text/xml で返します。

エラーコード

HTTP ステータスコード 404 (Not Found)
与えた id に該当する変更セットが見つからない場合

注意

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

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

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

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

パラメータ

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

レスポンス

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

エラーコード

HTTP ステータスコード 400 (Bad Request)
XML の解析でエラー発生時
HTTP ステータスコード 404 (Not Found)
与えた id に該当する変更セットが見つからない場合
HTTP ステータスコード 405 (Method Not Allowed)
If the request is not a HTTP PUT request
HTTP ステータスコード 409 (Conflict) - text/plain
If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned
Or if the user trying to update the changeset is not the same as the one that created it

注意

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

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

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

パラメータ

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

レスポンス

Nothing is returned upon successful closing of a changeset (HTTP ステータスコード 200)

エラーコード

HTTP ステータスコード 404 (Not Found)
与えた id に該当する変更セットが見つからない場合
HTTP ステータスコード 405 (Method Not Allowed)
If the request is not a HTTP PUT request
HTTP ステータスコード 409 (Conflict) - text/plain
If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned
Or if the user trying to update the changeset is not the same as the one that created it

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

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

パラメータ

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

レスポンス

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

エラーコード

HTTP ステータスコード 404 (Not Found)
与えた id に該当する変更セットが見つからない場合

注意

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

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

The input document should look like this: 

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

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

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

パラメータ

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

レスポンス

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

エラーコード

HTTP ステータスコード 404 (Not Found)
与えた id に該当する変更セットが見つからない場合
HTTP ステータスコード 409 (Conflict) - text/plain
If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned
Or if the user trying to update the changeset is not the same as the one that created it

注意

Query: GET /api/0.6/changesets

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

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

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

パラメータ

bbox=min_lon,min_lat,max_lon,max_lat (W,S,E,N)
Find changesets within the given bounding box
user=#uid or display_name=#name
Find changesets by the user with the given user id or display name. Providing both is an error.
time=T1
Find changesets closed after T1
time=T1,T2
Find changesets that were closed after T1 and created before T2
open
Only finds changesets that are still open but excludes changesets that are closed or have reached the element limit for a changeset (50.000 at the moment)
closed
Only finds changesets that are closed or have reached the element limit

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

レスポンス

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

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
On misformed parameters. A text message explaining the error is returned. In particular, trying to provide both the UID and display name as user query parameters will result in this error.
HTTP ステータスコード 404 (Not Found)
When no user with the given uid or display_name could be found.

注意

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

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

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

パラメータ

id
The ID of the changeset this diff belongs to.
POST data
The OsmChange file data

レスポンス

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

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

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

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

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
XML の解析でエラー発生時. A text message explaining the error is returned.
When an placeholder ID is missing or not unique
HTTP ステータスコード 405 (Method Not Allowed)
If the request is not a HTTP POST request
HTTP ステータスコード 409 (Conflict) - text/plain
If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned
If, while uploading, the max. size of the changeset is exceeded. A message with the format "The changeset #id was closed at #closed_at." is returned
Or if the user trying to update the changeset is not the same as the one that created it
Or if the diff contains elements with changeset IDs which don't match the changeset ID that the diff was uploaded to
Any of the error codes that could occur an a create, update or delete operation for one of the elements
See the according sections in this page

注意

Changeset summary

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

OSM API0.6 Changeset successful creation V0.1.png

Elements

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

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

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

A Node: 

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

A Way: 

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

A Relation: 

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

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

レスポンス

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

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
XML の解析でエラー発生時. A text message explaining the error is returned.
When a changeset ID is missing (unfortunately the error messages are not consistent)
When a node is outside the world
When there are too many nodes for a way
HTTP ステータスコード 405 (Method Not Allowed)
If the request is not a HTTP PUT request
HTTP ステータスコード 409 (Conflict) - text/plain
If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned
Or if the user trying to update the changeset is not the same as the one that created it
HTTP ステータスコード 412 (Precondition Failed)
When a way has nodes that do not exist or are not visible (i.e. deleted): "Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible."
When a relation has elements that do not exist or are not visible: "Relation with id #{id} cannot be saved due to #{element} with id #{element.id}"

注意

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

Returns the XML representation of the element.

レスポンス

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

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

エラーコード

HTTP ステータスコード 404 (Not Found)
When no element with the given id could be found
HTTP ステータスコード 410 (Gone)
If the element has been deleted

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

Updates data from a preexisting element. A full representation of the element as it should be after the update has to be provided. So any tags that remain unchanged have to be in the update as well. A version number has to be provided as well.

レスポンス

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

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
XML の解析でエラー発生時. A text message explaining the error is returned. This can also happen if you forget to pass the Content-Length header.
When a changeset ID is missing (unfortunately the error messages are not consistent)
When a node is outside the world
When there are too many nodes for a way
When the version of the provided element does not match the current database version of the element
HTTP ステータスコード 409 (Conflict) - text/plain
If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned
Or if the user trying to update the changeset is not the same as the one that created it
HTTP ステータスコード 404 (Not Found)
When no element with the given id could be found
HTTP ステータスコード 412 (Precondition Failed)
When a way has nodes that do not exist or are not visible (i.e. deleted): "Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible."
When a relation has elements that do not exist or are not visible: "Relation with id #{id} cannot be saved due to #{element} with id #{element.id}"

注意

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

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

For example: 

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

Where the node ID in the XML must match the ID in the URL, the version must match the version of the element you downloaded and the changeset must match the ID of an open changeset owned by the current authenticated user. It is allowed, but not necessary, to have tags on the element except for lat/long tags which are required, see http://web.archiveorange.com/archive/v/wQWIbRy3o8HjRNYaSim9 and also tested to still hold on 2011-05-30, without lat+lon the server gives 400 Bad request.

レスポンス

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

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
XML の解析でエラー発生時. A text message explaining the error is returned.
When a changeset ID is missing (unfortunately the error messages are not consistent)
When a node is outside the world
When there are too many nodes for a way
When the version of the provided element does not match the current database version of the element
HTTP ステータスコード 404 (Not Found)
When no element with the given id could be found
HTTP ステータスコード 409 (Conflict) - text/plain
If the changeset in question has already been closed (either by the user itself or as a result of the auto-closing feature). A message with the format "The changeset #id was closed at #closed_at." is returned
Or if the user trying to update the changeset is not the same as the one that created it
HTTP ステータスコード 410 (Gone)
If the element has been already been deleted
HTTP ステータスコード 412 (Precondition Failed)
When a node is still used by a way: Node #{id} is still used by way #{way.id}.
When a node is still member of a relation: Node #{id} is still used by relation #{relation.id}.
When a way is still member of a relation: Way #{id} still used by relation #{relation.id}.
When a relation is still member of another relation: The relation #{id} is used in relation #{relation.id}.

注意

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

Retrieves all old versions of an element.

エラーコード

HTTP ステータスコード 404 (Not Found)
When no element with the given id could be found

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

Retrieves a specific version of the element.

エラーコード

HTTP ステータスコード 404 (Not Found)
When no element with the given id could be found

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

Allows a user to fetch multiple elements at once.

パラメータ

[nodes|ways|relations]=comma separated list
The parameter has to be the same in the URL (e.g. /api/0.6/nodes?nodes=123,456,789)

エラーコード

HTTP ステータスコード 400 (Bad Request)
On a malformed request (parameters missing or wrong)
HTTP ステータスコード 404 (Not Found)
If one of the elements could not be found
HTTP ステータスコード 414 (Request-URI Too Large)
If the URI was too long (How long is too long?)

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

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

注意

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

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

注意

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

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

エラーコード

HTTP ステータスコード 404 (Not Found)
When no element with the given id could be found
HTTP ステータスコード 410 (Gone)
If the element has been deleted

GPS トレース

GPS ポイントの取得

以下のコマンドにより、与えた境界ボックス内の GPS 追跡ポイントを GPX 形式で返します。 

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

ここでは以下を示します。

例

境界ボックスにある、先頭から 5,000 個のポイントを取得: 

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

同じ境界ボックスにある、次の 5,000 個のポイント (5,001–10,000 のポイント) を取得: 

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


トレースのアップロード

GPX ファイルや GPX ファイルの書庫を、以下のように API でアップロードできます。 

POST /api/0.6/gpx/create

これは POST メソッドを使用する、唯一の API 呼び出しです。multipart/form-data HTTP メッセージ中の、以下の POST パラメータを期待します。

パラメータ 説明
file 追跡ポイントがある GPX ファイル。処理が成功するには、ファイルにウェイポイントだけでなく、追跡ポイント (<trkpt>) が含まれていなければならないことに注意してください。また、追跡ポイントには妥当なタイムスタンプが必要です。ファイルの処理は非同期で行われますので、ファイルの処理が成功しなくても、この呼び出しは正常終了します。複数の GPX ファイルを含む .tar, .tar.gz, .zip ファイルも受け付けますが、アップロードしたログの中では、1つのエントリーとして現れます。
description トレースの説明
tags トレースのタグを表す文字列
public 1 の場合トレースを公開します。0 では公開しません。これは後方互換のためだけに存在します。今後は visibility パラメータを使用してください。visibility を同時に指定した場合、このパラメータの値を無視します。
visibility 以下のうち1つです。 private, public, trackable, identifiable (意味は OSM trace upload page や JA:Visibility_of_GPS_traces を参照)

HTTP BASIC 認証が必要です。

トレースのメタデータダウンロード

GPX ファイル詳細へのアクセスや、ファイル全体のダウンロードができます。 

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

HTTP BASIC 認証が必要ですが、理論上トレースが公開としてマークされている場合、認証していなくても許可されるはずです。公開されていない場合、オーナーのみがデータにアクセスできます。

以下は "details" レスポンスの例です。 

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

"data" レスポンスは、アップロードしたファイルそのものになります。


以下のようにして、認証ユーザーの GPX トレースすべてのリストの取得もできます。 

GET /api/0.6/user/gpx_files

Methods for User Data

Unless noted otherwise, all user-specific API calls require authentication and operate on the currently authenticated user account. That's why they don't normally have an explicit "username" parameter. 特に断りのない限り、すべてのユーザー固有のAPI呼び出しが認証を必要とし、現在認証されたユーザーアカウントで動作します。 ですので、明示的に "ユーザー名"パラメータを持たないのです。

Details

You can get the home location and the displayname of the user, by using あなたは、使用している所在地と表示名を取得することができます 

GET /api/0.6/user/details

this returns an XML document of the from 

<osm version="0.6" generator="OpenStreetMap server">
 <user display_name="Max Muster" account_created="2006-07-21T19:28:26Z" id="1234">
   <home lat="49.4733718952806" lon="8.89285988577866" zoom="3"/>
   <description>The description of your profile</description>
   <languages>
     <lang>de-DE</lang>
     <lang>de</lang>
     <lang>en-US</lang>
     <lang>en</lang>
   </languages>
 </user>
</osm>

Preferences

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

You can retrieve the list of current preferences using 

 GET /api/0.6/user/preferences

this returns an XML document of the form 

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

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

Also possible is to PUT a single preference using 

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

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

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

When NOT to use the API

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

Further Reading

Retrieved from "http://wiki.openstreetmap.org/wiki/JA:API_v0.6"
Personal tools
Namespaces
Variants
Actions
site
Toolbox