JA:API v0.6

From OpenStreetMap Wiki
Jump to: navigation, search
利用できる言語 — API v0.6
Afrikaans Alemannisch aragonés asturianu azərbaycanca Bahasa Indonesia Bahasa Melayu Bân-lâm-gú Basa Jawa Baso Minangkabau bosanski brezhoneg català čeština dansk Deutsch eesti English español Esperanto estremeñu euskara français Frysk Gaeilge Gàidhlig galego Hausa hrvatski Igbo interlingua Interlingue isiXhosa isiZulu íslenska italiano Kiswahili Kreyòl ayisyen kréyòl gwadloupéyen Kurdî latviešu Lëtzebuergesch lietuvių magyar Malagasy Malti Nederlands Nedersaksies norsk bokmål norsk nynorsk occitan Oromoo oʻzbekcha/ўзбекча Plattdüütsch polski português português do Brasil română shqip slovenčina slovenščina Soomaaliga suomi svenska Tiếng Việt Türkçe Vahcuengh vèneto Wolof Yorùbá Zazaki српски / srpski беларуская български қазақша македонски монгол русский тоҷикӣ українська Ελληνικά Հայերեն ქართული नेपाली मराठी हिन्दी অসমীয়া বাংলা ਪੰਜਾਬੀ ગુજરાતી ଓଡ଼ିଆ தமிழ் తెలుగు ಕನ್ನಡ മലയാളം සිංහල ไทย မြန်မာဘာသာ ລາວ ភាសាខ្មែរ ⵜⴰⵎⴰⵣⵉⵖⵜ አማርኛ 한국어 日本語 中文(简体)‎ 吴语 粵語 中文(繁體)‎ ייִדיש עברית اردو العربية پښتو سنڌي فارسی ދިވެހިބަސް
その他の言語このウィキの翻訳を支援してください

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

This page was updated in March 2012 to reflect small changes applied since then, and in April 2013 after the addition of the Map Notes API.

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 呼び出しでPUT、DELETE メソッドを使用しますが、あなたが使っているクライアントの HTTP スタックではそれを使えないかも知れません。そのスタックの作者に、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 ドキュメントは例として提供していることに注意してください。

  • version の minimum と maximum は、サーバーが受け付ける API 呼び出しのバージョンです。
  • area の maximum は、API 呼び出しで問い合わせられる最大領域を、平方度で表します。
  • tracepoints の per_page は、1つの GPS トレースの最大ポイント数です (場合により不正確)。
  • waynodes の maximum は、ウェイに含められるノードの最大数です。
  • changesets の maximum は、変更セットに含められる、ノード、ウェイ、リレーションの組み合わせの最大数です。

注意

  • この URL にはバージョンがないことに注意してください。利便性のため、サーバーは /api/0.6/capabilities というリクエストもサポートしています。これにより、クライアントはすべてのリクエストで、同じ URL プレフィックス http:/.../api/0.6 を使用できます。

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

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

  • 与えられた境界ボックスの内側にあるすべてのノードと、それを参照しているリレーション。
  • 与えられた境界ボックスの内側にあるノードを、少なくともひとつ参照しているすべてのウェイと、そのウェイを参照しているリレーション、およびそのウェイが参照している境界ボックスの外側のノード。
  • 上記の規則で選択したノードやウェイの1つを参照しているリレーション (再帰的には適用しません)。
GET /api/0.6/map?bbox=left,bottom,right,top

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

  • left は、境界ボックスの左 (西端) 側の経度です。
  • bottom は、境界ボックスの下 (南端) 側の緯度です。
  • right は、境界ボックスの右 (東端) 側の経度です。
  • top は、境界ボックスの上 (北端) 側の緯度です。

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

  • イングランドにあるすべてのノードを参照している "England" というリレーションがあります。
  • イングランドの小さい部分をカバーする境界ボックスで、ノード、ウェイ、リレーションを取得します。

