JA:Overpass API

From OpenStreetMap Wiki
Jump to navigation Jump to search
Overpass API logo.svg
edit
Overpass API · 言語リファレンス · 言語ガイド · Technical terms · エリア · クエリーの例 · Sparse Editing · Permanent ID · よくある質問 · もっと (日本語) · Web site
Servers status · Versions · Development · Technical design · Installation · XAPI compatibility layer · Public transport sketch lines · アプリケーション · Source code and issues
Overpass turbo · Wizard · Overpass turbo shortcuts · MapCSS stylesheets · Export to GeoJSON · もっと (日本語) · Development · Source code and issues · Web site
Overpass Ultra · Overpass Ultra extensions · MapLibre stylesheets ·もっと (日本語) · Source code and issues · Web site
Overpass API logo.svg

概要

Overpass API(以前の別名:OSM Server Side Scripting、あるいは2011年以前はOSM3S)とは読み出し専用のAPIであり、OSM地図データの中から個別に選択された部分を取り出します。Webを介したデータベースとして動作します。利用者はAPIに対してクエリを送り、クエリに対応したデータ セットを受け取ります。

編集に最適化されている標準のAPIとは異なり、OverPass APIはデータ利用者向けに最適化されています。利用者は数個の要素を即座に得たり、最大約1千万個の要素を数分かかって得ることができ、例えば位置、オブジェクトのタイプ、タグの内容、近接度やその組合せによる検索条件によって選び出すことができます。様々なサービスのデータベースのバックエンドとして動いています。

詳細な概要は ユーザーズマニュアル(英語) を参照して下さい。

加えて、 Overpass QL ガイド/言語リファレンス もあります。インタラクティブなウェブベースのフロントエンドである overpass turbo を介してさまざまな機能に慣れることを強くお勧めします。レガシーアプリケーション向けには、XAPIからのスムーズな移行を可能にする互換レイヤーもあります。

パブリックな Overpass API のインスタンス

OSMの標準サービスを最小限でスケーラブルに保っておくため、Overpass APIはサードパーティのサービスとして動作します。パブリックに利用できるサービスとして以下のものがあります。


名称 データ範囲 Endpoint バージョン Attic data ハードウェア Munin 利用ポリシー
Main Overpass API instance Global https://lz4.overpass-api.de/api/interpreter Overpass API 0.7.56.2 b688b00f はい 4 physical cores, 64 GB RAM, SSD Link これらのサーバはいずれも、1日あたり約1,000,000リクエストの処理能力があります。1日あたり10,000クエリまたは5GBのデータ取得より少なければ、他のユーザーを邪魔しないと考えてよいでしょう。overpass-api.deのアドレスとhttps://overpass-api.de/api/interpreterのエンドポイントはz から lz4 までラウンドロビンでリダイレクトされて動作します。
Main Overpass API instance Global https://z.overpass-api.de/api/interpreter Overpass API 0.7.56.1002 b121d216 はい 4 physical cores, 64 GB RAM, SSD Link
French Overpass API instance Global http://overpass.openstreetmap.fr/api/interpreter 0.7.54.13 ff15392f いいえ 8 cores, 16 GB RAM, SSD [1] 任意の目的でAPIを利用可能です。1日・1プロジェクトあたりのクエリは1000を越えないこと(プロジェクトとは例えばスマホアプリでこのAPIを利用する時、ユーザが1万人いて1日に1回クエリを送ったらそれでおしまいということ)
Swiss Overpass API instance スイスのみ http://overpass.osm.ch/api/interpreter 0.7.55 579b1eec いいえ 12 cores, 64 GB RAM, hard disks ? User:Datendelphin に問い合わせて下さい
Kumi Systems Overpass Instance Global https://overpass.kumi.systems/api/interpreter 0.7.55.7 8b86ff77 多分, attic queries fail with runtime errors 4 servers with 20 cores, 256GB RAM, SSD each - 任意のプロジェクトで利用可能。制限なし。

質問/フィードバックなどは こちら

Taiwan Overpass API Global https://overpass.nchc.org.tw/api/interpreter 0.7.55.5 2ca3f387 はい ? ? 質問/フィードバックなどは OSM.tw あるいはNCHC FSL

Overpass API のエンドポイントは Open Historical Map でも利用しています。

