JA:API v0.6

From OpenStreetMap Wiki
Jump to navigation Jump to search

broom

Help (89606) - The Noun Project.svg

OSM API現在 の最新版は、2009年4月17日-21日にデプロイした API v0.6 です(※注記と※別記参照)。

※注記:この API は、バージョン番号の更新を行いません。2020年3月時点の版は 0.6.6 に相当すると推定されます。時系列で新しい順に、次のおもな更新が行われています。(※別記に経緯の説明あり、日本語版の翻訳は遅れている場合があります。)

  • 2020年9月、ユーザーの詳細に JSON サポートを追加。
  • 2020年3月、OSM 要素のエンドポイントにサポートを追加。
  • 2019年以前
    • 2019年12月、エンドポイント expand_bbox を除去。
    • 2018年7月、巻き戻し可能で微細な変更点が複数。
    • 2016年1月、変更セットの議論の追加。
    • 2013年4月、地図メモ API の追加。
    • 2012年3月、小さな変更。

全般情報

この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 で認証が必要です。読み込みリクエストには、(ユーザーの詳細を除き) 認証は必要ありません。


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

URL + 認証

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

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

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

エラーコード

HTTP ステータスコード 400 (Bad request)
API の cgimap バージョンを開いているユーザーにこのメッセージが表示される場合は、OAuth(統合ログイン)に対して "Bad OAuth request." エラーが返り、処理に失敗したことを示します
HTTP ステータスコード 401 (Unauthorized)
ログインに失敗しています
HTTP ステータスコード 403 (Forbidden)
ログインに成功したユーザーがブロックされていると、アプリケーションは設定上、エラーメッセージを表示することになっていて(必要な場合という意味合いで)、エンドユーザー向け UI が導入済みの場合は openstreetmap.org に簡単にアクセスし、遷移先のメッセージを閲覧する方法が示されます

要素(Element)

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

変更セット(Changeset)

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

タグ(Tag)

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

文字列の最大長

現在の Ruby on Rails の API の実装はオブジェクト、変更セットキー、ユーザ設定やリレーションメンバーのロールのタグや値の文字の長さを制限しています。

注意:制限値は本当に255文字であり256文字ではありません。

確実なユーザーの識別

以前の 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 属性は省略できます。

JSON フォーマット

OSM API JSON フォーマットOverpass API JSON フォーマットの解説文書に基づいており、以下のエンドポイントに対応しています。

  • 境界ボックスを使ってマップデータを取り込む:GET /api/0.6/map
  • 閲覧(Read):GET /api/0.6/[node|way|relation]/#id
  • 履歴(History):GET /api/0.6/[node|way|relation]/#id/history
  • バージョン(Version):GET /api/0.6/[node|way|relation]/#id/#version
  • Multi fetch: GET /api/0.6/[nodes|ways|relations]?#parameters
  • 地物のリレーション(Relations for element):GET /api/0.6/[node|way|relation]/#id/relations
  • ノードのウェイ(Ways for node):GET /api/0.6/node/#id/ways
  • Full: GET /api/0.6/[way|relation]/#id/full

JSON フォーマットをリクエストするには、HTTP アクセプトヘッダの設定をapplication/jsonにするか、URL 接頭辞として.jsonを使います。

(Github issue)

正しい 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 呼び出し

雑記


利用可能な API バージョン: GET /api/versions

現時点でサポートしている API バージョンの一覧を返します。

<?xml version="1.0" encoding="UTF-8"?>
<osm generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
  <api>
    <version>0.6</version>
  </api>
</osm>

機能: GET /api/capabilities

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

レスポンス

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