コマンドの規則によって指定したノード、ウェイ、リレーションが、("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変更セットに 50,000 編集以上 特定の制限参照
  • 変更セットが開かれてから、24時間以上経過
  • 1時間の間、変更セットに関連する変更・API呼び出しがない (いわゆるアイドルタイムアウト)

変更セットは特に不可分(アトミック)ではありません。変更セットで追加した要素は、変更セットを閉じる前に、他のユーザーから見えることになります。与えられたいくつもの変更を、一度にアップロードすることは、実現不可能です。その代わりに、前述の楽観的ロックを用います。サーバーに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要素がある場合、それらすべての中のタグが使われます。キーが重複すると、後のもので前のものを上書きします。

レスポンス

新しく作成した変更セットの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 に該当する変更セットが見つからない場合

注意

  • API v0.5からAPI v0.6への移行の際に自動生成された変更セットでは、uidが得られません。
  • 空の変更セットでは、境界ボックスの属性がありません。
  • 変更セットの境界ボックスは、その変更セットで変更されたすべてのオブジェクトの外接矩形を含むような矩形です。そのような条件を満たす最小の矩形とは限りません。
  • このAPI呼び出しは、変更セットそのものに関する情報だけを返すもので、変更セット内で行われた実際の要素に対する変更に関する情報は返しません。そのような情報を得るにはdownload API呼び出しを使います。

更新: PUT /api/0.6/changeset/#id

変更セットに付いているタグ(例: changeset comment=foo )を更新します。

ペイロードは、ある一つの変更セットの新規バージョンを含むOSMドキュメントであるべきです。このメソッドでは境界ボックス、更新日時、その他の属性は無視され、更新されません。境界ボックスの更新については、expand_bboxメソッドを参照してください。

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

パラメータ

id
更新する変更セットのID。このAPI呼び出しを発行するユーザーは、変更セットを作成したユーザーと同一である必要があります。

レスポンス

変更セットの新しいバージョンを含むOSMドキュメントを、コンテントタイプ text/xml で返します。

エラーコード

HTTP ステータスコード 400 (Bad Request)
XML の解析でエラー発生時
HTTP ステータスコード 404 (Not Found)
与えた id に該当する変更セットが見つからない場合
HTTP ステータスコード 405 (Method Not Allowed)
リクエストが HTTP PUT リクエストではない場合
HTTP ステータスコード 409 (Conflict) - text/plain
対象の変更セットがすでに閉じられている場合(ユーザー自身によるか、自動的に閉じる機構の結果として)。"The changeset #id was closed at #closed_at." という形式のメッセージが返されます
または変更セットを更新しようとしているユーザーが、作成したユーザーと同一でない場合

注意

変更しないタグも、削除されないように再記述される必要があります。

閉じる: PUT /api/0.6/changeset/#id/close

変更セットを閉じます。所有者がこのAPI呼び出しを発行しなくても、変更セットがすでに閉じられれている場合があります。そのような場合にはエラーコードが返ります。

パラメータ

id
閉じる変更セットのID。このAPI呼び出しを発行するユーザーは、変更セットを作成したユーザーと同一である必要があります。

レスポンス

変更セットを閉じることに成功したときは何も返りません (HTTP ステータスコード 200)。

エラーコード

HTTP ステータスコード 404 (Not Found)
与えた id に該当する変更セットが見つからない場合
HTTP ステータスコード 405 (Method Not Allowed)
リクエストが HTTP PUT リクエストではない場合
HTTP ステータスコード 409 (Conflict) - text/plain
対象の変更セットがすでに閉じられている場合(ユーザー自身によるか、自動的に閉じる機構の結果として)。"The changeset #id was closed at #closed_at." という形式のメッセージが返されます
または変更セットを閉じようとしているユーザーが、作成したユーザーと同一でない場合

ダウンロード: GET /api/0.6/changeset/#id/download

変更セットに関連付けられたすべての変更を記述する OsmChange ドキュメントを返します。

パラメータ

id
OsmChange を取得したい変更セットのID。

レスポンス

OsmChange XML を、コンテントタイプ text/xml で返します。

エラーコード

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

注意

  • 変更セットが開いている期間は、この呼び出しの結果が変わることがあります。
  • OsmChange 内の要素はタイムスタンプとバージョン番号でソートされます。

境界ボックスを拡張する: POST /api/0.6/changeset/#id/expand_bbox

この場所まで、を示すnode 要素を含むXMLドキュメントをPOSTします。(ここでの node 要素は、このページの他の部分で使われているノードとは関係ありません。) APIにより自動的に計算された境界ボックスと、指定された点を含むような厳密に最小の包含矩形まで、変更セットの境界ボックスが拡張されます。したがってこの呼び出しは境界ボックスのサイズを拡大することのみが可能です。拡張された境界ボックスは、その後の変更セットへの追加によって上書きされることがあります。

入力するドキュメントは次のようなものであるべきです:

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

osm要素はnode以外の要素を含んでも構いませんが、それらは無視されます。node要素はlatとlon以外の属性(idなど)を含んでも構いませんが、それらも無視されます。

この呼び出しは、変更セットに対してAPIが自動的に計算した境界ボックスを、エディターが拡張できるように用意されています。 APIが変更内容のみから推定するより広い領域が適切だと助言できる何らかの情報を、エディターが持っている場合があります。多数の変更をアップロードする前に、どの領域が影響を受けるかサーバーにヒントを送るために、使われるかも知れません。

パラメータ

id
境界ボックスを拡張しようとする変更セットのID。

レスポンス

更新された変更セットをコンテントタイプ text/xml で返します。

エラーコード

HTTP ステータスコード 404 (Not Found)
与えた id に該当する変更セットが見つからない場合
HTTP ステータスコード 409 (Conflict) - text/plain
対象の変更セットがすでに閉じられている場合(ユーザー自身によるか、自動的に閉じる機構の結果として)。"The changeset #id was closed at #closed_at." という形式のメッセージが返されます
または変更セットを更新しようとしているユーザーが、作成したユーザーと同一でない場合

注意

  • 大量の変更がアップロードされる前にexpand_bbox呼び出しを発行すると、実際に何か利点があるか、定かではありません。
  • XML要素の名前としてのnodeの重複利用が紛らわしいため、この呼び出しの形式は将来のAPIバージョンで変わるかも知れません。

問い合わせ: GET /api/0.6/changesets

変更セットを問い合わせるAPIメソッドです。さまざまな基準での問い合わせができます。

複数の問い合わせが指定されたとき、すべての問い合わせに合致するものが結果となります。返されるドキュメントの内容は、変更セット(複数)とそのタグです。変更セットに関連付けられた変更のすべてを取得するには、それぞれの変更セットのIDについて個別にdownloadメソッドを使います。

変更セットに対するロールバックやその他の操作をサポートするため、基本的な問い合わせを改善したり拡張したりする必要がありそうです。

パラメータ

bbox=min_lon,min_lat,max_lon,max_lat (W,S,E,N)
指定された境界ボックスの内部の変更セットを探します
user=#uid or display_name=#name
指定されたユーザーIDまたは表示名を持つユーザーによる変更セットを探します。両方を指定するとエラーになります。
time=T1
T1の後に閉じられた変更セットを探します
time=T1,T2
T1の後かつT2の前に閉じられた変更セットを探します
open
まだ開いている変更セットのみを探します。閉じられた変更セットや、1つの変更セットの要素の上限(一度に50,000)に達した変更セットは除きます。
closed
閉じられた変更セットまたは要素の上限に達して変更セットのみを探します

時刻の形式: このRuby関数で解釈できるすべて。デフォルト文字列は’-4712-01-01T00:00:00+00:00’で、これはユリウス通日での0日です。

レスポンス

作成日時でソートされたすべての変更セットのリストを返します。問い合わせの結果が存在しない場合は、<osm>要素は空になります。レスポンスはコンテントタイプ text/xml で送られます。

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
形式の正しくないパラメータ。エラーを説明するテキストメッセージが返されます。典型的には、ユーザー問い合わせのパラメータとしてUIDと表示名の両方を指定しようとすると、このエラーになります。
HTTP ステータスコード 404 (Not Found)
指定されたuidまたはdisplay_nameを持つユーザーが見つからない場合。

注意

  • 公式なユーザーによる変更セットのみが返ります。
  • 時刻による問い合わせが現時点での実装で意味があるか定かではありません。この機能に関する元の文書では:
    • One-sided to query changesets where the start time is after the given time.
    • Bounded (?time=T1,T2) to query where the start time is between the given times.
  • 最大で100個の変更セットを返します。

差分アップロード: POST /api/0.6/changeset/#id/upload

このAPI呼び出しでOsmChange形式のファイルをサーバーにアップロードすることができます。トランザクションで実行されることが保証されます。したがってすべての変更が適用されるか、またはまったく適用されないか、です。

OSCファイルをアップロードする場合、OsmChangeの仕様を満たすために以下の追加をする必要があります。

  • 各要素はchangeset属性とversion属性を持たなければなりません。要素を新たに作成する場合は例外で、サーバーがバージョンをセットするのでバージョンは必要ありません。changesetはアップロードしようとしてる変更セットのIDと同一でなければなりません。
  • OsmChangeドキュメント内の<delete>ブロックは、if-unused属性(値は無視される)を持つことができます。この属性がある場合、このブロック内の削除処理は条件付きであり、削除しようとするオブジェクトが他のオブジェクトから使われていない場合にのみ実行されます。if-unusedを持たない場合、そのような状況はエラーとなり、差分アップロード全体が失敗します。

パラメータ

id
差分が属している変更セットのID。
POST data
OsmChangeファイルデータ

レスポンス

差分の適用が成功した場合、XML(コンテントタイプ text/xml)が、一つの要素について以下の形式で、

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

アップロードされたすべての要素に対して返されます。同じ要素が複数回、入力の中に含まれていた場合、出力の中にも複数回現れるので、直観に反するかも知れず、注意が必要です。

属性 作成 変更 削除
old_id アップロードされた要素と同じ
new_id 新しいID アップロードと同じ 存在しない
new_version 新しいバージョン 存在しない

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
XML の解析でエラー発生時。エラーを説明するテキストメッセージが返ります。
プレースホルダーのIDが無いか一意でない場合
HTTP ステータスコード 405 (Method Not Allowed)
リクエストがHTTP POSTリクエストでない場合
HTTP ステータスコード 409 (Conflict) - text/plain
対象の変更セットがすでに閉じられている場合(ユーザー自身によるか、自動的に閉じる機構の結果として)。"The changeset #id was closed at #closed_at." という形式のメッセージが返されます
アップロード中に変更セットの最大サイズが超過した場合。"The changeset #id was closed at #closed_at." という形式のメッセージが返されます
または変更セットを更新しようとしているユーザーが、作成したユーザーと同一でない場合
または差分アップロードしようとしている変更セットのIDと一致しない変更セットIDを持つ要素が差分に含まれている場合
要素の生成、変更、削除 処理の際に起きるエラーのコード
このページの対応する章を参照してください

注意

  • 最初のエラーで処理が止まるので、一つの差分アップロードの中に複数の矛盾があっても、最初の問題だけが報告されます。
  • 現在は差分のサイズに上限はありませんが、今後、変更される見込みです。

変更セットのまとめ

変更セットの生成が成功した場合の手順は、大まかに次の図のとおりです:

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

要素

OpenStreetMapの3つの基本要素(ノードウェイリレーション)のすべてに対して、生成、参照、更新、削除の呼び出しがあります。ペイロードと多少の特別なエラーメッセージを除いて、これらの呼び出しは似通っているので、一度に記述します。

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

指定されたタイプの要素を作成します。リクエスト全体が
<osm>...</osm>
要素に包まれている必要があることに注意してください。

ノード:

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

ウェイ:

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

リレーション:

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

複数の要素が指定されても、最初の要素のみが作成されます。残りは捨てられます。(この動作は変更セットの生成と異なります)

レスポンス

新しく作成された要素のID (コンテントタイプはtext/plain)

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
XML の解析でエラー発生時。エラーを説明するテキストメッセージが返ります。
変更セットのIDが無い場合 (残念ながらエラーメッセージに一貫性がありません)
ノードが世界の外側にある場合
一つのウェイに対するノードが多すぎる場合
HTTP ステータスコード 405 (Method Not Allowed)
リクエストがHTTP PUTリクエストでない場合
HTTP ステータスコード 409 (Conflict) - text/plain
対象の変更セットがすでに閉じられている場合(ユーザー自身によるか、自動的に閉じる機構の結果として)。"The changeset #id was closed at #closed_at." という形式のメッセージが返されます
または変更セットを更新しようとしているユーザーが、作成したユーザーと同一でない場合
HTTP ステータスコード 412 (Precondition Failed)
存在しないノードか、不可視な(つまり削除された)ノードがウェイに含まれているとき: "Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible."
存在しない要素か不可視な要素がリレーションに含まれているとき: "Relation with id #{id} cannot be saved due to #{element} with id #{element.id}"

注意

  • この呼び出しは変更セットの境界ボックスを変更します。
  • リレーションのrole属性はオプションです。空の文字列がデフォルトです。

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

要素のXML表現を返します。

レスポンス

要素のXML表現で、<osm>要素で包まれています:

<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)
指定されたIDを持つ要素が見つからない場合
HTTP ステータスコード 410 (Gone)
要素が削除されている場合

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