Overpass APIへのクエリは、XMLかOverpass QL形式です。文法は下記参照。Overpass turboフロントエンドを使って、上記のOverpass APIインスタンスへのクエリを作成したり表示したりすることができます。

Overpass APIはパーマネント リンクも提供しています。

コミュニティ:質問サイト

もちろん最初に ユーザーズマニュアル(英語) を参照して下さい。

Overpass API と overpass turbo に関する質問を受け付けるコミュニティサイトがいくつかあります。

これらのサイトの質問と回答の内容は古くなっていることが多いので注意して下さい 掲載されている内容から現在までの間に、不足している機能が実装されたり、回避策が合理化されている可能性があります。 内容の妥当な有効期限は2年程度でしょう。

表の中でOSM HelpのみがOSMコミュニティの管理で、それ以外はサードパーティーのサイトです。

サイト 利用言語 質問でよく使用されるタグ
OSM Help 英語 overpass, overpass-turbo
GIS StackExchange 英語 overpass-api
Stack Overflow 英語 overpass-api
OSM US Slack, Channel #overpass 英語


開発者 / システム管理者

最新の安定リリースgitソースコード リポジトリ(最新バージョン)から、独自のインスタンスをインストールすることができます。ライセンスはAffero GPL v3です。

このプロジェクトは、Roland Olbricht (mail: roland.olbricht@gmx.de)がメンテナンスしています。ソースコードへのバグ レポートやプル リクエストなどの貢献も歓迎しています。

開発者向けのメーリングリストもあります。

制限

どのようなサービスにも制限は付き物です。Overpass APIもそうです。

  • 大きなデータのダウンロード:

Overpass APIクエリの結果のサイズは、ダウンロードが完了して初めて分かります。残り時間を推定することはできません。 同じ領域からの場合でも、すでに静的に用意されたものに比べ、Overpass APIから動的に生成されるファイルをダウンロードするためには、たいていはより長い時間がかかります。したがって、国レベルのサイズの領域から(ほぼ)すべてのデータを抽出しようとする場合には、Planet.osmミラーを使う方が良いでしょう。領域の中で利用可能なデータのうちの一部分の選択だけを必要とする場合に、Overpass APIは便利なのです。

  • OSMデータの履歴のクエリ:

Overpass APIは 変更セットベースの抽出条件は提供しません。時刻ベースの差分を使うワークアラウンドも可能ですが、ややこしいでしょう。オブジェクトの全履歴も得ることもできませんが、時刻ベースの選択基準を使えばオブジェクトのある時点での状態を得ることはできます。 (この機能はver.0.7.55から retrotimeline のコマンドでサポートされました。https://dev.overpass-api.de/blog/sliced_time_and_space.html を参照)

マップ クエリ

クエリの詳細な文法を説明する前に、おそらく最も一般的な使い方であるマップ クエリを示します。このクエリは特定の矩形領域内の全データ(メタデータを含む)を収集します。(これらのリクエストは最小限に省略しています。これらのリクエストを実行するアイコンリンクには、指定された座標とズームレベルでレンダリングされたマップの中心を設定し、ロード時にリクエストをすぐに実行するパラメーターも含まれていることに注意してください)

Overpass QL Overpass XML
try it yourself in overpass-turbo
(
   node(51.249,7.148,51.251,7.152);
   <;
);
out meta;
try it yourself in overpass-turbo
<union>
  <bbox-query s="51.249" w="7.148" n="51.251" e="7.152"/>
  <recurse type="up"/>
</union>
<print mode="meta"/>

クエリを実行するには、ここのクエリフォームに入力しても良いし、Overpass turboを使って結果を地図上で確認することもできます。

矩形領域(51.249,7.148,51.251,7.152)の中の値は、最小緯度、最小経度、最大緯度、最大経度(つまり、南-西-北-東)の順序です。矩形領域の詳細は後で説明します。

シンプルな使用例

Overpass APIクエリ言語についての詳細は、Overpass API言語ガイド、またはOverpass APIクエリ言語の解説を参照してください。


リソース管理オプション (osm-script)

osm-script は、XML構文を使用する時に明示的に使用しない場合は、自動的に追加されます。明示的に指定する理由は、オプションのXML属性を設定してリソース管理オプションを微調整するためです (QL構文を使用している場合は、クエリの開始時に空の文で同等の括弧付きオプションを指定することもできます)。


Overpass XML Overpass QL
Overpass turboで実際に試す
<osm-script timeout="900" element-limit="1073741824">
  <bbox-query s="51.15" w="7.0" n="51.35" e="7.3"/>
  <print/>
</osm-script>
Overpass turboで実際に試す
[timeout:900][maxsize:1073741824];
node(51.15,7.0,51.35,7.3);
out;

このクエリは、タイムアウトを3分から15分に延長しています(900秒と記述)。 さらに、メモリ使用量のソフトクォータは1 GiB(1,073,741,824バイト)に設定されます。

警告:この例を実行すると、100 MiBを超えるデータが取得されます(最初の例のようにすべての詳細を示すために再帰処理しない場合でも、タグ付きのノードのフラットリストのみが取得されます)。 Overpass は、マップ上のデータをレンダリングするためにブラウザで直接実行した場合に警告を表示しますが、読み込みを続けるとブラウザのタブがクラッシュする可能性があります。このような大きなリクエストの結果は、他のツールで処理するためにダウンロードする必要があります。

これらのリソース制限を任意の高い値に設定することはできません。各Overpass APIインスタンスは、(サーバーの能力または現在のサーバーの負荷に応じて、)しきい値を超えてそれらを拡張することを拒否するか、クエリがエラーメッセージ(およびOK以外のHTTP サーバーエラーステータス)で失敗したりします。

高度な使用例

以下の使用例では、まだ説明していないコマンド、recursearoundを紹介します。これらのコマンドは、他のコマンドと組み合わせないと意味がありません。

繰り返しますが、以下の例はすべてhttp://www.overpass-api.de/query_form.htmlへコピーして試してみることができます。

注意: クエリが完了するまでには数分かかるでしょう。もしタイムアウトになる場合は、タイムアウト時間を延長することができます。

recurse

recurseは、リレーションの所属関係へのクエリを行います。ウェイに参照されている全ノード、リレーションのメンバーである全ノードと全ウェイの取得ができます。また逆方向に、ノード、ウェイ、リレーションに対して、その要素がメンバーになっているウェイやリレーションを取得できます。要素のタイプを選ぶには、typeを使います。

例: refキーの値がE61であるリレーションのノードをすべて取得します。現実にはE61路線のバス停をすべて取得します。

Template:Overpass turboで実際に試す

refキーの値がE61であるリレーションのウェイをすべて取得します。現実にはE61路線の運行ルートです。

Template:Overpass turboで実際に試す

上記のウェイのノードをすべて取得します。バス停は含まれませんが、これは意図通りです。後述のunionの例を参照してください。

Template:Overpass turboで実際に試す

Lichtscheidという名前を持つノードをメンバーとして持つすべてのリレーションを取得します。これらは、その場所に停車するバス路線です。

<query type="node">
  <has-kv k="name" v="Lichtscheid"/>
</query>
<recurse type="node-relation"/>

<print/>

指定した矩形領域に含まれるノードをメンバーとして持つすべてのウェイを取得します。

<bbox-query s="51.249" n="51.251" w="7.149" e="7.151"/>
<recurse type="node-way"/>

<print/>

リレーションのメンバーであるリレーションを取得することもできます。

<query type="relation">
  <has-kv k="name" v="VRR Buslinien"/>
</query>
<recurse type="relation-relation"/>

<print/>

逆方向もできます。

<query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-backwards"/>

<print/>

around

一つまたは複数のノードの近くにあるノードすべてを、aroundで取得できます。 例えば、Bristolと呼ばれるノードから10メートル以内にあるノードをすべて取得します。

Overpass turboで実際に試す
<query type="node">
  <has-kv k="name" v="Bristol"/>
</query>
<around radius="10"/>
<print/>

クエリを連鎖させれば、第1の基準に一致するノードの近くに位置して第2の基準を満足するようなノードだけを取得することができます。ここでは、"Bristol"という名前のパブから100メートル以内のバス停をすべて探してみましょう。

Overpass turboで実際に試す
<query type="node">
  <has-kv k="amenity" v="pub"/>
  <has-kv k="name" v="Bristol"/>
</query>
<query type="node">
  <around radius="100"/>
  <has-kv k="highway" v="bus_stop"/>
</query>
<print/>


基本要素

まだ説明していない補助的なステートメンがあります。特に、unionitem、変数メカニズム、foreachです。

しつこいですが、以下の例はすべてhttp://www.overpass-api.de/query_form.htmlへコピーして試してみることができます。

union

unionによって、いくつかのクエリの結果をまとめることができます。例えば名前がLichtscheidまたはMüngstener Straßeであるノードをすべて取得できます。

<union>
  <query type="node">
    <has-kv k="name" v="Lichtscheid"/>
  </query>
  <query type="node">
    <has-kv k="name" v="Müngstener Straße"/>
  </query>
</union>
<print/>

別の例として、あるリレーションと、そのメンバーすべてと、メンバーであるウェイに含まれるノードとを取得します。

<union>
  <query type="relation">
    <has-kv k="ref" v="CE 61"/>
  </query>
  <recurse type="relation-node" into="nodes"/>
  <recurse type="relation-way"/>
  <recurse type="way-node"/>
</union>
<print/>

ここは少し説明が必要でしょう:

  • queryは、refがCE 61のリレーションを収集します。その結果をデフォルト変数 _ に書き込みます。そして外側のunionがデータを収集します。
  • recurse relation-nodeは、上記で見つかったリレーションのメンバーであるようなノードを収集します。結果は変数nodesに置かれます(この変数は以降では使われず、ただ単にデフォルト変数の中のリレーションを残すためのものです)。そして外側のunionにより収集されます。
  • recurse relation-wayは、再びデフォルト変数を参照し、デフォルト変数内のリレーションのメンバーであるウェイを返します。同様に、外側のunionが結果を収集します。
  • 最後にrecurse way-nodeは、たった今収集されたウェイのメンバーであるノードを返します。これがunionの結果に入るデータの最後の一群です。

複雑に感じるでしょうか、それは正しいです。どのようにステートメントの文法を改善できるか、提案を歓迎しています。私自身はシステマティックな改善方法をまだ見つけられていません。

ここまでで、bbox-queryといくつかのrecurseステートを組合せ、unionで全部を囲むことによって、地図の取り出しを組み立てることができるようになりました。

item

itemや変数の背景にある考え方は一部、これまでの例で見てきたものです。 すべてのステートメントは入力をある変数から取り出し、出力をある変数へ置きます。変数名が省略された場合、デフォルトは _ になります。これにより、ほとんどの場合は明示的に変数を定義する必要が無くなります。from属性で名前を指定された変数から入力が取り出され、intoで指定された変数へ出力が置かれます。

<query type="way" into="foo">
  <has-kv k="name" v="Am Hofe"/>
</query>
<print from="foo"/>

例えば、これはprintの例で示されたものと同じことをしますが、明示的に記述された変数fooを使用します。

このコンセプトを汎用的にするために、unionqueryへの入力を、itemによって指定できます。

<query type="relation">
  <has-kv k="network" v="VRR"/>
  <has-kv k="ref" v="645"/>
</query>
<recurse type="relation-node" into="stops"/>
<query type="node">
  <around from="stops" radius="100"/>
  <has-kv k="highway" v="bus_stop"/>
</query>
<union>
  <item/>
  <recurse type="node-relation"/>
  <query type="node">
    <around from="stops" radius="100"/>
    <has-kv k="park_ride"/>
  </query>
</union>
<print/>

この例の中ほどのitemは、それまでに収集されたbus_stopのデータがunionの結果に含まれることを保証します。 クエリを可能にするためにstops変数がどのように必要となるかも、この例で分かります。

<bbox-query s="51.15" n="51.35" w="7.0" e="7.3"/>
<recurse type="node-way"/>
<query type="way">
  <item/>
  <has-kv k="highway" v="motorway"/>
</query>
<print/>

クエリ中のitemは、見つけられる項目を、その前のステップ、recurseですでに見つかっている項目の中だけに限定します。このようにして、ある矩形領域の中で任意のタグをもつウェイを見つけることができる、完全なクエリが可能になります。

foreach

<query type="relation">
  <has-kv k="type" v="multipolygon"/>
  <has-kv k="name"/>
</query>
<foreach into="pivot">
  <union>
    <recurse type="relation-way" from="pivot"/>
    <recurse type="way-node"/>
  </union>
  <make-area pivot="pivot"/>
</foreach>

これは領域を作るためのルールの核心部分です。ここではmake-areaの説明はしません。最初のquery部分は、特定の性質を持つリレーションを集めます。2番目の部分では、queryの結果に含まれる各要素に何かをしようとします。foreachがこれを行います。ループの中身は入力となる集合の要素すべてに対して一回ずつ実行されます。この例ではpivotという名前の出力集合へ、そのそれぞれの要素も含められます。

メタ データ

printの特別なモードとは別に、特定のメタ データのための専用のクエリが2つあります。usernewerです。

user

ある特定のユーザーによって最後に変更されているデータすべてを選択できます。 ユーザー名を選びましょう(例として、私のです)。

<user name="Roland Olbricht"/>
<print mode="meta"/>

または、ユーザーIDを選びましょう。

<user uid="65282"/>
<print mode="meta"/>

このステートメントは、クエリ ステートメントの中でも使えます。その場合、指定されたユーザーによって最後に変更されたデータに、クエリ結果が限定されます。

<query type="node">
  <user name="Roland Olbricht"/>
  <has-kv k="highway" v="bus_stop"/>
  <bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/>
</query>
<print mode="meta"/>

newer

newerはクエリ ステートメントの中で使えます(単独のステートメントとしては使えません)。 与えられた日時より新しい要素に、出力を限定します。 日時は、YYYY-MM-DDTHH:MM:SSZ の形式である必要があります。必然的に、常にUTCタイム ゾーンとして扱われます。

<query type="node">
  <newer than="2011-08-01T00:00:00Z"/>
  <has-kv k="highway" v="bus_stop"/>
  <bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/>
</query>
<print mode="meta"/>

矩形領域内で特定の日時より新しいノードをすべて取りたい場合は、queryitemサブ ステートメントを付けます。

<bbox-query s="51.2" n="51.35" w="7.05" e="7.3"/>
<query type="node">
  <item/>
  <newer than="2011-08-01T00:00:00Z"/>
</query>
<print mode="meta"/>

公共交通の例

Example preview of line 6 (APS Mobilità).

Overpass APIがアプリケーション内でどのように使えるか、の例として興味深いのは、公共交通の線ダイアグラムを生成するサービスです。

右にあるレンダリング済みビューの例をご覧ください。 こちらに他の例があります。

このWikiでは、文書化された {{Sketch Line}} のテンプレートを使用してこのツールへのリンクを作成できます。

(サーバーの負荷によって、リクエストしてから生成されるまでに10秒ほどかかるときもあります。辛抱してください。)

注:Overpass API v0.7.52以降、PTv2サポートにはいくつかの既知の問題があり、その結果、ストップ名が重複したり、ギャップが生じたりします。Githubの問題#190を参照してください。 新しいPTvXバージョンまたはそのバリエーションでもレンダリングの問題が発生する可能性があります。

XAPI互換レイヤー

詳細や使用例は

を参照してください。

Overpass関連のプログラム、スクリプト

Python API

Node.js API

  • query-overpassは、シンプルなAPIラッパーで、OverpassへのCLI

Converters

議論、プレゼン、ワークショップ

このセクションでは、Overpass APIやそれに関連するこれまでのプレゼン、議論、ワークショップを一覧します。プレゼンの多くはサンプルが豊富で、初心者の出発点としても適しています。

日付 イベント 場所 タイトル タイプ 発表者 言語 リンク
2020年2月 OSMit 2020 トリノ (イタリア) Overpass Turbo: oltre il wizard プレゼン Andrea Albani イタリア語 スライド
2019年9月 SotMUS 2019 ミネアポリス (アメリカ) A turbo introduction to Overpass プレゼン Minh Nguyễn 英語 ビデオ, スライド, スライド+ノート
2017年 秋 Université Rennes (フランス) Introduction aux données OpenStreetMap et à l'API Overpass Turbo プレゼン Boris Mericskay フランス語 スライド
2016年9月 SotM 2016 ブリュッセル (ベルギー) Gardening OSM data with Overpass API プレゼン Roland Olbricht 英語 ビデオ
2016年7月 FOSSGIS 2016 - OSM-Sonntag ザルツブルグ (オーストリア) Overpass-Abfragen jenseits key=value selber schreiben ワークショップ Nakaner ドイツ語 スライド
2016年5月 SOTM FR 2016 Clermont-Ferrand (フランス) Démystifier l'API Overpass / Demystify the Overpass API ワークショップ Antoine Riche フランス語 ビデオ
2015年10月 FOSS@HFT Stuttgart シュツットガルト (ドイツ) Parametrisierter Download aus einer weltweiten Geodatenbank (OpenStreetmap) sowie daran anschliessend mit dem Workshop Algorithmik und Technik, Hypothesenprüfung プレゼン/ワークショップ Roland Olbricht ドイツ語 ビデオ
2015年7月 AGIT 2015 ザルツブルグ (オーストリア) Overpass API: OpenStreetMap-Daten vorgefiltert beziehen プレゼン Roland Olbricht ドイツ語 ?
2015年6月 SotM US 2015 ニューヨーク (アメリカ) Working with OSM diffs / The Overpass API ワークショップ Roland Olbricht 英語 ?, 概要
2015年4月 geo-spatial.org Cluj (ルーマニア) Overpass API: utilizarea datelor OpenStreetMap pentru a realiza hărți tematice ワークショップ Alex Morega ルーマニア語 ワークショップ素材
2015年3月 FOSSGIS 2015 ミュンスター (ドイツ) OpenStreetMapで宝探し プレゼン Roland Olbricht ドイツ語 概要, ビデオ
2015年3月 FOSSGIS 2015 ミュンスター (ドイツ) Overpass APIによるOpenStreetMapデータの維持と探索 ワークショップ (有料) Roland Olbricht ドイツ語 素材の参照不可
2015年2月 FOSDEM 2015 ブリュッセル (ベルギー) Overpass-API - OpenStreetMapデータを検索するサービス プレゼン Roland Olbricht 英語 スライド, ビデオ
2014年9月 ボン (ドイツ) ZERAでのOverpass-APIセミナー ワークショップ Roland Olbricht ドイツ語 Manuscript, スライド
2014年6月 SotM-EU 2014 カールスルーエ (ドイツ) Overpass API v0.7.50 - 時間次元 プレゼン Roland Olbricht 英語 スライド/ビデオ
2014年6月 SotM-EU 2014 カールスルーエ (ドイツ) 疎な編集 - 大スケールのオブジェクトを編集する プレゼン Roland Olbricht 英語 スライド/ビデオ
2014年3月 FOSSGIS 2014 ベルリン (ドイツ) Overpass APIによるOpenStreetMapデータの抽出、分析、フィルター ワークショップ (有料) Roland Olbricht ドイツ語 素材の参照不可
2013年10月 Intergeo 2013 エッセン (ドイツ) Overpass APIによるOSMデータの直接利用 プレゼン Roland Olbricht ドイツ語 スライド
2013年10月 OSMit 2013 ロヴェレート (イタリア) Overpass Turbo プレゼン Martin Raifer イタリア語 スライド
2013年3月 FOSSGIS 2013 ラッパーズヴィール (スイス) Overpass APIによるOpenStreetMapデータの抽出、分析、フィルター ワークショップ Roland Olbricht ドイツ語 スライド
2013年3月 FOSSGIS 2013 ラッパーズヴィール (スイス) overpass turbo - OpenStreetMapデータの簡単な解析 プレゼン Martin Raifer ドイツ語 スライド, ビデオ, FOSSGIS 2013会議資料
2013年3月 FOSSGIS 2013 ラッパーズヴィール (スイス) OSM、OpenLayers、Overpass APIによるモバイル カードの生成 プレゼン Roland Olbricht ドイツ語 スライド, ビデオ
2012年12月 OSMDE009 OSMトーク: Overpass API ポッドキャスト Roland Olbricht, Stephan/RadioOSM ドイツ語 リンク
2012年3月 FOSSGIS 2012 ベルリン (ドイツ) Overpass API プレゼン Roland Olbricht ドイツ語 スライド, FOSSGIS 2012会議資料
2011年6月 SotM-EU 2011 ウィーン (オーストリア) Overpass API - オープンでスリムなXAPIの代用 プレゼン Roland Olbricht 英語 スライド, ビデオ