<?xml version="1.0" encoding="UTF-8"?>
<osm version="0.6" generator="OpenStreetMap server" copyright="OpenStreetMap and contributors" attribution="http://www.openstreetmap.org/copyright" license="http://opendatacommons.org/licenses/odbl/1-0/">
  <api>
    <version minimum="0.6" maximum="0.6"/>
    <area maximum="0.25"/>
    <note_area maximum="25"/>
    <tracepoints per_page="5000"/>
    <waynodes maximum="2000"/>
    <changesets maximum_elements="10000"/>
    <timeout seconds="300"/>
    <status database="online" api="online" gpx="online"/>
  </api>
  <policy>
    <imagery>
      <blacklist regex=".*\.google(apis)?\..*/(vt|kh)[\?/].*([xyz]=.*){3}.*"/>
      <blacklist regex="http://xdworld\.vworld\.kr:8080/.*"/>
      <blacklist regex=".*\.here\.com[/:].*"/>
    </imagery>
  </policy>
</osm>

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

  • 著作権、継承、ライセンス要件: 法的情報を参照

API:

  • version の minimum と maximum は、サーバーが受け付ける API 呼び出しのバージョンです。
  • area の maximum は、API 呼び出しで問い合わせ可能な最大領域を、平方度で表します。
  • tracepoints の per_page は、1つの GPS トレースの最大ポイント数です (場合により不正確)。
  • waynodes の maximum は、ウェイに含められるノードの最大数です。
  • changesets の maximum は、変更セットに含められる、ノード、ウェイ、リレーションの組み合わせの最大数です。
  • status の要素はデータベースや API、GPX API 単位でオンライン、読み取り専用もしくはオフラインかどうか示します。データベース欄は情報提供用、API/GPX-API 欄はむしろクライアント側で対応するのがリードライト要求か (オンライン)、リードオンリー要求か (readonly) もしくは要求に応じないか (オフライン) を見込むためにあります。

方針:

  • Imagery blacklist にはエリアスでも地図でもソースのうち、著作権により OSM で使用が許諾されないものをリストしてあります。背景のレイヤーとして、これらのリソースを表示してはいけません。

注意

  • この URL にはバージョンがないことに注意してください。利便性のため、サーバーは /api/0.6/capabilities というリクエストもサポートしています。これにより、クライアントはすべてのリクエストで、同じ URL プレフィックス http:/.../api/0.6 を使用できます。
  • 要素とリレーションのメンバーの ID は処理系の依存により現在符号付き 64bit の整数に制約されていますが、これが問題になることはないでしょう。

境界ボックス(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)
ノード・ウェイ・リレーションの上限を超え、特に返すノードが 50'000 超の場合。このコードが適用される他の場合については、上記を参照。
HTTP ステータスコード 509 (Bandwidth Limit Exceeded)
"Error: You have downloaded too much data. Please try again later." ダウンロードしたデータ量が多すぎるというエラーです。Developer FAQ を参照

パーミッションを取り付ける: GET /api/0.6/permissions

現在の API 接続に対してパーミッション承認を返します。

  • もし API クライアントが承認されない場合、空のパーミッションリストを返します。
  • もし API クライアントが Basic Auth を利用する場合、すべてのパーミッションをリストして返します。
  • もし API クライアントが OAuth を利用する場合、実際に利用者が承認するパーミッションに限定して返します。
GET /api/0.6/permissions

レスポンス

返すのは、パーミッションのタグからなる1件のパーミッション要素 (コンテンツタイプは text/xml)

 <?xml version="1.0" encoding="UTF-8"?>
 <osm version="0.6" generator="OpenStreetMap server">
   <permissions>
     <permission name="allow_read_prefs"/>
     ...
     <permission name="allow_read_gpx"/>
     <permission name="allow_write_gpx"/>
   </permissions>
 </osm>
 

注記

現状で下記のパーミッションを返してきますが、OAuth 利用の規定に使われたものを直接、反映します。

  • allow_read_prefs (利用者の個人設定を読む)
  • allow_write_prefs (利用者の個人設定を変更)
  • allow_write_diary (ダイアリのエントリ、コメントを作成、 make friends)
  • allow_write_api (地図の修正)
  • allow_read_gpx (非公開の GPS trace を閲覧)
  • allow_write_gpx (GPS trace をアップロード)
  • allow_write_notes (メモをアップロード)