すでに存在している要素のデータを更新します。要素が更新後にそうなっているべき完全な表現を指定する必要があります。したがって変更されずに残っているべきタグもすべて更新データに入っていなければなりません。バージョン番号も指定する必要があります。

レスポンス

新しいバージョン番号が、コンテントタイプtext/plainで返されます。

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
XML の解析でエラー発生時。エラーを説明するテキストメッセージが返ります。Content-Lengthヘッダーを送るのを忘れた場合もこのエラーが起きます。
変更セットのIDが無い場合 (残念ながらエラーメッセージに一貫性がありません)
ノードが世界の外側にある場合
一つのウェイに対するノードが多すぎる場合
指定された要素のバージョンが、現在のデータベース内の要素のバージョンと一致しないとき
HTTP ステータスコード 409 (Conflict) - text/plain
対象の変更セットがすでに閉じられている場合(ユーザー自身によるか、自動的に閉じる機構の結果として)。"The changeset #id was closed at #closed_at." という形式のメッセージが返されます
または変更セットを更新しようとしているユーザーが、作成したユーザーと同一でない場合
HTTP ステータスコード 404 (Not Found)
指定されたIDを持つ要素が見つからない場合
HTTP ステータスコード 412 (Precondition Failed)
存在しないノードか、不可視な(つまり削除された)ノードがウェイに含まれているとき: "Way #{id} requires the nodes with id in (#{missing_ids}), which either do not exist, or are not visible."
存在しない要素か不可視な要素がリレーションに含まれているとき: "Relation with id #{id} cannot be saved due to #{element} with id #{element.id}"