変更セット(changeset)

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

  • 1変更セットに 10,000 編集以上 特定の制限参照
  • 変更セットが開かれてから、24時間以上経過
  • 1時間、変更セットに関連する変更・API呼び出しがない (いわゆるアイドルタイムアウト)

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

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

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

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

境界ボックスの計算

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

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

処理を最大化するため、サーバは オブジェクトよりもわずかに大きなバッファを用意し、境界ボックスを頻繁に更新しなくて済むようにします。そのため、境界ボックスは更新内容と変更セットで異なることがあり、したがって, 境界ボックスの四辺と隣りのノードとの距離にばらつきを生じる可能性があります。

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

変更セット作成リクエストのペイロードには、1つ以上のchangeset要素があり、任意の数の tag をその中に含めることができます。変更セット作成要求のペイロードはこの変更セットのメタデータです。要求の本文には1件以上のchangeset要素を書き、オプションとして任意の数のタグを含めます (たとえば 'comment'、'created_by'等)。changeset要素はすべてosm要素で挟んでください。

<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?include_discussion=true

与えた 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"/>
    ...
    <discussion>
     <comment date="2015-01-01T18:56:48Z" uid="1841" user="metaodi">
       <text>Did you verify those street names?</text>
     </comment>
     <comment date="2015-01-01T18:58:03Z" uid="123" user="fred">
       <text>sure!</text>
     </comment>
     ...
   </discussion>
 </changeset>
</osm>

パラメータ

id
取得する変更セットの id
(new) include_discussion
結果に変更セットの議論を含むかどうかを示します。もし、このパラメータに何らかの値を設定すれば変更セットが返り、このパラメータが空だったり省略された場合は変更セットが結果に返りません。

レスポンス

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 (廃止、除去)

ご注意:このエンドポイントは2019年12月付で削除されました。詳細はこちらの GitHub 案件をご参照ください。

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

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

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

変更セットに対するロールバックやその他の操作をサポートするため、基本的な問い合わせを改善したり拡張したりする必要がありそうです。 この問い合わせは100件を上限に条件に合う変更セットを返し、最新の変更セットを返す並びは created_at 順です[1].


パラメータ

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=true
まだ開いている変更セットのみを探します。閉じられた変更セットや、1つの変更セットの要素の上限(一度に50,000)。(現状では一度に 10.000[2])に達した変更セットは除きます
closed=true
閉じられた変更セットまたは要素の上限に達して変更セットのみを探します
changesets=#cid{,#cid}
特定のID の変更セットを検索します (2013-12-05 以降に有効)

時刻の形式: この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 を持たない場合、そのような状況はエラーとなり、差分アップロード全体が失敗します。また属性を設定するとエラー発生を防ぐため、すでに削除したオブジェクトを再び削除しようとします。
  • OsmChange ドキュメント内には通常、要素ごとに useruid 属性があります。これらは API にアップロードするドキュメント内では不要です。

パラメータ

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が無いか一意でない場合 (this will occur for circular relation references)
HTTP status code 404 (Not Found)
指定した ID の変更セットが見つからない場合
Or when the diff contains elements that could not be found for the given 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を持つ要素が差分に含まれている場合
要素の生成、変更、削除 処理の際に起きるエラーのコード
このページの対応する章を参照してください
その他のステータスコード
いずれかの要素について作成、更新、削除などの操作を行なった結果、さまざまなエラーコードとその関連メッセージが表示されるかもしれません。
詳細はこのページ内の当該の節をご参照ください

注意

  • 最初のエラーで処理が止まるので、1件の差分アップロードの中に複数の矛盾があっても、最初の問題だけが報告されます。
  • 1件の変更セットで上限で何個の変更件数が指定できるか、参照先は /api/capabilities --> changesets -> maximum_elements です。
  • Rails ポートには現状で、差分の大きさ制限はありません。. CGImap では差分のサイズ制限は 50MB (非圧縮で)。
  • プレースホルダーID の前方宣言は禁じられており、API が拒絶します。

変更セットのまとめ

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

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

変更セットの議論

(new)

2014年11月に OpenStreetMap のウェブサイトに追加された機能です。(ブログ記事を見る)