注意

  • この呼び出しは変更セットの境界ボックスを変更します。

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

有効にXML表現された要素が削除されるように要求します。

例:

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

ノードのIDはURLに含まれるIDと一致しなければなりません。バージョンはダウンロードした要素のバージョンと、変更セットは現在の認証済みユーザーが所有する開いている変更セットのIDと、一致しなければなりません。必須のlat/lonタグ以外のタグは必要ではありませんが、付いていても構いません。http://web.archiveorange.com/archive/v/wQWIbRy3o8HjRNYaSim9 に書かれているように、また2011-05-30に確認したところでも、lat+lonが無いとサーバーは400 Bad requestを返します。

レスポンス

新しいバージョン番号が、コンテントタイプtext/plainで返されます。

エラーコード

HTTP ステータスコード 400 (Bad Request) - text/plain
XML の解析でエラー発生時。エラーを説明するテキストメッセージが返ります。
変更セットのIDが無い場合 (残念ながらエラーメッセージに一貫性がありません)
ノードが世界の外側にある場合
一つのウェイに対するノードが多すぎる場合
指定された要素のバージョンが、現在のデータベース内の要素のバージョンと一致しないとき
HTTP ステータスコード 404 (Not Found)
指定されたIDを持つ要素が見つからない場合
HTTP ステータスコード 409 (Conflict) - text/plain
対象の変更セットがすでに閉じられている場合(ユーザー自身によるか、自動的に閉じる機構の結果として)。"The changeset #id was closed at #closed_at." という形式のメッセージが返されます
または変更セットを更新しようとしているユーザーが、作成したユーザーと同一でない場合
HTTP ステータスコード 410 (Gone)
要素がすでに削除されている場合
HTTP ステータスコード 412 (Precondition Failed)
ノードがまだウェイに使われている場合: Node #{id} is still used by way #{way.id}.
ノードがまだリレーションのメンバーである場合: Node #{id} is still used by relation #{relation.id}.
ウェイがまだリレーションのメンバーである場合: Way #{id} still used by relation #{relation.id}.
リレーションがまだ他のリレーションのメンバーである場合: The relation #{id} is used in relation #{relation.id}.

注意

  • 以前のAPIバージョンではペイロードは必要ではありませんでした。現在は変更セットIDとバージョン番号のために必要です。

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

ある要素の古いバージョンをすべて取り出します。

エラーコード

HTTP ステータスコード 404 (Not Found)
指定されたIDを持つ要素が見つからない場合

バージョン: GET /api/0.6/[node|way|relation]/#id/#version

ある要素の特定のバージョンを取り出します。

エラーコード

HTTP ステータスコード 404 (Not Found)
指定されたIDを持つ要素が見つからない場合

複数取得: GET /api/0.6/[nodes|ways|relations]

複数の要素を一度に取得します。

パラメータ

[nodes|ways|relations]=comma separated list
パラメータはURL内のものと同じである必要があります(例えば /api/0.6/nodes?nodes=123,456,789)

エラーコード

HTTP ステータスコード 400 (Bad Request)
形式が正しくないリクエスト(パラメータが無いか、正しくない)
HTTP ステータスコード 404 (Not Found)
要素のいずれかが見つからない場合
HTTP ステータスコード 414 (Request-URI Too Large)
URIが長すぎた場合 (どれくらい長ければ長すぎるのか?)

要素に関するリレーション: GET /api/0.6/[node|way|relation]/#id/relations

指定された要素が使われているすべての(削除されていない)リレーションを含むXMLドキュメントを返します。