コメント: POST /api/0.6/changeset/#id/comment

変更セットにコメントを行います。変更セットは閉じられている必要があります。


URL: https://api.openstreetmap.org/api/0.6/changeset/#id/comment ()
レスポンス: application/xml

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

パラメータ

text
コメントのテキストです。コンテンツタイプは "application/x-www-form-urlencoded" になります。

エラーコード

HTTP ステータスコード 400 (Bad Request)
テキストフィールドの値が存在していない時に返ります
HTTP ステータスコード 409 (Conflict)
変更セットが閉じられていない時に返ります

購読: POST /api/0.6/changeset/#id/subscribe

新しいコメントの通知を受け取るために変更セットの議論を購読します。


URL: https://api.openstreetmap.org/api/0.6/changeset/#id/subscribe ()
レスポンス: application/xml

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

エラーコード

HTTP ステータスコード 409 (Conflict)
ユーザがすでに変更セットを購読していた場合に返ります
if the changeset is still open

購読停止: POST /api/0.6/changeset/#id/unsubscribe

変更セットの議論の通知を止めるために購読停止します。

URL: https://api.openstreetmap.org/api/0.6/changeset/#id/unsubscribe ()
レスポンス: application/xml

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

エラーコード

HTTP ステータスコード 404 (Not Found)
ユーザが変更セットの購読を行っていなかった時に返ります
HTTP status code 409 (Conflict)
変更セットがまだ未処理の場合

要素

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>

XML のノードのIDはURLに含まれるIDと一致しなければなりません。バージョンはダウンロードした要素のバージョンと、変更セットは現在の認証済みユーザーが所有し開いている変更セットのIDと、それぞれ一致しなければなりません。必須のlat/lonタグ以外のタグは必要ではありませんが、付いていても構いません。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 status code 403 (Forbidden)
要素のバージョンがない場合 (改訂の影響)
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)
オブジェクト単位でバージョン番号を付与するのはオプションですが、その場合も先頭に小文字のブイの字 "v" を付けます。例: /api/0.6/nodes?nodes=421586779v1,421586779v2

エラーコード

HTTP ステータスコード 400 (Bad Request)
形式が正しくないリクエスト(パラメータが無いか、正しくない)
HTTP ステータスコード 404 (Not Found)
要素のいずれかが見つからない場合
HTTP ステータスコード 414 (Request-URI Too Large)
URIが長すぎた場合 (tested to be > 8213 characters in the URI, or > 725 elements for 10 digit IDs when not specifying versions)

要素に関するリレーション: 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)
要素が削除されている場合

Redaction: POST /api/0.6/[node|way|relation]/#id/#version/redact?redaction=#redaction_id

この API メソッドは本来は ODbL ライセンス変更用に開発され、新しい CT/licence を受け入れなかった利用者による投稿を非表示にしました。現在は DWG が使用し、データのプライバシーや著作権違反を含む旧版の要素を非表示にします。すべての API による要素のバージョン番号取得リクエストは、HTTP エラーコード 403 を返します。

注記

  • 仲裁役としてOSM アカウント限定で許可されます (DWG とサーバー管理者)
  • #redaction_id の掲載先は https://www.openstreetmap.org/redactions
  • さらに詳しい情報は the sourceを参照
  • これは非常に珍しいコールです

エラーコード

HTTP ステータスコード (Bad Request)
"Cannot redact current version of element, only historical versions may be redacted." 現行版の要素は編集は不可、古いもののみ編集の対象という意味です。

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


Response
  • This response is NOT wrapped in an Osm Xml parent element.
  • The file format is GPX Version 1.0 which is not the current version. Verify that your tools support it.
    <?xml version="1.0" encoding="UTF-8"?>
    <gpx version="1.0" creator="OpenStreetMap.org" xmlns="http://www.topografix.com/GPX/1/0">
    	<trk>
    		<name>20190626.gpx</name>
    		<desc>Footpaths near Blackweir Pond, Epping Forest</desc>
    		<url>https://api.openstreetmap.org/user/John%20Leeming/traces/3031013</url>
    		<trkseg>
    			<trkpt lat="51.6616100" lon="0.0534560">
    				<time>2019-06-26T14:27:58Z</time>
    			</trkpt>
    			...
    		</trkseg>
    		...
    	</trk>
    	...
    </gpx>
    