注意

  • 要素が存在しない場合はエラーになりません。
  • 要素が存在しないか、どのリレーションからも使われていない場合、空のXMLドキュメントが返ります(<osm>要素は別として)

ノードに関するウェイ: GET /api/0.6/node/#id/ways

指定されたノードが使われているすべての(削除されていない)ウェイを含むXMLドキュメントを返します。

注意

  • ノードが存在しない場合はエラーになりません。
  • ノードが存在しないか、どのウェイからも使われていない場合、空のXMLドキュメントが返ります(<osm>要素は別として)

全取得: GET /api/0.6/[way|relation]/#id/full

このAPI呼び出しは、あるウェイかリレーションと、それが参照するすべての他の要素とを取得します

  • ウェイの場合、指定されたウェイと、ウェイに参照されるすべてのノードの完全なXMLを返します。
  • リレーションの場合、以下を返します:
    • そのリレーション自身
    • リレーションのメンバーであるノード、ウェイ、リレーションすべて
    • 加えて、前段階で得られるウェイに使われているすべてのノード
    • 同様の再帰ロジックはリレーションには適用されません。すなわち、もしリレーションr1がウェイw1とリレーションr2を含み、w1はノードn1とn2を含み、r2はノードn3を含む場合、r1に対する"full"リクエストはr1、r2、w1、n1、n2を返しn3は返しません。

エラーコード

HTTP ステータスコード 404 (Not Found)
指定されたIDを持つ要素が見つからない場合
HTTP ステータスコード 410 (Gone)
要素が削除されている場合

GPS トレース