トレースのアップロード

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 認証が必要です。


Response:

A number representing the ID of the new gpx

Error codes

HTTP status code 400 (Bad Request)
When the description is empty

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

Use this to update a GPX file. Only usable by the owner account. Requires authentication.

The response body will be empty.

Delete: DELETE /api/0.6/gpx/#id

Use this to delete a GPX file. Only usable by the owner account. Requires authentication.

The response body will be empty.

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

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


Download Data: GET /api/0.6/gpx/#id/data

Use this to download the full GPX file. Available without authentication if the file is marked public. Otherwise only usable by the owner account and requires authentication.

The response will be the exact file that was uploaded.

List: GET /api/0.6/user/gpx_files

Use this to get a list of GPX traces owned by the authenticated user: Requires authentication.

Example "details" response:

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


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

ユーザの詳細

この API メソッドは2012年9月に追加されました。(コード)

GET /api/0.6/user/#id

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

 <osm version="0.6" generator="OpenStreetMap server">
   <user id="12023" display_name="jbpbis" account_created="2007-08-16T01:35:56Z">
     <description></description>
     <contributor-terms agreed="false"/>
     <img href="http://www.gravatar.com/avatar/c8c86cd15f60ecca66ce2b10cb6b9a00.jpg?s=256&d=http%3A%2F%2Fwww.openstreetmap.org%2Fassets%2Fusers%2Fimages%2Flarge-39c3a9dc4e778311af6b70ddcf447b58.png"/>
     <roles>
     </roles>
     <changesets count="1"/>
     <traces count="0"/>
     <blocks>
       <received count="0" active="0"/>
     </blocks>
   </user>
 </osm>

与えられた ID に該当するユーザが存在しなかった場合、空のファイルが返ります。


Details of multiple users

This API method was added in July 2018 (code).

You can get the details of a number of users via

GET /api/0.6/users?users=#id1,#id2,...,#idn

this returns for example

  <osm version="0.6" generator="OpenStreetMap server">
    <user id="12023" display_name="jbpbis" account_created="2007-08-16T01:35:56Z">
      <description></description>
      <contributor-terms agreed="false"/>
      <img href="http://www.gravatar.com/avatar/c8c86cd15f60ecca66ce2b10cb6b9a00.jpg?s=256&amp;d=http%3A%2F%2Fwww.openstreetmap.org%2Fassets%2Fusers%2Fimages%2Flarge-39c3a9dc4e778311af6b70ddcf447b58.png"/>
      <roles>
      </roles>
      <changesets count="1"/>
      <traces count="0"/>
      <blocks>
        <received count="0" active="0"/>
      </blocks>
    </user>
    <user id="210447" display_name="siebh" account_created="2009-12-20T10:11:42Z">
      <description></description>
      <contributor-terms agreed="true"/>
      <roles>
      </roles>
      <changesets count="267"/>
      <traces count="1"/>
      <blocks>
        <received count="0" active="0"/>
      </blocks>
  </user>
</osm>

or an empty file if no user found for given identifier.

ログインユーザの詳細

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">
  <contributor-terms agreed="true" pd="true"/>
  <img href="http://www.openstreetmap.org/attachments/users/images/000/000/1234/original/someLongURLOrOther.JPG"/>
  <roles></roles>
  <changesets count="4182"/>
  <traces count="513"/>
  <blocks>
      <received count="0" active="0"/>
  </blocks>
  <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>
  <messages>
    <received count="1" unread="0"/>
    <sent count="0"/>
  </messages>
</user>

</osm>

messages のセクションは2013年半ばから使用できるようになりました。受信済み、送信済み、未読の 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

これは地図メモ機能(ユーザが地理的に関連した“付せん”でテキストによる注記を加えられる機能)にアクセスを可能にします。 この機能は API v0.6 に元々付いていたわけではなく、後に追加されました(2013/04/23 のコミット 0c8ad2f86edefed72052b402742cadedb0d674d9 にて)。

境界ボックス内の地図メモデータの検索: GET /api/0.6/notes

指定した境界ボックス内にある既存の地図メモを返します。地図メモは、変更日時が新しい順に並べられ最新のものが最初に来ます。地図メモのリストはファイルの拡張子によって異なる形式(例:実行可能な JavaScript、XML、RSS、JSON、GPX)で返すことが出来ます。(訳註:実行可能な JavaScript と有りますが、.js にしてもエラーが出ます。callback パラメータを付けて JSONP 形式にしても出力は変わらないようでした)


URL: http://api.openstreetmap.org/api/0.6/notes?bbox=left,bottom,right,top (example)
レスポンス: application/xml


パラメータ 説明 使用可能な値 デフォルト値
bbox 地図メモを受け取るエリアを示す西南東北の経度緯度です 角度の浮動小数点数 デフォルト値は指定されていません。値の指定は必須です。
limit 最大何件の地図メモが返ってくるかを指定します 1 から 10000 が許可されます 100
closed ノード解決までの日数。その日以降は返さないという日付です。 0 なら未解決の地図メモだけが返ります。-1 ならすべての地図メモが返ります。 7

ファイルの拡張子を指定することで、結果を望む形式で返すことが出来ます。例えば、この例なら結果が JSON 形式で返ってきます。現在は、RSS、XML、JSON、GPX形式がサポートされています。

エラーコード

HTTP ステータスコード 400 (Bad Request)
何かしらの制限を超えた時に返します

メモの読取: GET /api/0.6/notes/#id

指定された ID の地図メモを返します。出力はファイルの拡張子によって数種類の形式(例:XML、RSS、JSON、GPX)に出来ます。


URL: http://api.openstreetmap.org/api/0.6/notes/#id ([1])
レスポンス: application/xml

エラーコード

HTTP ステータスコード 404 (Not Found)
指定された ID に地図メモが存在していない時に返ります

メモの作成: 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 地図メモに記入する任意のテキストのフィールドです デフォルト値は指定されていません。何かしらのテキストが必須です。

リクエストが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=ThisIsANoteComment (example)
レスポンス: application/xml

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


エラーコード

HTTP ステータスコード 400 (Bad Request)
text に何も存在しなかった時に返します
HTTP ステータスコード 404 (Not found)
if no note with that id is not available
HTTP ステータスコード 405 (Method Not Allowed)
POST でリクエストをしなかった時に返します
HTTP ステータスコード 409 (Conflict)
コメントした地図メモが解決している時に返します

メモの解決: 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 note with the given id could be found
HTTP ステータスコード 405 (Method Not Allowed)
POST でリクエストをしなかった時に返します
HTTP ステータスコード 409 (Conflict)
解決した地図メモを解決しようとした時に返します

メモの再開: 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 note with the given id could be found
HTTP ステータスコード 405 (Method Not Allowed)
POST でリクエストをしなかった時に返します
HTTP ステータスコード 409 (Conflict)
未解決の地図メモを再開しようとした時に返します
HTTP ステータスコード 410 (Gone)
削除された地図メモを再開しようとした時に返します

テキストとコメントからメモの検索: 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 検索クエリを指定します 文字列 デフォルト値は指定されていません。何かしらのクエリが必須です。
limit 最大何件の地図メモが返ってくるかを指定します 1 から 10000 が許可されます 100
closed Specifies the number of days a note needs to be closed to no longer be returned 0 なら未解決の地図メモだけが返ります。-1 ならすべての地図メモが返ります。 7

エラーコード

HTTP ステータスコード 400 (Bad Request)
何かしらの制限を超えた時に返します

RSS Feed: GET /api/0.6/notes/feed

Gets an RSS feed for notes within an area.

URL: https://api.openstreetmap.org/api/0.6/notes/feed?bbox=left,bottom,right,top

Return type: application/xml

APIを使うべきでない場合

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

より詳しく

脚注