GPS ポイントの取得

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

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

ただし:

  • left, bottom, right, top は、ノード・ウェイ・リレーションを取得するコマンドと同じように使われます。
  • pageNumber には、返されるべき 5,000 個ごとのポイントのグループ (ページ) を指定します。このコマンドは 5,000 個のポイントまでしか返しませんので、5,000 個を超えるポイントがある境界ボックスからすべてのポイントを取得する場合、このパラメーターを増加させてコマンドを (同じ境界ボックスで) 再送しなければなりません。このパラメーターに 0 (ゼロ) を指定すると、先頭から 5,000 個のポイントを返します。また、1 を指定すると 5,001–10,000 のポイントを返します。

境界ボックスにある、先頭から 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 pageJA: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

ユーザー情報に関するメソッド

特に断りのない限り、すべてのユーザー固有のAPI呼び出しが認証を必要とし、その時点で認証されているユーザーアカウントで動作します。 それぞれの呼び出しが明示的に "username" パラメータを持たないのはそのためです。

詳細

GET /api/0.6/user/details

を使って、ユーザーの本拠地と表示名を得ることができます。 以下のような形式のXMLドキュメントが返ります。

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

ユーザー設定

OSMサーバーに任意のユーザー設定を格納することができます。例えば、エディタはローカルに保存する設定の代わりに、ユーザーがどこからログインしても同じ設定が使えるような目的でこれを使うことができます。

 GET /api/0.6/user/preferences

を使って現在のユーザー設定のリストを取り出せます。 次のような形式のXMLドキュメントが返ります。

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

同じ形式でユーザー設定をアップロードできます(GETメソッドの代わりにPUTを使って)。既存のユーザー設定はすべて、新しくアップロードされたセットで置き換えられます。

 PUT /api/0.6/user/preferences/[your_key] (大かっこ無しで)

を使えば1項目だけのユーザー設定をPUTできます。

この例では、リクエストのペイロードはユーザー設定の値のみを含むべきです。つまりXMLフォーマットではありません。

同じキーが2度以上出現する場合はHTTPレスポンスコード406(not acceptable)が、150を超えるユーザー設定項目をアップロードしようとした場合は413(request entity too large)が、PUT呼び出しから返ります。キーと値のサイズは255文字までに制限されます。

地図メモ API

This provides access to the notes feature, which allows users to add geo-referenced textual "post-it" notes. This feature was not originally in the API 0.6 and was only added later ( 04/23/2013 in commit 0c8ad2f86edefed72052b402742cadedb0d674d9 )

Retrieving bug data by bounding box: GET /api/0.6/notes

Returns the existing notes in the specified bounding box. The notes will be ordered by the date of their last change, the most recent one will be first. The list of notes can be returned in several different forms (e.g. as executable JavaScript, XML, RSS, json and GPX) depending on the file extension.


URL: http://api.openstreetmap.org/api/0.6/notes?bbox=left,bottom,right,top (example)
コンテンツタイプ: application/xml


パラメータ 説明 使用可能な値 デフォルト値
bbox Coordinates for the area to retrieve the bugs from 角度の浮動小数点数 デフォルト値は指定されていません。値の指定は必須です。
limit 最大何件の地図メモが返ってくるかを指定します 1 から 10000 が許可されます 100
closed Specifies the number of days a bug needs to be closed to no longer be returned A value of 0 means only open bugs are returned. A value of -1 means all bugs are returned. 7

You can specify the format you want the results returned as by specifying a file extension. E.g. example to get results in json. Currently the format RSS, XML, json and gpx are supported.

エラーコード

HTTP ステータスコード 400 (Bad Request)
When any of the limits are crossed

Read: GET /api/0.6/notes/#id

Returns the existing note with the given ID. The output can be in several formats (e.g. XML, RSS, json or GPX) depending on the file extension.


URL: http://api.openstreetmap.org/api/0.6/notes/#id ([1])
コンテンツタイプ: application/xml

エラーコード

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

メモを作成する: Create: POST /api/0.6/notes

新しい地図メモを作成します


URL: http://api.openstreetmap.org/api/0.6/notes?lat=51.00&lon=0.1&text=ThisIsANote (example)
コンテンツタイプ: application/xml


パラメータ 説明 使用可能な値 デフォルト値
lat 地図メモの緯度を指定します 角度の浮動小数点数 デフォルト値は指定されていません。値の指定は必須です。
lon 地図メモの経度を指定します 角度の浮動小数点数 デフォルト値は指定されていません。値の指定は必須です。
text A text field with arbitrary text containing the note No default, needs to be present

リクエストがOSMで認証されたユーザで行われた場合、そのメモは認証されたユーザーのアカウントに関連付けられます。

エラーコード

HTTP ステータスコード 400 (Bad Request)
text に何も存在しなかった時に返します
HTTP ステータスコード 405 (Method Not Allowed)
POST でリクエストをしなかった時に返します

コメントの作成: Create: POST /api/0.6/notes/#id/comment

メモ #id に新しいコメントを追加します

URL: http://api.openstreetmap.org/api/0.6/notes/#id/comment?text=ThisIsABugComment (example)
Return type: application/xml

パラメータ 説明 使用可能な値 デフォルト値
text コメントの内容 任意の文字列 デフォルト値は指定されていません。何かしらの値が必須です。


エラーコード

HTTP ステータスコード 400 (Bad Request)
text に何も存在しなかった時に返します
HTTP ステータスコード 404 (Not found)
if no bug with that id is not available
HTTP ステータスコード 405 (Method Not Allowed)
POST でリクエストをしなかった時に返します

メモの解決: POST /api/0.6/notes/#id/close

メモを解決したものとして閉じます。


URL: http://api.openstreetmap.org/api/0.6/notes/#id/close?text=Comment (example)
コンテンツタイプ: application/xml

このリクエストをするにはユーザ認証を事前に行っておく必要があります。

エラーコード

HTTP ステータスコード 404 (Not Found)
When no bug with the given id could be found
HTTP ステータスコード 405 (Method Not Allowed)
POST でリクエストをしなかった時に返します

メモの再開: POST /api/0.6/notes/#id/reopen

解決したメモを再開する。


URL: http://api.openstreetmap.org/api/0.6/notes/#id/reopen?text=Comment (example)
コンテンツタイプ: application/xml

このリクエストをするにはユーザ認証を事前に行っておく必要があります。

エラーコード

HTTP ステータスコード 404 (Not Found)
When no bug with the given id could be found
HTTP ステータスコード 405 (Method Not Allowed)
POST でリクエストをしなかった時に返します
HTTP ステータスコード 409 (Conflict)
When reopening an already closed note
HTTP ステータスコード 410 (Gone)
When reopening a deleted note

Search for notes on text and comments: GET /api/0.6/notes/search

Returns the existing notes matching either the initial note text or any of the comments. The notes will be ordered by the date of their last change, the most recent one will be first. The list of notes can be returned in several different forms (e.g. XML, RSS, json or GPX) depending on file extension given.


URL: http://api.openstreetmap.org/api/0.6/notes/search?q=SearchTerm (example)
コンテンツタイプ: application/xml


パラメータ 説明 使用可能な値 デフォルト値
q Specified the search query 文字列 none, parameter required
limit 最大何件の地図メモが返ってくるかを指定します 1 から 10000 が許可されます 100
closed Specifies the number of days a bug needs to be closed to no longer be returned A value of 0 means only open bugs are returned. A value of -1 means all bugs are returned. 7

エラーコード

HTTP ステータスコード 400 (Bad Request)
When any of the limits are crossed

APIを使うべきでない場合

大量のアップロードやデータ更新については、APIは適切な機構ではないでしょう。よりモダンな大量アップロード・修正スクリプトが、変更セットを構築し、それをJOSMのようなエディタにロードし、コミットの前に内容が検証されるべきです。アトミックなやり方で変更セットをアップロードするために、APIを使うこともできます。http://wiki.openstreetmap.org/wiki/Change_File_Formats も参照してください。

より詳しく