JA:Overpass API/Overpass QL
Servers status · Versions · Development · Technical design · Installation · XAPI compatibility layer · Public transport sketch lines · アプリケーション · Source code and issuesOverpass turbo · Wizard · Overpass turbo shortcuts · MapCSS stylesheets · Export to GeoJSON · もっと (日本語) · Development · Source code and issues · Web siteOverpass Ultra · Examples · Overpass Ultra extensions · MapLibre stylesheets · URL Params · もっと (日本語) · Source code and issues · Web site
Overpass QL（"Overpass Query Language"の短縮形) は、Overpass API における二番目の問い合わせ言語で、Overpass XML の代替として設計されたものです。
Overpass QLは、
C言語風の文法を用いた命令型プログラミング言語です。
概要
ステートメント（文）
Overpass QL のコードはステートメント からなっており、それぞれのステートメントはセミコロン ; で終わります。ステートメントは逐次処理され、実行状態がそれに応じて変化していきます。
実行状態
Overpass QL の実行状態には下記のものがあります。
- デフォルトの集合（set）
_（単一の下線） - 名前つき集合（ユーザーが作成する場合）
- スタック：ブロックステートメントの実行中
集合（set）
Overpass QLは集合を操作します。 ステートメントは結果を集合に書き込み、集合は後続のステートメントによって入力として読み取られます。 集合は、OSMのノード、ウェイ、リレーション、エリアの任意の組み合わせとすることができ、要素の数も任意です。
入力や結果として名前つき集合を指定しない場合は、暗黙のうちに、_ (単一の下線) という名前のデフォルトの集合が、入力元や結果の書き込み先になります。
（暗黙あるいは明示的に）新たな結果の書き込み先として既存の集合が割り当てられた場合、その集合の元からあった内容は上書きされてしまい、使えなくなります。集合はつねに大域的に有効です。
例えば、下記の文は タグ のクエリ name="Foo" の結果を暗黙的にデフォルトの集合 _ に書き込み、以前の内容をこの結果で上書きします。
node[name="Foo"];
結果を名前つき集合に書き込む場合は -> の書式を使い、集合の名称の前に . をつけます。上の文は次の文と等価になります。
node[name="Foo"]->._;
同様に、次の文は2つのタグのクエリの結果を和集合として、デフォルトの集合 _ に書き込みます。
(
node[name="Foo"];
node[name="Bar"];
);
従って、次の文と等価となります。
(
node[name="Foo"];
node[name="Bar"];
)->._;
名前つき集合に要素を書き込む場合は、 -> の書式を使い、集合の名前を指定します。
例えば次の文は name=Foo というタグを持つ全てのノードを a という名前の集合に書き込みます。
(node[name="Foo"];)->.a;
集合の名前には、アルファベット、数字、下線を使うことができますが、最初の文字を数字にすることはできません。
集合から要素を読み出す場合は、コマンドに . と集合名をつけます。
次の文は a という名前の集合から amenity=foo タグを持つ全てのノードを返します。
node.a[amenity=foo];
言語構造
Overpass QL のステートメントにはいくつかの種類があり、下記のように分類されます。
- 設定：オプションのグローバル変数で、クエリの最初の文で設定します。設定の例としてはOverpass APIサーバーのタイムアウト、Overpass QL クエリの出力形式があります。
- 単独クエリ：これ自体で完結するステートメントです。Overpass API サーバーにクエリを実行して集合を作成したり、既存の集合の内容を操作したり、クエリのの最終結果を出力先に送信したりといった機能を実行することができます。
- ブロックステートメント：Overpass QLのステートメントをグループ化して、論理和とループに使うことができます。
設定
Overpass QL の「設定」は、最初のコメント化されていない文で宣言する必要があります。また複数の文で宣言することはできません。
設定の宣言はブラケット [] で囲みます。コロン : は設定名と値、またはセットする値の間に置きます。設定文の最後はセミコロン ; で終わります。
// This is a typical settings declaration line
// on an Overpass Turbo server
[out:json][timeout:25];
タイムアウト（timeout:）
timeout:の設定は1個の非負整数のパラメーターを持ちます。デフォルト値は180です。 このパラメーターは、利用者が考える、クエリの実行時間の最大許容値を秒単位で表します。 クエリの実行時間がこの時間を超えた場合、サーバーはタイムアウトでクエリを中断します。二つ目の効果として、大きな値を指定した場合、サーバーがクエリの実行前に拒否する可能性が高くなります。
このため、本当に複雑で大きなクエリを送る場合は、大きな値、たとえば1時間を表す "3600" を指定してください。この場合、お使いのクライアントが、指定した時間内にクライアント側からタイムアウトしないようにしてください。
例:
[timeout:180]
要素の上限 (maxsize:)
maxsize: の設定は1個の非負整数のパラメーターを持ちます。デフォルト値は 536870912 (512 MB)です。 このパラメータは、利用者が考える、クエリの実行によるサーバー上のRAMの最大許容値をバイト単位で表します。クエリがこの値を超える RAM を要した場合、サーバーはメモリー枯渇としてクエリを中断します。二つ目の効果として、大きな値を指定した場合、サーバーがクエリの実行前に拒否する可能性が高くなります。 このため、本当に複雑で大きなクエリを送る場合は、大きな値、たとえば 1 GB を表す "1073741824" を指定してください。 最大値は現在のサーバーの負荷に大きく依存します。 例えば2GBのリクエストは、全体的なリソース管理に合わないため、ピーク時に拒否される可能性があります。 技術的には、maxsizeは64ビットの符号付き数値として扱われます。
Example:
[maxsize:1073741824]
注: 最近、2 GBのメモリを超えるクエリを中止するための新しいメカニズムが導入されました。 この制限の正確なサイズはまだ議論中であり、今後変更される可能性があります。 「ランタイムエラー：クエリは約2048 MBのRAMを使用してメモリが不足しています。」などのエラーメッセージが表示された場合は、このスレッドも必ずお読みください。
http://permalink.gmane.org/gmane.comp.gis.openstreetmap.overpass/237
出力形式 (out:)
out:設定はoutステートメントとは関係ないので注意してください。両者の記法を混同しないように
out 設定は、OSM データを返す際の出力形式を定義します。5 個の値のいずれかを指定することができます。デフォルト値は xml です。
- xml
- json (geoJSONとは別物)
- csv
- custom
- popup
例:
[out:json]
CSV 出力モード
CSV 出力形式は、OSM データを csv ドキュメントとして返します。これは LibreOffice などのツールで直接開くことができます。フィールドの並びを定義するための構成パラメーターが必要となります。また、オプションで、csv ヘッダー行や、区切り文字のためのパラメーターを指定することができます。
書式:
[out:csv( フィールド名_1 [,フィールド名_n ...] [; csv-ヘッダー行 [; csv-区切り文字 ] ] )]
注:
- 数値（座標、id）は千単位の区切り文字を使わず、小数点の区切り文字には英語のドット(.)を使います（幾何学的な座標の場合）。
- 文字列の特定の文字については、エスケープは行われません。これはリリース 0.7.55 で変更されます。
- デフォルトの区切り文字（タブ）を使用しても、ほとんどの場合、列の欠落/破損/ずれがなく表形式データを解析できます。
- ヨーロッパの言語設定などでは、小数点記号がドット(.)でない場合があり、アプリケーションで直接CSVファイルを開くと、データが破損しているように見える可能性があります。必要により、読み込み時に変換などしてください。
フィールド名のリスト
通常の OSM のフィールド名（タグ）のほか、以下の特別なフィールドを出力の要素として使うことができます。
これらの特別なフィールドはいずれも、2個のコロン :: を前に置く必要があります。
| 特別なフィールド名 | 説明 |
|---|---|
::id
|
OSM オブジェクトの ID |
::type
|
OSM オブジェクトの種類: node, way, relation |
::otype
|
OSM オブジェクトの種類を数値で |
::lat
|
緯度 (ノードに対して、または out center モードの場合に利用可能) |
::lon
|
経度 (ノードに対して、または out center モードの場合に利用可能) |
以下のメタ情報フィールドは、OSM 要素の出力に out meta; が使われている場合のみ使用可能です。
| |
::version
|
OSM オブジェクトのバージョン番号 |
::timestamp
|
OSM オブジェクトの最終変更のタイムスタンプ |
::changeset
|
オブジェクトが変更された変更セット |
::uid
|
OSM のユーザー id |
::user
|
OSM のユーザー名 |
以下のメタ情報フィールドは、OSM 要素の出力に out count; が使われている場合のみ使用可能です。
| |
::count
|
入力集合のオブジェクト（ノード、ウェイ、リレーション、エリア）のトータルの数 |
::count:nodes
|
入力集合のノードの数 |
::count:ways
|
入力集合のウェイの数 |
::count:relations
|
入力集合のリレーションの数 |
::count:areas
|
入力集合のエリアの数 |
例:
[out:csv(
::"id", amenity, name, operator, opening_hours, "contact:website", "contact:phone", brand, dispensing, lastcheck
)];
ボンにある鉄道の駅:
[out:csv(::id,::type,"name")];
area[name="Bonn"];
nwr(area)[railway=station];
out;
CSV ヘッダー行
ヘッダー行の有無は、最初のオプションパラメータで制御できます。これは、フィールドリストの直後にセミコロンで区切って追加することができます。指定可能な値には、 true と false があります。このパラメーターを指定しなかった場合は、ヘッダー行が出力されます。
[out:csv(
::"id", amenity, name, operator, opening_hours, "contact:website", "contact:phone", brand, dispensing, lastcheck;
false
)];
CSV 区切り文字
デフォルトでは、各フィールドはタブ文字 ("\t") で区切られます。しかし、この区切り文字の設定は、二つ目のオプションのパラメーターを使って変えることができます。以下の例では、すべての出力フィールドが、タブ文字の代わりにパイプ文字 ("|") で区切られます。
[out:csv(
::"id", amenity, name, operator, opening_hours, "contact:website", "contact:phone", brand, dispensing, lastcheck;
true; "|"
)];
- データのCSV出力のチェック
XMLやJSONのような他の出力モードとは異なり、現在のところエラーメッセージ一切表示されません。 空の結果（またはヘッダー行のみの結果）は、何も見つからなかったか、タイムアウトまたはその他のより深刻なエラーのためにクエリが中止されたことを示している可能性があります。 これを回避する一つの方法は、追加のカウンタを導入することです。 これは、前のクエリの結果を要約し、常にクエリの最後の出力文として置かれます。
以下の例では、前のボンの全鉄道駅のリストを拡張し、追加の出力文でCSVの集計行を返します。最後の ::count のパラメーターが "count" タイプの疑似要素を記述しています。（この値は通常のデータ行では空のままです）
[out:csv(::type,::id,"name",::count)];
area[name="Bonn"]->.a;
( node(area.a)[railway=station];
way(area.a)[railway=station];
rel(area.a)[railway=station];
);
out;
out count;
出力には ::count タイプの追加列と結果の集合の要素の数である 5 が追加されます。もし最後のcountの行がなかったり合計数が異なる場合は、エラーが発生しているかクエリの結果が完全ではないか矛盾しているということがわかります。
@type @id name @count node 26945519 Bonn-Oberkassel node 1271017705 Bonn-Beuel node 2428355974 Bonn-Bad Godesberg node 2713060210 Bonn Hauptbahnhof node 3400717493 Bonn-Mehlem count 0 5
custom と popup の値も、追加の構成が必要です。 詳細については、出力形式のドキュメント(英語)を参照してください。
大域的な境界ボックス (bbox)
bbox 設定を使うと、すべてのクエリ（明示的に別の境界ボックスが定義されているものを除く）に対する暗黙的な境界ボックスを定義することができます。
bbox が設定されていない場合のデフォルトは「世界全体」となります。
標準のOverpass QLプログラムでは、境界ボックスはISO 6709形式の2つの座標のペアで構成され、各値はコンマで区切られます。
境界ボックスは、南側の緯度、西側の経度、北側の緯度、東側の経度 の順で記述します。
[bbox:南,西,北,東]
// ドイツの都市ボン周辺の境界ボックス
[bbox:50.6,7.0,50.8,7.3]
// ブラジルのリオデジャネイロ付近の境界ボックス
[bbox:-23,-43.3,-22.8,-43.1]
注:クエリを data= のパラメータの値としてURLエンコードしている場合、境界ボックスを別の bbox 変数として追加することができます。この場合は、経度-緯度 の順で指定します。（これは OpenLayers や他のフレームワークでは一般的な順序です。）
ボンの例の場合、URLエンコードでは下記のようになります。
/api/interpreter?data=[bbox];node[amenity=post_box];out;&bbox=7.0,50.6,7.3,50.8
これは、おおむねドイツ・ボンにある郵便ポストすべてを検索します。
過去のデータ（date）
date 設定はグローバル設定で、過去のある時点でのデータベースの状態にもとづく結果を返します。この設定は、破壊されたデータを再構築するような場合や、過去のある時点でデータベースに存在していたオブジェクトを表示する場合などに有用です。
識別子 date とそれに続くコロン : およびOSMで標準のISO 8601形式のフォーマット YYYY-MM-DDThh:mm:ssZ で日付を記述します。
この例のクエリでは、2015 年 10 月 28 日 19:20 UTC 時点であるかのように処理します。
[date:"2015-10-28T19:20:00Z"]
OSMのデータベースには 2012-09-12T06:55:00Z (1347432900 エポック秒)
以前のデータはありません。この日付は、ODbL準拠のplanetファイルに含まれる最初の変更に対応しています。 これより前の日付設定を使用することは技術的に可能ですが、それを使用すると常に、 2012-09-12T06:55:00Zの時点のデータベースの状態が返されます。
2個の日時の間の差分（diff）
diff 設定は、データベースが、過去の二つの異なる時点におけるクエリの差分をとるようにします。たとえば、データベース抽出用のデルタ生成に有用です。
識別子 diff とそれに続くコロン : および日付指定、さらに、オプションでカンマと二つ目の日付指定からなります。日付指定が一つだけの場合は、二つ目の日付は現時点とみなします。日付のフォーマットはOSM標準のISO 8601形式のフォーマット YYYY-MM-DDThh:mm:ssZ です。
例:
[diff:"2012-09-14T15:00:00Z"]
この後のクエリを、2012 年 9 月 14 日 15:00 時点であるかのように処理します。次に、同じクエリを現時点のデータに対して処理します。最後に、この二つの結果の差分を出力します。
[diff:"2012-09-14T15:00:00Z","2012-09-21T15:00:00Z"]
これも、基本的に同じですが、9 月 14 日の状態と 9 月 21 日の状態とを比較するところが違います。
出力には、最初と最後のタイムスタンプの間に存在する可能性のある中間バージョンは含まれないことに注意してください。つまり、オブジェクトにいくつかの変更がある場合、指定されたタイムフレームの最後のバージョンのみが返されます。
2個の日時の間の拡張形式の差分（adiff）
adiff は基本的には "diff" と同じですが、新しい方の結果に含まない要素すべてについて、何が起きたかを表すところが違います。
要素が削除されている場合、最終削除日が出力され、"visible=false" と示されます。要素が変更されてクエリにマッチしなくなっている場合、最終変更日が出力され、"visible=true" と示されます。
詳しい情報は、Augmented Diffs を参照してください。
ブロックステートメント
和集合 (union)
union ブロックステートメントは、1 組の丸括弧の対で記述します。union ブロック内には、任意のステートメントの並びを置くことができ、入れ子になった union や foreach を置くこともできます。下記の例の角括弧 [ ... ] は構文のオプション部分を示しており、文字どおりに入力する必要はありません。
(ステートメント1; ステートメント2; …)[->.出力集合];
和集合には入力集合はありません。和集合は結果集合を生成します。和集合の結果集合は、送り先の有無にかかわらず、すべてのサブステートメントの結果集合の和集合になります。
例:
(node[name="Foo"]; way[name="Foo"];);
一つ目のステートメントでは "Foo" という値の name タグを持つ全ノードを、二つ目のステートメントでは "Foo" という値の name タグを持つ全ウェイを収集します。union ステートメントにより、全体の結果集合は、二つのステートメントの結果集合の和集合になります。
union ステートメントの結果集合は、通常の接尾辞の記法を使って送り先を指定することができます。
例:
(node[name="Foo"]; way[name="Foo"];)->.a;
先の例と同様ですが、結果は集合 "a" に書き込まれます。
制限事項: foreach および print ステートメントを union 内部に書くことはできません。
差集合 (difference)
difference ブロックステートメントは、1 組の丸括弧の対で記述します。difference ステートメントのなかには、ちょうど二つのステートメントを置き、その間にマイナス記号を置く必要があります。
(ステートメント1; - ステートメント2;)[->.出力集合];
入力集合をとりません。結果集合を生成します。この結果集合は、一つ目のサブステートメントの結果集合に含まれ、かつ二つ目のサブステートメントの結果集合に含まれないすべての要素からなります。
例:
(node[name="Foo"]; - node(50.0,7.0,51.0,8.0););
これは、"Foo" という値の name タグを持ち、かつ与えられた領域には含まれないノードをすべて収集します。
difference ステートメントの結果集合は、通常の接尾辞の記法を使って送り先を指定することができます。
例:
(node[name="Foo"]; - node(50.0,7.0,51.0,8.0);)->.a;
先の例と同様ですが、結果は変数 a に書き込まれます。
積集合 (intersection)
2つの入力セットの両方に現れる要素のセット、つまり両方のセットの一部である要素を生成することも可能です。これについては以下の #By_input_set_.28.setname.29 で説明します。
node.a.b;
これはブロックステートメントではありませんが、上記の差分ステートメントと密接な関係があるため、ここに書いています。
ブロックステートメント if
v0.7.55以降
ブロックステートメント if は条件式が true の時にのみ、そのサブステートメントを実行します。例えば、より厳密な検索条件で結果が得られなかった場合に、より緩やかな検索条件を試すような場合に使用します。
ステートメントはどのセットとも直接相互作用しません。
基本の書式は次の通りです。
if (<条件式>)
{
<サブステートメントのリスト>
}
または
if (<条件式>)
{
<サブステートメントのリスト>
}
else
{
<サブステートメントのリスト>
}
For-each ループ (foreach)
foreach ブロックステートメントは、foreach キーワードと、それに続く 1 組の丸括弧の対で記述します。括弧内には、任意のステートメントの並びを置くことができ、入れ子になった union や foreach を置くこともできます。
入力集合をとります。結果集合は生成しません。foreach ステートメントは、入力集合の内容すべてにわたって、入力集合の各要素につき 1 回ずつ、ループします。
例:
way[name="Foo"];
foreach(
(
._;
>;
);
out;
);
"Foo" という値の name タグを持つウェイすべてについて、ウェイごとに、そのウェイに含まれるノードを出力し、その直後に、ウェイ自身を出力します。より詳しくいうと、まず、way[name="Foo"] の結果集合を、次の入力集合として使います。次に、この入力集合の各要素について、ループの中身が1回ずつ実行されます。ループの中身では、その要素および要素に含まれるノードたちの和集合が作られ、その和集合が出力されます。 ループ実行中、ある反復において出力される部分集合は、別の反復におけるものとは独立しています。このため、全体の出力結果では、重複するオブジェクトがあるかもしれません(ループ内の out ステートメントでは union 処理はされません)。
foreach ステートメントの入力集合は、通常の接尾辞の書式を使って変更することができます。
例:
foreach.a(...);
こうすると、既定の集合 "_" ではなく、集合 a をもとに、ループが実行されます。
丸括弧を開く直前に接尾辞の書式を追加することで、ループの要素を格納する集合を指定することもできます。
例:
foreach->.b(...);
こうすると、ループの要素が変数 b に格納されます。このような記述をしない場合、foreach ステートメントでは、どの集合にも格納されません。 以下の例のようにすると、入力集合とループ要素の集合の両方を指定できます。
foreach.a->.b(...);
注: 入力集合はループで変更することができません。集合を変更すると保存されて以降で使うことができますが、繰り返しの回数は変更されません。
The block statement for
v0.7.55以降
ブロックステートメント for は、入力をサブセットに分割し、ループ本体のすべてのステートメントをサブセットごとに1回実行します。
入力セットは次のように分解されます:
各要素について、指定された条件式が評価され、同じ値を持つ要素がグループ化されます。各ループ実行の開始時に、出力集合は関連するサブ集合で満たされます。
基本の書式は次の通りです。
for (<条件式>)
{
<サブステートメントのリスト>
}
入出力の集合は for と左括弧の間において指定します。
入力集合を指定する場合:
for.<入力集合> (<条件式>)
{
<サブステートメントのリスト>
}
出力集合を指定する場合:
for->.<出力集合> (<条件式>)
{
<サブステートメントのリスト>
}
両方を指定する場合:
for.<入力集合>->.<出力集合> (<条件式>)
{
<サブステートメントのリスト>
}
ループ内では、条件式の値は、出力集合のプロパティ val を介して利用できます。 すなわち、次のように記述するとこのループの式の値にアクセスできます。
<Output Set>.val
特別な条件式 keys() を使用すると、サブセットに存在するすべてのキーをループできます。 各キーのそれぞれのサブセットは、このキーセットを持つ要素です。 通常の条件式とは異なり、その場合、セットは相互に区別されません。
The block statement complete
v0.7.55以降
ブロックステートメント complete は、ループの結果が安定するまで、サブセット全体をループします。これは同じ名前のウェイや川の支流の集まりのように、緩くまたは密に接続された要素を追跡することができます。
ステートメントは、各ループ実行の開始時とステートメント全体の出力の両方で、出力集合に蓄積された要素を出力します。
要素は、ループに入る前に入力集合から蓄積され、ループの終わりに再び入力集合から蓄積されます。 入力集合に余分な要素が含まれている場合、ループが再度実行されます。
基本の書式は下記の通りです。
complete
{
<サブステートメントのリスト>
}
ループの最大値のデフォルトは4096です。この値は1から1048576の間で任意に変更できます。値を設定する場合は "complete" の後で()内に数字を入れます。
complete(<ループする数>)
{
<サブステートメントのリスト>
}
入出力集合を指定する場合は次のように記述します。
入力集合のみ指定:
complete.<入力集合>
{
<サブステートメントのリスト>
}
出力集合のみ指定:
complete->.<出力集合>
{
<サブステートメントのリスト>
}
入出力集合を指定:
complete.<入力集合>->.<出力集合>
{
<サブステートメントのリスト>
}
ループ回数と入出力集合を指定:
complete(<ループする数>).<入力集合>->.<出力集合>
{
<サブステートメントのリスト>
}
The block statement retro
v0.7.55以降
ブロックステートメント retro は、条件文で指定された日付でサブセットを実行します。
現在、ブロック外からの変数の内容がブロック内で使用できるかどうか、またその逆は未定義です。
将来のバージョンでは、派生要素のみを転送したり、環境を完全に分離したり、要素をあるポイントから別のポイントに移動したりする可能性があります。
基本の書式は下記の通りです。
retro (<条件文>)
{
<サブステートメントのリスト>
}
The block statement compare
v0.7.55以降
ステートメント compare は、2つのタイムスタンプのデータの差分を計算します。 特定のプロパティを持つ要素だけでなく、任意の要素で使用できます。
ステートメントにはサブステートメントのブロックを含めることができます。 サブステートメントのブロックは、2回目の実行で差分を計算した後に実行されます。古いタイムスタンプに対して1回、新しいタイムスタンプに対してもう一度実行されます。 これにより、差分結果に基づいて追加の計算を行うことができます。
ステートメントは、diffモードでのみ使用できます。 他のモードでは、その動作は未定義であり、将来のバージョンでは、他の場所に置くと構文エラーになる可能性があります。
diffクエリの最初の実行では、空の集合を返します。 diffクエリの2回目の実行では、要素の違いを返します。
ステートメントが条件文を引数として取得する場合、両方のタイムスタンプで異なる値を持つ要素のみが返されます。
要素がいずれかのタイムスタンプに存在しない場合、その値は空の文字列と見なされます。 現在、そのような差分の唯一の目的は、それを出力ステートメントに出力することです。
基本の書式は下記の通りです。
compare();
入出力集合の両方あるいは一方を指定する場合:
.<入力集合> compare()->.<出力集合>;
条件文を追加する場合:
compare(delta:<条件文>);
組み合わせ:
.<入力集合> compare->.<出力集合>(delta:<条件文>);
すべての書式でサブステートメントのブロックを追加できます:
compare()
{
<サブステートメントのリスト>
};
あるいは
.<入力集合> compare(delta:<条件文>)->.<出力集合>;
{
<サブステートメントのリスト>
};
単独クエリ
出力 (out)
out ステートメントは out: 設定とは異なります。両方を混同しないように。
out ステートメントは、集合の内容を出力します。任意の Overpass QL クエリでほぼ常に使用されます。
out count; は要素の種類（ノード、ウェイ、リレーション、エリア）ごとに入力集合の要素の総数のみを出力するステートメントです。他のものと組み合わせることはできません。
最も単純な形式のoutステートメントには、暗黙のデフォルトがいくつかあります。
out; // outステートメントの最も単純な形
._ out body; // 上記と同じ意味
デフォルトの入力集合 _ は、outステートメントにピリオドと集合名を付加することで無視されます。
.mystuff out; // 'mystuff'という名前の集合を出力
out ステートメントは、out とセミコロンの間に、空白文字で区切った任意の数のパラメーターを追加して、構成することができます。
使えるパラメーターは以下のとおりで、順序は任意です。
- 出力の詳細度。以下のいずれか一つ。既定値は body。
- ids: 要素の id のみを出力します。
- skel: 必要な位置情報をあわせて出力します。追加されるのは、ノードの場合は座標とid。ウェイについてはウェイのidとそのメンバーのノードのid。リレーションについてはリレーションのid、タイプと全てのメンバーのタイプ、id、役割です。
- body: データを使うために必要な情報をすべて出力します。追加されるのは、すべての要素のタグと、リレーションのメンバーの役割です。
- tags: 各要素がもつ id とタグのみを出力し、座標やメンバーの情報は出力しません。
- meta: 要素についてのあらゆる情報を出力します。body で出力される情報に加えて、すべての要素について、バージョン、変更セットの id、タイムスタンプ、最後に手を加えたユーザーのデータが含まれます。派生要素のメタデータ属性も、派生要素にはありません。 修飾子 noids を使用すると、すべてのidをステートメントから省略できます。
- 地理位置情報の次の修飾子の1つ。 デフォルトは'なし'です。
- geom: 各オブジェクトに完全な位置情報を追加します。各ノード、ウェイおよびリレーションのメンバーの各ノードに座標を追加します。また、全リレーションに、座標つきの "nd" メンバーを追加します。
- bb: 各要素に、その要素の境界ボックスを追加します。ノードに対しては "geom" と同じです。ウェイに対しては、含まれる全ノードが内包される境界ボックスです。リレーションに対しては、メンバーたる全ノードおよび全ウェイを内包する境界ボックスです (メンバーたるリレーションの影響はありません)。
- center: ウェイおよびリレーションに対して、前述の境界ボックスの中心のみを追加します。なお、中心点は、必ずしもポリゴン内部にあるとは限らないので注意してください(例)。
- "(南,西,北,東)" の形式の境界ボックス。（通常 "geom" パラメーターで使用されます）この場合、追加した境界ボックス内部の座標のみが生成されます。ウェイについては、正しい形の線分群とするために、境界ボックスからはみだした最初と最後の座標も生成されます。（この制限は、ジオメトリのない派生要素には影響しません。）
- 並び順の指定。以下のいずれか一つ。デフォルトは asc。
- asc: オブジェクト id でソートします。
- qt: 4分割タイルのインデックスでソートします; これは、大雑把な地理的位置順であり、id によるソートよりかなり高速です。（位置情報のないmakeまたはconvertステートメントによって生成された派生要素は個別にグループ化され、idでのみソートされます）
- 出力する要素数の最大値を指定する非負整数。既定値は無制限。
item
item 単独クエリは、入力集合の接頭辞のみからなります。
指定された接頭辞にもとづく入力集合をとります。特に、union ステートメントで使うと便利です。union ステートメントで使った場合、その入力集合をそのまま union ステートメントの結果集合 (の一部) として生成します。
もっともありがちな使い方は、以下のように、既定の入力集合を使ったものです。
._;
union ステートメントの文脈の場合、以下の例は、既定の入力集合のアイテムすべてに、再起下降 の結果を追加したものを返します。
(._; >;);
もちろん、以下のように、他の集合を使うこともできます。
.a;
(.a; .a >;);
注: union ステートメント内で、後に続くステートメントは、item ステートメントの影響を受けません。特に、`.a;` は、その入力集合の内容を既定の集合 "_" に追加したりはしません。
item ステートメントは、フィルターとして使うこともできます。
再帰上昇 (<)
再帰上昇 単独クエリは、単一の小なり記号で記述します。
入力集合をとります。結果集合を生成します。結果集合は以下のものから生成されます。
- 入力集合に現れるノードを持つウェイすべて、加えて、
- 入力集合に現れるノードまたはウェイを持つリレーションすべて、加えて、
- 結果集合に現れるウェイを持つリレーションすべて
例:
<;
再帰上昇ステートメントの入力集合は、通常の接頭辞の記法を使って、選ぶことができます。
.a <;
再帰上昇ステートメントの結果集合は、通常の接尾辞の記法を使って、送り先を変えることができます。
< ->.b;
もちろん、以下のように、この両方を変更することもできます。
.a < ->.b;
再帰上昇リレーション (<<)
再帰上昇リレーション 単独クエリは、再帰上昇と似た文法を持っており、二連の小なり記号で記述します
再帰上昇 単独クエリと同様の記述で、入力集合や結果集合を変えることができます。 再帰上昇 の結果に加えて、入力または結果集合のオブジェクトを指す全てのリレーションが含まれるまで、見つかったリレーションのバックリンクを続けます。
正確には、再帰上昇リレーション 単独クエリは、被包含関係について、反射的かつ推移的な関係をもつ閉包を返します。
書式:
<<;
再帰下降 (>)
再帰下降 単独クエリは、単一の大なり記号で記述します。
入力集合をとります。結果集合を生成します。結果集合は以下のものから生成されます。
- 入力集合に現れるウェイの一部であるノードすべて、加えて、
- 入力集合に現れるリレーションのメンバーであるノードおよびウェイすべて、加えて、
- 結果集合に現れるウェイの一部であるノードすべて
特に、再帰上昇 単独クエリと同様の記述を使って、入力集合や結果集合を変えることができます。
例:
>;
再帰下降リレーション (>>)
再帰下降リレーション 単独クエリは、再帰下降と似た文法を持っており、二連の大なり記号で記述します。
再帰下降 単独クエリと同様の記述で、入力集合や結果集合を変えることができます
入力または結果集合のすべてのオブジェクトについて、そのオブジェクトのすべてのメンバーが結果セットにも含まれるまで、ndsを含むメンバーシップのリンクを追跡し続けます。
正確には、再帰下降リレーション 単独クエリは、包含関係について、反射的かつ推移的な関係をもつ閉包を返します。
書式:
>>;
エリアのクエリ (is_in)
単独クエリ is_in は、以下のものを含むエリアを返します。
- 与えられた座標（指定された場合） または、
- 入力集合に含まれる1つ以上のノード（座標が指定されていない場合）
入力集合または単一の座標のいずれか一方を入力にとります。結果集合を生成します。結果は、入力集合から得られるノードの少なくとも一つ、または指定された座標を、その内部に含むエリアすべてです。
is_in は Overpass QL のフィルターで直接使用することはできません。 is_in の結果をフィルタリングするには追加のクエリが必要です。（下記参照）
[.input_set] is_in [-> .出力集合];
is_in(緯度,経度) [-> .出力集合];
もっとも短い形は、検索対象の座標として入力集合をとるものです。以下の例のようになります。
is_in;
入力集合は、通常の接頭辞の書式を使って変更することができます。
.a is_in;
結果集合は、通常の接尾辞の記法を使って、送り先を変えることができます。
is_in->.b;
もちろん、以下のように、この両方を変更することもできます。
.a is_in->.b;
既存のノードを使うかわりに、2個の浮動小数点数をカンマで区切った形で、座標を指定することもできます。緯度、経度の順に書きます。座標を指定した場合、入力集合は無視されます。以下の例のようになります。
is_in(50.7,7.2);
この形式の場合も、結果集合は、通常の接尾辞の記法を使って、送り先を変えることができます。
is_in(50.7,7.2)->.b;
エリアの生成は、ある抽出規則によっています。すべてのウェイやリレーションに、対応するエリアがあるわけではありません。詳細は areas.osm3s および Areas の Wiki ページをご覧ください。
is_in の結果をフィルタリングするには追加のクエリが必要です。
is_in(48.856089,2.29789);
area._[admin_level="2"]; // ._ は ''is_in'' で返される全てのエリアを含むデフォルトの入力セットを表します。
ステートメント timeline
v0.7.55以降
ステートメント timeline は、オブジェクトのタイプとid、およびオプションでバージョンを引数として受け取ります。 次に、指定されたバージョンのメタ情報を含む派生構造を返します。
バージョンが指定されていない場合、既知のバージョンごとに1つのオブジェクトが返されます。 これらの各オブジェクトには、参照を識別するためのタグ ref 、 reftype 、および refversion があります。 さらに、関連するタイムスタンプを含む created および expired のタグがあります。
基本の書式:
timeline(<Type>, <Ref>);
あるいは
timeline(<Type>, <Ref>, <Version>);
<Type> は node、way、relationの3つのうちのいずれかです。
出力集合を指定する場合:
timeline(<Type>, <Ref>)->.<Set>;
あるいは
timeline(<Type>, <Ref>, <Version>)->.<Set>;
ステートメント local
v0.7.55以降
ステートメント local は、指定された入力をOSMデータのローカライズされた表現に変換します。 出力パラメーターは、含まれるデータのクラスを制御します。
タイプパラメータがない場合、local は次のようにジオメトリとタグを出力します。
- タグ付きノードごとに1つのオブジェクト
- 加えて、ウェイの一部ごとに1つのオブジェクト
- さらに、リレーションジオメトリのパーツごとに1つのオブジェクト
タイプパラメータ"ll"を使用すると、追加のルーズオブジェクトを出力します。
- タグ付きでノードメンバなしのウェイごとに1つのオブジェクト
- ノードまたはウェイメンバーのないリレーションのメンバーごとに1つのオブジェクト
タイプパラメータ"llb"を使用すると、さらに多くのデータを出力します。 OSM要素のidを前述のオブジェクトに関連づけるオブジェクトを提供します。
基本の書式:
local <Type>
<Type>は 空(empty)か"ll"、"llb"です。入出力集合を指定することもできます。
.<入力集合> local <Type> ->.<出力集合>
ステートメント convert
v0.7.54以降
ステートメント convert は、入力セットの要素ごとに1つの派生要素を生成します。 この出力要素の内容は、ステートメントのパラメーターによって制御されます。
生成されたすべての要素のタイプとして固定タイプを設定する必要があります。 その後、任意の数のタグを設定できます。 さらに、元のオブジェクトからすべてのキーをコピーするように指定できます。 この場合、一部のタグを選択的に抑制することもできます。
最後に、生成されたオブジェクトのidを明示的に設定することが可能です。 idを設定しない場合、グローバル昇順カウンターからの一意のidが割り当てられます。
基本の書式:
convert <Type> <List of Tags>
<List of Tags> はコンマ区切りされたアイテムのリストで、次のいずれかです。
<Key> = <Evaluator> ::id = <Evaluator> :: = <Evaluator> !<Key>
ステートメント make
v0.7.54以降
ステートメント make は、実行ごとに1つの派生要素を生成します。 この出力要素の内容は、ステートメントのパラメーターによって制御されます。
生成された要素の型として固定型を設定する必要があります。 その後、任意の数のタグを設定できます。
convert ステートメントとは異なり、ジェネリックキーを設定するには、セットの名前を前に付ける必要があります。
実行時に、ジェネリックキーを使用した make ステートメントは、選択したセットのいずれかの要素に少なくとも1回出現するすべてのキーのタグを設定します。
明示的に定義されたタグは、常に汎用キーメカニズムによって生成されたキーをオーバーライドします。 同様に、明示的にshrekでキャンセルされたタグは、一般的なキーメカニズムによってスキップされます。
最後に、生成されたオブジェクトのidを明示的に設定することが可能です。 idを設定しない場合、グローバル昇順カウンターからの一意のidが割り当てられます。
基本の書式:
make <Type> <List of Tags>
<List of Tags> はカンマ区切りされたアイテムのリストで、次のいずれかです。
<Key> = <Evaluator> <Set>:: = <Evaluator> !<Key> ::id = <Evaluator>
同じキーを2回設定すると構文エラーになります。 また、最大1つのジェネリックキーを設定できます。
クエリステートメント
もっとも重要なステートメントは、クエリ ステートメントです。これは単一のステートメントではなく、種類指定子 node, way, relation（または短縮形 rel）, derived, area, nwr （nodes, ways, relationsの短縮形）のいずれかと、その後に続く、単独または複数のフィルターからなります。結果集合は、各フィルターの条件にマッチする要素すべてです。
例:
// one filter
node[name="Foo"];
way[name="Foo"];
rel[name="Foo"];
nwr[name="Foo"];
nw[name="Foo"];
nr[name="Foo"];
wr[name="Foo"];
derived[name="Foo"];
area[name="Foo"];
// 複数のフィルター
node[name="Foo"][type="Bar"];
ここで、 node, way, rel, nwr, derived, area は種類指定子、[name="Foo"] 、 [type="Bar"] はフィルターであり、セミコロンでステートメントが終わります。
クエリステートメントの結果集合は、通常の接尾辞の記法を使って、送り先を変えることができます。
node[name="Foo"]->.a;
個々のフィルターは、入力集合をとるものがあり、そのようなものは個々のフィルターにおいて入力集合を変更することができます。これについては、それぞれのフィルターの説明をご覧ください。
クエリフィルター
クエリフィルターは、クエリステートメントに条件として追加できます。 引数として条件式を持っていますそして、式がブール値trueを返す要素のみを渡します。
現時点では、クエリフィルターをクエリの唯一の条件にすることはできません。 これは実装上の理由によるものであり、将来のバージョンで変更される予定です。
単一のクエリに複数のクエリフィルターを含めることは技術的に可能です。 しかし、それは意味がありません。 それらの条件式は、単一のクエリフィルターで結合子と組み合わせることができます。 これは同じ意味であり、より高速です。
書式:
(if: <Evaluator>)
スペースはオプションです。
フィルター
タグによるフィルター (has-kv)
has-kv フィルターは、属性値のあるタグを持つ、あるいは持たない要素をすべて選択します。OSM の基本的なオブジェクトの種類であるノード、ウェイ、リレーション、および、拡張された種類であるエリアに対応します。
入力集合をとりません。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
どのフィルターも、開き角括弧( [ )で始まり、その次に単引用符または二重引用符で括られたキー文字列があり、その後はフィルターにより異なります。どのフィルターも、閉じ角括弧( ] )で終わります。文字列がアルファベットだけからなる場合は、引用符を省略することができます。
等号 (=, !=)
もっともありがちな形式です。指定された、特定の値を持つタグを含む要素をすべて選択します。この形式では、キー文字列の後に、等号と、その後に値の文字列を置きます。以下に、例としていくつかの変形を挙げます。これらはすべて等価です。
node[name=Foo];
node[name='Foo'];
node[name="Foo"];
node['name'="Foo"];
node["name"="Foo"];
node["name"='Foo'];
数字、空白類文字などを含む値は、以下のように、単引用符または二重引用符で括る必要があります。
node[name="Foo Street"];
node["name:fr"="Rue Feau"];
等値演算子 (訳註: '=') を使って空の値を問い合わせることは、できません。空の値の検索は、正規表現を使っておこなうことができます。
node[power=""]; // 非対応
node[power~"^$"]; // かわりに、正規表現を使う
同様に、このようなキー・値型のクエリを使って空のキー値を問い合わせることもできないので、正規表現を使って表現する必要があります。
node[~"^$"~"."]; // 空のキー ("") で、何か値を持つノードを検索
註: Overpass Turbo Wizard には、""="" を自動的に変換する機構が組み込まれています。
存在
二つ目の形式です。特定のキーを持つ要素を、値によらず、すべて選択します。キー文字列と閉じ角括弧の間には何も置きません。
node["name"];
node['name'];
node[name];
Not exists
この形式は、特定のキーと任意の値を持つタグを「持たない」すべての要素を選択します。
node[!"name"];
node[!'name'];
node[!name];
値の正規表現マッチ (~, !~)
三つ目の形式です。特定のキーと、正規表現にマッチする値を持つ要素をすべて選択します。キー文字列の後には、チルダと、その後に検索対象の正規表現の文字列を置きます。
| ステートメント | 説明 |
|---|---|
node["name"~"^Foo$"]; |
nameがFooと完全に一致するノードを検索 - node["name"="foo"]; と同じ
|
node["name"~"^Foo"]; |
nameがFooから始まるノードすべてを検索 |
node["name"~"Foo$"]; |
nameがFooで終わるノードすべてを検索 |
node["name"~"Foo"]; |
nameの値にFooを含むノードすべてを検索 |
node["name"~".*"]; |
nameタグを持つノードすべてを検索（ node["name"];と同じ）
|
node["name"!~".*"]; |
nameタグを持たないノードすべてを検索（ node[!"name"];と同じ）
|
なお、QL 中ではバックスラッシュをエスケープする必要があります。 ["name"~"^St\."] は、^St. という正規表現にもとづく結果 ("St" で始まる name すべてを検索) が得られます。["name"~"^St\\."] ならば、St\. という正規表現に相当します ("St." で始まる name すべてを検索)。これは、C 言語のエスケープ規約によるものであり、XML の文法は当てはまりません。
大文字・小文字を区別しない
以下のようにして、大文字・小文字を区別しないようにすることもできます。
node["name"~"^Foo$",i]; /* "foo", "FOO", "fOo", "Foo" などを検索。 */
キーと値(正規表現の有無に関わらず)の形式では、否定を使うことができます。この場合、指定されたキーを持つが値はマッチしない要素、および、指定されたキーのタグを持たない要素を選択します。
node["name"!="Foo"];
node["name"!~"Foo"];
node["name"!~"Foo",i];
キー/値の正規表現マッチ (~"key regex"~"value regex")
四つ目の形式です。キーと値の両方が正規表現にマッチする要素すべてを選択します。最初のチルダ (~) の後に、キーを求めるための正規表現を置き、そのあとに、もう一つのチルダと、値のための正規表現を置きます。
node[~"^addr:.*$"~"^Foo$"]; /* addr:* タグの値が "Foo" と完全に一致するものを検索 */
node[~"^addr:.*$"~"^Foo"]; /* addr:* タグの値が "Foo" で始まるものを検索 */
node[~"^addr:.*$"~"Foo$"]; /* addr:* タグの値が "Foo" で終わるものを検索 */
node[~"^addr:.*$"~"Foo"]; /* addr:* タグの値が "Foo" を含むものを検索 */
node[~"^addr:.*$"~"."]; /* 任意の値をもつ addr:* タグを検索 */
この形式は、大文字と小文字を区別しない検索もサポートしています（キー、値とも）: node[~"^addr:.*$"~"^Foo$",i];
 |
|
境界ボックス
bounding box クエリフィルターは、境界ボックス内部の要素すべてを検索します。
入力集合をとりません。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
(south,west,north,east)
開き丸括弧で始まり、カンマで区切られた4個の浮動小数点数が続き、閉じ丸括弧で終わります。
それぞれの浮動小数点数は、境界ボックスの限界を示します。1個目の数は南限、すなわち最小の緯度です。2個目は西限で、通常は最小の経度です。3個目は北限、すなわち最大の緯度です。4個目は東限で、通常は最大の経度です。2個目の引数が4個目の引数より大きい場合、境界ボックスは180度の経線を跨ぐ形になります。
例:
node(50.6,7.0,50.8,7.3);
再帰 (n, w, r, bn, bw, br)
再帰 フィルターは、与えられたパラメーターに応じて、入力集合の要素のメンバーの要素すべて、あるいは、入力集合の要素をメンバーとして持つ要素すべてを選択します。
入力集合は、接頭辞の記法を追加することで変更することができます。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
開き丸括弧で始まり、w (ウェイをもとに順方向), r (リレーションをもとに順方向), bn (ノードをもとに逆方向), bw (ウェイをもとに逆方向), br (リレーションをもとに逆方向) のいずれかが続きます。その後に、オプションで、入力集合を指定します。閉じ丸括弧で終わります。
以下は、既定の入力集合を使った例です。
node(w); // 入力集合に含まれるすべてのウェイの子ノードを選択
node(r); // 入力集合に含まれるリレーションのメンバーのノードを選択
way(bn); // 入力集合に含まれるすべてのノードの親ウェイを選択
way(r); // 入力集合に含まれるリレーションのメンバーのウェイを選択
rel(bn); // 入力集合に含まれるノードをメンバーとして持つリレーションを選択
rel(bw); // 入力集合に含まれるウェイをメンバーとして持つリレーションを選択
rel(r); // 入力集合に含まれるすべてのリレーションのメンバーのリレーションを選択
rel(br); // 入力集合に含まれるすべてのリレーションの親リレーションを選択
以下は、入力集合を変更した例です。
node(w.foo); // "foo"の入力集合にあるウェイの子ノードを選択
再帰の対象を、特定の役割(role)をもつリレーションのメンバーに限定することができます。コロンと役割名を、閉じ丸括弧の直前に追加すればよいです。
以下は、既定の入力集合を使った例です。
node(r:"role"); // 入力集合に含まれるリレーションのメンバーのノードを選択
way(r:"role"); // 入力集合に含まれるリレーションのメンバーのウェイを選択
rel(bn:"role"); // 入力集合に含まれるノードをメンバーとして持つリレーションを選択
rel(bw:"role"); // 入力集合に含まれるウェイをメンバーとして持つリレーションを選択
rel(r:"role"); // 入力集合に含まれるすべてのリレーションのメンバーのリレーションを選択
rel(br:"role"); // 入力集合に含まれるすべてのリレーションの親リレーションを選択
以下は、入力集合を変更した例です。
node(r.foo:"role");
また、役割を持たないものを明示的に検索することもできます。
node(r:""); // 入力集合に含まれるリレーションで役割を持たないノードメンバーを選択
node(r.foo:"");
入力集合によるフィルター (.setname)
"item" フィルターは、入力集合のすべての要素を選択します。
すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
ドットのあとに、入力集合の名前を書きます。
例: 既定の集合の場合は以下のようになり、
node._;
名前つき集合の場合は以下のようになります。
node.a;
複数の入力集合を指定することもできます。(積集合)
node.a.b;
このステートメントは、入力集合 .a と入力集合 .b の 両方 (積集合) に属するノードをすべて返します。
要素 id によるフィルター
id-query フィルターは、与えられた種類で、与えられた id を持つ要素を選択します。 OSM のデータ種類のノード、ウェイ、リレーションのほか、エリアにも対応しています。
入力集合をとりません。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
開き丸括弧で始まり、その後に正の整数が続きます。閉じ丸括弧で終わります。
例:
node(1);
way(1);
rel(1);
area(1);
エリア id は、OSM のウェイに対してはウェイの id に 2400000000 を加え、リレーションに対しては id に 3600000000 を加える必要があります。なお、エリアの生成は、ある抽出規則によっています。つまり、すべてのウェイやリレーションに、対応するエリアがあるわけではありません。
v0.7.54以降のバージョンでは、 id-query フィルターは複数の値をサポートします。この場合、bounding box フィルターと区別するために id: という接頭辞が必要になります。
node(id:1000,1001,1002,1003,1004,1005);
way(id:3998029,3998240,4065354,4065364,4065392,4065421);
rel(id:10815,10816);
area(id:1234);
他の要素との相対位置 (around)
| 可能であれば around クエリフィルターではなく bounding box クエリフィルターを使用してください。その方が高速です。 |
around フィルターは、入力集合の要素から一定距離内にある要素すべてを選択します。座標を指定した場合は、入力集合のかわりに指定した座標を使います。入力集合は、接頭辞の記法を追加することで変更することができます。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
距離 0 は、ウェイの交差判定に使うことができます。
文法: 開き丸括弧で始まり、その後にキーワード around が続きます。その後に、オプションで、入力集合の指定が続きます。さらにその後に、距離をメートル単位で表す単一の浮動小数点数が続きます。最後に、閉じ丸括弧、または、緯度・経度を表す二つの浮動小数点数(カンマ区切り)および閉じ丸括弧で終わります。
(around[.入力集合]:距離)
(around:距離,緯度,経度)
v0.7.55以降のバージョンでは、緯度/経度のペアのリストで指定されるラインの特定の距離内にあるすべての要素を照会することが可能です。
(around[.入力集合]:距離)
(around:距離,緯度_1,経度_1,緯度_2,経度_2,...,緯度_n,経度_n)
例:
node(around:100.0);
way(around:100.0);
rel(around:100.0);
入力集合を変えた例:
node(around.a:100.0);
座標を指定した例:
node(around:100.0,50.7,7.1);
way(around:100.0,50.7,7.1);
rel(around:100.0,50.7,7.1);
ラインの例:
way[highway](around:500,50.540853270068986,8.048780365649707,50.53106288705902,8.030823236553783,50.51780737956311,8.019643105996508,50.50287491071276,8.016749912560886,50.48828159051387,8.022534398052139,50.47599950382573,8.036215335651725,50.467689755650376,8.055945038928135,50.46447690759688,8.079058902127825,50.46679590711731,8.102435269947343,50.47433280529453,8.122917034379736,50.48606755168466,8.137738019645033,50.50041288059356,8.144896569557243,50.51542994506574,8.143425882283827,50.529090915610794,8.13352458229042,50.53955268865336,8.11652989500613,50.545404823255616,8.09473704711951,50.545858734919165,8.07108928349599,50.540853270068986,8.048780365649707)
;(._;>;);out meta;
例: ボンにある映画館のうち、バス停から 100m 以内にあるものをすべて検索
area[name="Bonn"];
node(area)[highway=bus_stop];
node(around:100)[amenity=cinema];
out;
ボンにある映画館のノードとウェイの両方について、バス停から 100m 以内にあるものをすべて検索
area[name="Bonn"];
node(area)[highway=bus_stop]->.bus_stops;
(
way(around.bus_stops:100)[amenity=cinema];
node(around.bus_stops:100)[amenity=cinema];
);
(._;>;);
out meta;
ポリゴンによるフィルター (poly)
polygon フィルターは、与えられた境界ボックス内部にある、指定された種類の要素をすべて選択します。
入力集合をとりません。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
開き丸括弧で始まり、キーワード poly が続きます。その後に、偶数個の浮動小数点数をスペースで区切った文字列が続きます。2個ずつの浮動小数点の組は、座標を表すもので、緯度・経度の順で記述します。閉じ丸括弧で終わります。
(poly:"緯度_1 経度_1 緯度_2 経度_2 緯度_3 経度_3 …");
例は以下のとおりです (ドイツ・ボン周辺の三角形)。
node(poly:"50.7 7.1 50.7 7.2 50.75 7.15");
way(poly:"50.7 7.1 50.7 7.2 50.75 7.15");
rel(poly:"50.7 7.1 50.7 7.2 50.75 7.15");
高速化のヒント:緯度/経度のペアの数が多いと、(poly: ) フィルターは遅くなります。ポリゴンの形状はシンプルなものを推奨します。
newer
newer フィルターは、指定された日時以降に変更された要素すべてを検索します。他のフィルターとは異なり、このフィルターは単独で使うことはできません。背後にあるデータベースインスタンスが過去のデータに対応している場合は、"newer" ではなく "changed" を使ったほうがおそらくよいでしょう。
入力集合をとりません。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
開き丸括弧から始まり、日時指定が続きます。なお、この日時指定では省略形を使うことはできず、常に単引用符または二重引用符で括る必要があります。閉じ丸括弧で終わります。
例:
node._(newer:"2012-09-14T07:00:00Z");
これは、指定した入力集合から、協定世界時（UTC）で 2012 年 9 月 14 日午前 7 時以降に変更されたノードすべてを検索します。
変更日時によるフィルター (changed)
changed フィルターは、指定された2個の日時の間に変更されたことのある要素すべてを選択します。日時が1個だけ指定された場合、2個目の日時はデータベースの最新の日時とみなします。 日時を1個だけ指定して、現在のタイムスタンプのもとで実行された場合、以下の2点の違いを除き、"newer" と同じ結果が得られます。違いの一つは、こちらの方がより速いこと、もう一つは、単一のフィルターとして使うことができることです。
注: 2017年6月の時点で、既知のバグにより、"changed"が"newer"よりもかなり遅くなる場合があります。 解決されるまで"newer"を使用するか、どちらがより高速に実行されるかをテストすることを検討してください。（参照：Github #278, #322, #346、 議論のページ ）
入力集合をとりません。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
開き丸括弧から始まり、日時指定が続きます。なお、この日時指定では省略形を使うことはできず、常に単引用符または二重引用符で括る必要があります。その後に、カンマと、2個目の日時指定が続きます。閉じ丸括弧で終わります。
例: 指定された日時から現在までの変更すべて
node._(changed:"2012-09-14T07:00:00Z");
例: 2個の指定日時の間の変更すべて
node._(changed:"2012-09-14T07:00:00Z","2012-09-14T07:01:00Z");
ユーザーによるフィルター (user, uid)
user フィルターは、指定されたユーザーが最後に手を加えた要素すべてを検索します。
入力集合をとりません。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
開き丸括弧で始まり、「キーワード user、コロン、検索対象のユーザー名を表す文字列」または「キーワード uid のあとに検索対象のユーザーを表すユーザー ID 」が続きます。閉じ丸括弧で終わります。
例:
node(user:"Steve");
node(uid:1);
v0.7.53以降では、複数のユーザーを指定できます。
node(user:"Mapper1","Mapper2","Mapper 3");
node(uid:1,2,4,8,16);
エリアによるフィルター (area)
area フィルターは、与えられたエリア内部にある、指定した種類の要素をすべて選択します。なお、過去のデータを対象とする場合についても、エリアは常に現在のデータに基づきますので注意してください。
入力集合は、接頭辞の記法を追加することで変更することができます。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
文法: 開き丸括弧ではじまり、キーワード area が続きます。その後に、コロンと非負整数を付けることができます。閉じ丸括弧で終わります。
ノードの場合は、エリアの内部または境界線上にあるものが検索されます。ウェイの場合は、少なくとも 1 点 (線分上の点も可) がエリアの内部 (境界線を含まない) にあるものが検索されます。エリア境界線上に終端があるだけで、エリアと交わらないようなウェイは、検索されません。リレーションの場合は、そのメンバーのいずれかがエリア内部 (境界線上を含まない) にあるものが検索されます。
area ステートメントで整数が指定されない場合は、入力集合から得られるエリアが使われます。例は以下のようになります。
node(area);
way(area);
rel(area);
入力集合を変えた例は以下のようになります。
node(area.a);
way(area.a);
rel(area.a);
整数を追加すると、入力集合は無視され、そのかわりに指定された整数の id を持つエリアを使います。
node(area:2400000001);
way(area:2400000001);
rel(area:2400000001);
警告: area(area); は現在サポートされていません。この場合(area)フィルターは暗黙的に無視され、予期しない結果が生じます。
なぜなら、OSMのエリアはネイティブ要素ではなく、閉じたウェイまたはリレーションを使用してOSMデータベースから推測しているからです。この機能により、クエリで複雑なフィルタリングルールを使用せずに、OSMデータベースでの複雑さと表現に関係なく、ジオメトリを格納できる一貫したセットにさまざまな表現をグループ化できます。 ただし、これらのオブジェクトをOSM id属性に関連付けるには、いくつかの調整が必要です。同じid値が、異なるタイプ（wayまたはリレーション）の無関係な要素に使用される可能性があるためです。 このため、Overpass APIによって返されるエリアには、Overpass APIに固有の「仮想」idのみがあり、OSMデータベースでは直接見つかりません。
エリア id の求めかたは、OSM のウェイに対してはウェイの id に 2400000000 を加え、リレーションに対しては id に 3600000000 を加えることになっています。なお、エリアの生成は、ある抽出規則によっています。つまり、すべてのウェイやリレーションに、対応するエリアがあるわけではありません（特に、area=noでタグ付けされているもの、およびほとんどのマルチポリゴンで、name=*が定義されていないものは、エリアの一部にはなりません）。
エリアは、Overpass API サーバー上の定期的なジョブで生成されているため、OSM 本体のデータベースとは数時間のずれがあります。Overpass json や xml での結果に含まれる `timestamp_areas_base` の値を確認すれば、正確なタイムスタンプがわかります。
より即時の結果が必要な場合（遅延バッチ処理に依存しない）、Overpassクエリでこの機能を使用せずに独自のフィルターを作成することもできます。標準のOSM要素タイプとIDを使用し、選択した特定のタグでフィルターします。
- この機能で照会できる領域を生成するために使用される、現在Overpassが使用しているフィルターの詳細は areas.osm3s を参照して下さい（Overpass QLのXML形式で記述）。これらの領域は "pivot" クエリを使用して定義しています（次の項参照）。
エリアの中核 (pivot)
pivot フィルターは、指定された種類の要素で、与えられたエリアの輪郭を定義するものを選択します。
入力集合は、接頭辞の記法を追加することで変更することができます。すべてのフィルターに共通ですが、結果集合はステートメント全体に対して生成され、個々のフィルターには生成されません。
開き丸括弧で始まり、キーワード pivot が続きます。閉じ丸括弧で終わります。
このステートメントは、入力集合中の各エリアに対して、それぞれのエリアの生成元となる要素を検索します。そのような要素は、マルチポリゴンリレーションまたはウェイのいずれかです。
例:
// デフォルトの入力集合 '_'
way(pivot);
rel(pivot);
// 入力集合 'a'
way(pivot.a);
rel(pivot.a);
以下の例では、最初の行で、グレーター・ロンドン地方のエリアを見つけて、その結果を結果集合 .londonarea に格納します。次の行では、結果集合 .londonarea に含まれるエリアを、pivot フィルターを使って、対応する OSM のリレーションに変換します。最終的に、out geom; でそのリレーションを (ウェイとノードを含めて) 出力します。
area[name="London"][admin_level=6][boundary=administrative]->.londonarea;
rel(pivot.londonarea);
out geom;
条件付きクエリフィルター (if:)
v0.7.54以降
クエリフィルターは、クエリステートメントに条件として追加できます。条件式を引数として持ち、式がブール値trueを返す要素のみを渡します。
現時点では、クエリフィルターをクエリの唯一の条件にすることはできません。 これは実装上の理由によるものであり、将来のバージョンで変更される予定です。
単一のクエリに複数のクエリフィルターを含めることは技術的に可能です。 しかし、それは意味がありません：
- これらの条件式は単一のクエリフィルターで結合子と組み合わせることができます。
- これは同じ意味であり、より高速です。
書式:
(if: <Evaluator>)
空白スペースはオプションです。
クエリの入力集合内のオブジェクトをフィルターするために特定の条件が必要な場合、上記の多くのフィルターは、条件付きクエリフィルターを使用して一般化することができます。 例:
node[name=foo];
このクエリは条件付きクエリフィルターを使用する次のものと同等です（ただし簡単にするために、タグ値によるフィルターを使用する以前の構文は、Overpassサーバーでのパフォーマンスが向上する可能性があるため、推奨されます。 条件式の場合、APIのバージョン0.7.54より前のOverpassサーバーおよびクライアントライブラリの現在の実装ではまだサポートされない可能性があります）。
node(if: t["name"] == "foo");
評価式 (Evaluators)
評価式は、実行時に値を生成する構成要素です。 どちらの評価式を使用するかは、コンテキストによって異なります。
評価式はクエリ文内の要素をフィルタリングするのに有効です。 クエリ結果に対する統計情報を取得できます。 また要素に対しタグの削除・追加ができます。
現時点ではタグに対する評価式のみがサポートされています。 ジオメトリに関する評価式は計画されていますが、現バージョンでは実装されていません。 次の評価式が存在し、以下で説明しています。
- 定数評価式は、コンテキストに関係なく常に同じ値を提供します。
- 要素に依存する評価式は、個々のオブジェクトに関する情報を提供します。
これらは、単一の要素のコンテキストでのみ意味があります。
- 統計評価式は、セット全体に関する情報を提供します。
- アグリゲーターを使用すると、要素に依存する評価式が集合のすべての要素をループし、その結果を組み合わせることができます。
- 演算子と自己準同型は、1つまたは2つの評価式の実行結果を新しい結果に結合します。
TODO:
- 各セクションに正規表現のような簡単な例を追加する必要があります。
- この文書にブログポストした中の簡単な説明の一部を追加する必要があります。
直値 (リテラル)
直値は固定値を表し、演算子の比較とテスト、および評価式への引数として使用できます。 直値の例：
| 直値 | 説明 |
|---|---|
3 |
整数値 3 †* |
3.14159 |
浮動小数点数 3.14159 †* |
2017-09-28T19:51:44Z |
OSMで標準の ISO 8601 形式の日付スタンプ
フォーマットは |
London Bridge |
文字列 ‡ |
addr:housenumber |
OSMでのキーを表す文字列 addr:housenumber ‡ |
† ゼロ未満の負の整数および浮動小数点数（例 -1.3）はそれ自体は直値ではありません。単項マイナス演算子のついた直値です。
* 一部の正および負の整数と浮動小数点数（境界ボックスクエリフィルターのコンテキストで使用される場合など）は、文字列として解釈されます。
‡ ：-のような文字や空白がエバリュエーターによって誤って解釈される可能性を回避するために、これらの直値を引用符で囲むことが望ましいです。 たとえば、 "London Bridge" および "addr：housenumber" は、タグ評価式内の解析の問題を回避します。 "2017-09-28T19：51：44Z" は、タイムスタンプ値を安全に書き込む方法です。
date（）などの一部の関数は、直値をOverpass QLに適した標準書式に変換しようとします。
固定値評価式
この演算子は常に固定値を返します。引数はありません。
書式：
<Value>
要素依存演算子
要素に依存する演算子は、1つのパラメータに依存するか、まったく依存しません。 書式はさまざまですが、ほとんどの場合、関数名と括弧です。
これらは、要素が処理されるコンテキストでのみ呼び出すことができます。 これは、変換、フィルター、または集約関数の引数に適用されます。 makeから直接呼び出すことはできません。
要素のidとtype
演算子 id は要素のidを返します。 演算子 type は要素のtypeを返します。 どちらもパラメーターはとりません。
書式：
id() type()
タグ値と汎用値の演算子
タグ演算子は、指定されたキーのタグの値を返します。
is_tag 演算子は、指定された要素にこのキーのタグがある場合は"1"を返し、そうでない場合は"0"を返します。
これらは要素のコンテキストでのみ呼び出すことができます。
書式：
t[<Key name>] is_tag(<Key name>)
<Key name>に特殊文字を含む場合は引用符で囲む必要があります。 タグ演算子はサブステートメントでも呼び出すことができ、その時の書式は次の通りです。
t[<サブステートメント>]
汎用タグ演算子は、呼び出されたキーのタグの値を返します。 要素のコンテキストでのみ呼び出すことができます。 さらに、キーを指定するには、ジェネリックプロパティの値の一部である必要があります。 書式：
::
オールキー評価式 (all keys評価式)
オールキー評価式は指定された要素のキーをまとめて返します。
書式：
keys()
メタデータ演算子
version演算子は要素のバージョンを返します。
version()
timestamp演算子は要素のタイムスタンプを返します。
timestamp()
changeset演算子は要素が最後に編集された時のチェンジセットのidを返します。
changeset()
uid演算子は要素に最後に触れたユーザーのidを返します。
uid()
user演算子は要素に最後に触れたユーザー名を返します。
user()
要素プロパティ数
v0.7.55以降
countのついた演算子は要素のタグやメンバーの数を返します。 統計的なcount演算子と異なり、追加の引数として入力集合を受け取ることはできません。
タグのカウントの演算子：
count_tags()
メンバーの数をカウントする演算子：
count_members()
異なるメンバーの数をカウントする演算子：
count_distinct_members()
特定のロールを持つメンバーの数をカウントする演算子：
count_by_role()
特定のロールを持つ異なるメンバーの数をカウントする演算子：
count_distinct_by_role()
メンバーごとのアグリゲーター
メンバーごとのアグリゲーターは、ウェイまたはリレーションの単一のメンバーにのみ適用される情報を処理するのに役立ちます。
この例は、ウェイまたはリレーション内の位置、角度などの幾何学的プロパティ、またはロールです。
メンバーごとのアグリゲーターは、引数を操作して複数回実行するための要素を必要とし、要素に加えて可能な位置を1つずつ引数に渡します。
per_member
v0.7.56以降
各要素について、アグリゲーターは要素のメンバーごとに1回引数を実行します。 戻り値は、セミコロンで区切られた戻り値のリストです。 重複排除や整理は行われません。 アグリゲーターはノードと派生物の空の値を返し、その場合にはその引数を実行しないことに注意してください。
書式：
per_member(<評価式>)
per_vertex
v0.7.56以降
要素ごとに、アグリゲーターは、その引数を要素の（内部）頂点ごとに1回実行します。 それ以外の場合は、per_member演算子と同様に動作します。 閉じたウェイの場合、これは、最初のメンバーを除くすべての頂点に対して1回実行されることを意味します。 開いたウェイの場合、最初と最後のメンバーを除くすべての頂点に対して1回実行されます。 リレーションの場合、その動作は現在定義されていません。
書式：
per_vertex(<評価式>)
メンバー依存関数
メンバー依存関数は、要素と要素内の位置がコンテキスト内にある場合にのみ使用できます。 次に、そのメンバーの特定の情報を提供します。
メンバーの位置
v0.7.56以降
位置関数は、メンバー内の要素内の1から始まる位置を返します。
書式：
pos()
メンバーのリファレンス
v0.7.56以降
mtypeとreferenceの演算子は参照されるオブジェクトのメンバーのタイプとidをそれぞれ返します。
書式：
mtype()
ref()
メンバーのロール
v0.7.56以降
role演算子はメンバーのロールを返します。
書式：
role()
メンバーの位置でのウェイの角度
v0.7.56以降
この関数は、このメンバーで終わるセグメントとそこから始まるセグメントの間の角度を返します。 これまでのところ、ウェイについてのみ定義されています。 ウェイが閉じたウェイの場合、最後のメンバーでは最初のセグメントが開始セグメントとして使用されます。 この関数は、per_vertex() 列挙子内で使用することを目的としています。
書式：
role()
ジオメトリ関連演算子
Closedness
v0.7.55以降
is_closed演算子は要素が閉じたウェイか否かを返します。他のタイプの要素では定義されていません。 ウェイに対して、最初のメンバーと最後のメンバーが等しければ"1"を、そうでなければ"0"を返します。 パラメーターはとりません。
書式：
is_closed()
Geometry
v0.7.55以降
geometry演算子は、単一のオブジェクトのジオメトリを、他のジオメトリ変換演算子に入れることができるジオメトリとして返します。
書式：
geom()
長さ (Length)
v0.7.55以降
length演算子は要素の長さを返します。 ウェイに対してはウェイの長さを、リレーションに対してはメンバーのウェイの長さの合計を、ノードに対しては常にゼロを返します。
書式：
length()
緯度・経度 (Latitude, Longitude)
v0.7.56以降
latitudeとlongitude演算子はそれぞれ要素の中心の緯度・経度の座標を返します。
ノードに対してはノードの座標、ウェイとリレーションに対しては境界ボックスの中心から派生した座標の緯度・経度です。
書式：
lat()
lon()
Point evaluator
v0.7.55以降
point 評価式の書式はpt(<latitude>, <longitude>)で、OSMのノードのジオメトリを返します。
返されるジオメトリは、指定された2つの値から導出された緯度と経度のノードです。 ユーザーが入力した緯度latitudeと経度longitudeの各値は、有効な浮動小数点数として解析する必要があります。
latitudeは-90から90の範囲内でなければなりません。小数点は10e-7を越える数字は無視されます(OSMがノードを保存する精度を超えるため)。
longitudeは-180から180の範囲内でなければなりません。小数点は緯度と同様に10e-7までです。
ラインの長さ (Linestring evaluator)
v0.7.55以降
この演算子は常にジオメトリを返します。 ジオメトリは、引数として指定されたポイントで構成される線です。
書式：
lstr(<Evaluator>, <Evaluator>[, ...])
ポリゴン (Polygon evaluator)
v0.7.55以降
この演算子は常にジオメトリを返します。 ジオメトリは、引数として指定された線分で構成されるポリゴンです。 ポリゴンは右手の法則に従い、自己交差はありません。
書式：
poly(<Evaluator>, <Evaluator>[, ...])
アグリゲーター (Aggregators)
アグリゲーターは、操作のための集合と引数としての評価式の両方を実行する必要があります。 その評価式は集合の各要素をループし、アグリゲーターはその結果を結合します。
union と set
これら2つの集約関数は、指定された集合の各要素に対して評価式を実行し、テキスト値を返します。
基本の書式：
<Set>.u(<Evaluator>)
<Set>.set(<Evaluator>)
既定の集合_に対しては、Setパラメーターを省略できます：
u(<Evaluator>)
set(<Evaluator>)
setは、表示されるすべての個別の値をセミコロンで区切ったリストを返します。 uは、メンバーが1つしかないセットなど、単一の一意の値を返す集合を操作するためのものです。 値が1つだけ見つかった場合は、その値が返されます。 値が見つからない場合、uは空の文字列を返します。 複数の異なる値が見つかった場合、uは"< multiple values found >"というテキストを返します。
min と max
基本の書式：
<Set>.min(<Evaluator>) <Set>.max(<Evaluator>)
既定の集合_に対しては、Setパラメーターを省略できます：
min(<Evaluator>) max(<Evaluator>)
これら2つの評価式は、指定された集合の各要素に対して右側の評価式を実行します。
すべての戻り値が有効な数値の場合、minは数値の中の最小値を返します。 同様に、すべての戻り値が有効な数値の場合、maxは数値の最大値を返します。
すべての戻り値が有効な数値でない場合、minは辞書順で最初の文字列を返します。 同様に、すべての戻り値が有効な数値ではない場合、maxは辞書順で最後の文字列を返します。
値が見つからない場合、minとmaxはそれぞれ空の文字列を返します。
sum
基本の書式：
<Set>.sum(<Evaluator>)
既定の集合_に対しては、Setパラメーターを省略できます：
sum(<Evaluator>)
これら2つの評価式は、指定された集合の各要素に対して右側の評価式を実行します。
すべての戻り値が有効な数値の場合、sumはそれらの合計を返します。 すべての戻り値が有効な数値でない場合、sumは"NaN"を返します。
統計的カウント
このcount関連演算子は集合の中の与えられたタイプの要素の数をカウントします。
書式：
count(nodes) count(ways) count(relations) count(deriveds) count(nwr) count(nw) count(wr) count(nr)
集合名を指定する場合は下記の通り。
<Set>.count(nodes) <Set>.count(ways) <Set>.count(relations) <Set>.count(deriveds) <Set>.count(nwr) <Set>.count(nw) <Set>.count(wr) <Set>.count(nr)
ジオメトリの結合 (Union of Geometry)
v0.7.55以降
基本の書式：
<Set>.gcat(<Evaluator>)
既定の集合_に対しては、Setパラメーターを省略できます：
gcat(<Evaluator>)
評価式は、指定された集合の各要素に対して右側の評価式を実行します。
次に、取得したジオメトリを1つの大きなオブジェクトに結合します。 ジオメトリがグループに複数含まれている場合、それらは結果のメンバーとして繰り返されます。
単項演算子
単項演算子はオペランドの実行に必要です。 それらは常に接頭表記で書かれています。 演算子は括弧でグループ化できます。
2種類の形式
<Operator><Evaluator>
と
(<Operator><Evaluator>)
はどちらも同じ意味を持つ表現です。 括弧は演算子の優先順位を示すために使用します。
優先順位は次の通りです。弱いものから強いものへの順に並んでいます。
- 論理和
- 論理積
- 等価、不等価
- 不等号 <、<=、>、>=
- 加算、減算
- 乗算、除算
- 論理否定
- 単項マイナス
論理否定
引数がブール値でfalseとなる場合、論理否定は"1"となります。それ以外は"0"です。 ブール値がfalseとなるのは、空のstd :: stringとゼロの数値表現であるすべてのstd :: stringです。 他のすべてのstd :: stringはブール値trueを表します。
書式：
! <Evaluator>
空白スペースはオプションです。
単項マイナス
単項マイナス演算子はその引数を否定します。 引数が整数または浮動小数点数の場合は、それぞれ整数または浮動小数点数として否定されます。 それ以外の場合、単項マイナス演算子は"NaN"を返します。
書式：
- <Evaluator>
空白スペースはオプションです。
二項演算子
二項演算子は、2つのオペランドを実行する必要があります。 それらは常に中置記法で書かれています。 演算子は括弧でグループ化できます
2種類の形式
<Evaulator><Operator><Evaluator>
と
(<Evaulator><Operator><Evaluator>)
はどちらも同じ意味を持つ表現です。 括弧は演算子の優先順位を示すために使用します。
2 + 3 * 4
は2 + 12と評価され、結果は14になります。
(2 + 3) * 4
は5 * 4と評価され、結果は20になります。
優先順位は次の通りです。弱いものから強いものへの順に並んでいます。
- 三項演算子
- 論理和
- 論理積
- 等価、不等価
- 不等号 <、<=、>、>=
- 加算、減算
- 乗算、除算
- 論理否定
- 単項マイナス
ブール論理和
ブール論理和は1つまたは2つの引数がブール値でtrueとなる場合に"1"となります。それ以外は"0"です。
ブール値がfalseとなるのは、空の文字列とゼロの数値表現であるすべての文字列です。 他のすべての文字列はブール値trueを表します。
現在、両方の引数が常に評価されます。 これは将来のバージョンで変更される可能性があります。
書式：
<Evaluator> || <Evaluator>
空白スペースはオプションです。
ブール論理積
ブール論理積は2つの引数がブール値でtrueとなる場合に"1"となります。それ以外は"0"です。
ブール値がfalseとなるのは、空の文字列とゼロの数値表現であるすべての文字列です。 他のすべての文字列はブール値trueを表します。
現在、両方の引数が常に評価されます。 これは将来のバージョンで変更される可能性があります。
書式：
<Evaluator> && <Evaluator>
空白スペースはオプションです。
等価、不等価
等価の演算子は2つの引数が等しい時に"1"となります。それ以外は"0"です。 不等価の演算子は2つの引数が等しい時に"0"となります。それ以外は"1"です。
両方の引数が整数として解釈できる場合、表現された値が比較されます。 両方の引数を浮動小数点数として解釈できる場合、表現された値が比較されます。 その他の場合はすべて、引数は文字列として扱われます。
等価：
<Evaluator> == <Evaluator>
不等価：
<Evaluator> != <Evaluator>
空白スペースはオプションです。
不等号 <、<=、>、>=
これらの演算子は、引数の比較した結果が正しい時"1"となります。 そうでなければ"0"です。
両方の引数が整数として解釈できる場合、表現された値が比較されます。 両方の引数を浮動小数点数として解釈できる場合、表現された値が比較されます。 その他の場合はすべて、引数は文字列として扱われます。
書式は、小なり、小なりイコール、大なり、大なりイコールの順に
<Evaluator> < <Evaluator>
<Evaluator> <= <Evaluator>
<Evaluator> > <Evaluator>
<Evaluator> >= <Evaluator>
となります。 空白スペースはオプションです。
加算、減算
両方の演算子の優先順位は同じですが、異なる種類の引数を受け入れます。
引数が両方とも整数の場合、それらはそれぞれ整数として加算または減算されます。 引数が両方とも浮動小数点数の場合、それらはそれぞれ浮動小数点数として加算または減算されます。 それ以外の場合、プラス演算子は引数を文字列として連結します。マイナス演算子は"NaN"を返します。
書式：
<Evaluator> + <Evaluator> // 加算
<Evaluator> - <Evaluator> // 減算
空白スペースはオプションです。
乗算、除算
乗算演算子と除算演算子は、それぞれの算術演算を実行します。
引数が両方とも整数の場合、それらはそれぞれ整数として乗算または除算されます。 引数が両方とも浮動小数点数の場合、それらはそれぞれ浮動小数点数として乗算または除算されます。 引数の1つまたは2つともが数値出ない場合、両方の演算子は"NaN"を返します。
<Evaluator> * <Evaluator> // 乗算
<Evaluator> / <Evaluator> // 除算
空白スペースはオプションです。
三項演算子
三項演算子は3つのオペランドが必要になります。
最初のオペランドがブール値trueに評価される場合、2番目のオペランドが評価するものに評価されます。 それ以外の場合は、3番目のオペランドが評価するものに評価されます。 2つの形式
<Evaluator>?<Evaluator>:<Evaluator>
と
(<Evaluator>?<Evaluator>:<Evaluator>)
は同じ意味になります。
文字列の自己準同型
文字列の自己準同型は、1つの引数を持つ関数です。それらの多くは、その引数の値を正規化またはチェックするのに役立ちます。それらは常に最初に自分の引数を評価します。
書式：
<Function Name>(<Evaluator>)
number、is_number、suffix
numberは引数を数値に変換します。 引数が数値で始まる場合、numberはその数値を正規化された形式で返します。 それ以外は"NaN"を返します。
is_numberは引数が数値で始まっているかをチェックします。数字で始まっていれば"1"を返し、それ以外は"0"を返します。
suffixは引数の数値の後に接尾辞がある場合は、それを返します。 引数が数字で始まらない場合は、空の文字列を返します。
書式：
number(<Evaluator>)
is_number(<Evaluator>)
suffix(<Evaluator>)
日付チェック (date、is_date)
dateは、引数を日付を表す数値に変換します。 引数が日付の場合、dateは引数の値を表す数値を返します。 それ以外の場合は"NaD"を返します。
is_dateは、引数が日付を表すかどうかをチェックします。 引数を日付として解析できる場合は"1"を返し、それ以外の場合は"0"を返します。
文字列は次のように日付に解析されます。
- 最初の桁のグループを年とする
- 次の桁のグループが存在する場合、月とする
- その次の桁のグループが存在する場合、日とする
- さらに桁のグループが存在する場合、時・分・秒とする
日付として解釈するためには、年が1000より大きいこと、月が存在する場合は12以下、日が存在する場合は31以下、時が存在する場合は24以下、分と秒が存在する場合は60以下であること。
日付の解析は、将来のバージョンでより自由になり、日付の表現をより受け入れる可能性があります。
書式
date(<Evaluator>)
is_date(<Evaluator>)
ジオメトリの自己準同型
ジオメトリの自己準同型は、1つの引数を持つ関数です。それらの多くは、その引数の値を正規化またはチェックするのに役立ちます。それらは常に最初に自分の引数を評価します。 書式：
<Function Name>(<Evaluator>)
center
v0.7.55以降
centerはその引数の中心を返します。 この関数はジオメトリとして評価することを想定しています。 そしてジオメトリの境界ボックスの中心となるポイントを引き渡します。
書式：
center(<Evaluator>)
trace
v0.7.55以降
traceはその引数のトレースを返します。 この関数はジオメトリとして評価することを想定しています。 その入力に含まれる全てのセグメントとノードの集合を引き渡します。 ウェイは、集合内に明示的にあるポイントと、集合内の複数のウェイに属するポイントで分割されます。 すべてのノードとセグメントは最大で1回含まれます。
書式：
trace(<Evaluator>)
hull
v0.7.55以降
hullは引数の外郭を返します。 この関数はジオメトリとして評価することを想定しています。 引数を全て含む穴のないポリゴンを引き渡します。
書式：
hull(<Evaluator>)
リスト表現された集合演算子
タグの値で複数の値を表す必要がある場合があります。 データ形式では決して必須ではありませんが、事実上の解決策は、値のセットをセミコロンで区切ったリストにしています。
このセクションでは、これらのリストの処理を簡単にするいくつかの関数を提供します。 現在、区切り文字はセミコロンにハードコードされています。 簡単にするために、各リストエントリの先頭または末尾の空白は無視されます。
リストは集合として理解されることにも注意してください。 つまり、リスト要素の順序は関係ありません。
リスト表現された集合の論理演算子
lrs_in
v0.7.55以降
lrs_inは、最初の引数が集合として扱われる2番目の引数に含まれている場合に"1"を返します。 それ以外の場合は"0"を返します。
書式：
lrs_in(<Evaluator>, <Evaluator>)
lrs_isect
v0.7.55以降
lrs_isectは、集合として扱われる2つの引数の共通部分を返します。 引数に共通の値がない場合は、空の文字列が返されます。
書式：
lrs_isect(<Evaluator>, <Evaluator>)
lrs_union
v0.7.55以降
lrs_unionは、集合として扱われる2つの引数の和集合を返します。
書式：
lrs_isect(<Evaluator>, <Evaluator>)
リスト表現された集合の統計演算子
lrs_min
v0.7.55以降
lrs_minは、集合として扱われる2つの引数の要素の最小値を返します。 すべての要素が数値の場合は、数値として比較します。
書式：
lrs_min(<Evaluator>)
lrs_max
v0.7.55以降
lrs_maxは、集合として扱われる2つの引数の要素の最大値を返します。 すべての要素が数値の場合は、数値として比較します。
書式：
lrs_max(<Evaluator>)
集合のKey-Value評価式
集合はメンバー以外も持つことができます。 他のステートメントによって割り当てられたプロパティを取得する場合があります。
例はプロパティ "val"です： このプロパティには、"for"ループ内に現在のループのそれぞれの値が含まれています。
書式：
<Set>.<Property>
他の例とは異なり、集合を明示的に示すことが必須です。
特別な書式
コメント
Overpass QLでは、C、C++やJavascript、CSSのソースコードなどと同じ形式でコメントを書くことができます。
out; // 単一行のコメント
/* スラッシュとアスタリスクで始まるコメントは、必ずアスタリスクとスラッシュで閉じる必要があります。 */
/* なお、この形のコメントは、
複数行にわたって書くことができます。 */
拡張 Overpass Turbo クエリ
Extended Overpass Turbo Queries はOverpass QL言語仕様の一部ではありません。 しかしOverpass QLはOverpass Turbo Query Wizardによって生成されるコードのコアコンポーネントであり、拡張 Overpass Turbo クエリが提供するショートカットについて知ることは、Overpass Turboサーバーにクエリを実行するときに役立ちます。 Overpass Turboクエリの例を見るときに、いつかこの構文を見る可能性があります。
拡張 Overpass Turbo クエリは二重中括弧 {{ }} で識別でされます。
すべてのリストは Extended Overpass Turbo Queriesのページにあります。
エスケープ
以下に挙げる、C 形式のエスケープシーケンスを使うことができます。
\nキャリッジリターンをエスケープ\tタブ文字をエスケープ\",\': それぞれ、二重引用符、単引用符をエスケープ\\: バックスラッシュをエスケープ\u####(ハッシュ文字は、4桁の十六進数です): 対応する unicode UTF-16 コードユニットをエスケープします。Unicode escape sequences をご覧ください。- なお、データベースでは、文字は UTF-8 で 1 バイト (U+0000..U+007F の範囲にある、7 ビット US-ASCII 文字集合に属する文字のみ) あるいはマルチバイトにエンコードされます。Unicode の標準 17 面内のスカラー値が割り当てられたすべての文字は、UTF-8 としてエンコードされます。
- しかし、このエスケープ書式では、BMP に割り当てられた文字にしか対応しません。「サロゲート」は Unicode の「文字」ではなく、妥当な UTF-8 にエンコードできません。BMP の非 ASCII 文字は、UTF-8 では 2 バイト (U+0080..U+07FF の範囲) または 3 バイト (U+0800..U+FFFFの範囲から、U+D800..U+DFFFの範囲の「サロゲート」を除いたもの) にエンコードされます。
- BMP 外の Unicode 文字は、UTF-16 ではサロゲートペアで表現されます。「妥当な」UTF-16 サロゲートペア (U+D800..U+DBFF の範囲の「上位サロゲート」に、U+DC00..U+DFFFの範囲の「下位サロゲート」が続くもの) のみが、UTF-8 に変換可能であり、\uD###\uD### のようにエスケープされます(不正なサロゲートペアや、ペアになっていないサロゲートのエスケープ結果は定義されません)。このようにエスケープされた妥当なサロゲートペアは、UTF-8 に変換すると 4 バイト (追加面 1 から 15) または 5 バイト (最後の追加面である 16、私用面で相互運用性がないため OSM データでは使ってはいけません) になります。
- 現在のところ、近代的な C で使われる、妥当な 17 個の Unicode 各面上の任意のコードポイント (サロゲートを除く) を表現できる \U000##### という共通のエスケープの書式には、対応していません。また、任意の 8 ビットバイト用の共通のエスケープ書式 '\x## (C において、エンコーディング非依存のものとして定義されたもの) にも対応していません。エスケープする必要がなければ、リクエストにエスケープはなるべく使わずに、生の妥当な UTF-8 を使ってください。
その他の機能
ウェイ・リレーションを、エリアに対応づける (map_to_area)
map_to_areaステートメントは、OSM のオブジェクト id (ウェイ、リレーションのいずれも可) を、そのオブジェクトに対応する Overpass API におけるエリア id に対応づけます。
これは、Overpass API 内部で、以下のような対応づけ方法によりおこなわれます。
- ウェイ: ウェイの OSM id に 2400000000 を加える
- リレーション: リレーションの OSM id に 3600000000 を加える
例：
rel(62716);
out; // リレーション 62716 を出力
map_to_area; // OSM のリレーションを、id に 3600000000 を加えることで、Overpass API のエリアに対応づけ
out; // エリア 3600062716 を出力
このステートメントの主な使い途は、大きいエリアの一部分であるエリア内のオブジェクトを検索する("エリア内エリアクエリー")というものです。
注:
- Overpass API 内部のエリア生成過程では、OSM のすべてのウェイやリレーションに対してエリアが生成されるわけではありません。与えられたウェイやリレーションに対応するエリアがない場合、map_to_area は当該オブジェクトを飛ばして、エリアは追加しません。
それ以外の場合、エリアは返されますが、Overpassサーバーの内部バックグラウンドプロセスによって最後に作成または更新されたときのジオメトリで返され、OSMデータベースのウェイ/リレーション要素からロードされた最新のジオメトリとは異なる場合があります 。
- 実際のOSM要素の代わりにクエリでエリアを使用すると、これらのジオメトリをOSMデータベースの多くの子要素から完全にロードし、ウェイを共通のノードに接続することで変換する必要がないため、Overpassクエリを高速化できます。
- また、適切に閉じた「リング」を作成しない場合、すべてのリレーションとウェイが有効な領域に変換されるとは限りません（タグが通常は有効な領域であることを示している場合でも）。
以下に、このステートメントの使い方として考えられるものの概観を示します。
例 1: ケルンの中心業務地区にあるすべての酒場を検索
名前が "Innenstadt" のエリアという条件だけで問い合わせると、ケルン以外も含んだ大量のエリアが返されてしまいます。
area[name="Köln"]->.b;
rel(area.b)[name="Innenstadt"];
map_to_area -> .a;
node(area.a)[amenity=pub];
out meta;
例 2: ヘッセン州の郡のうち、消防署のないものをすべて検索
area[admin_level=4]["name"="Hessen"][boundary=administrative]->.boundaryarea;
( node(area.boundaryarea)["amenity"="fire_station"];
way(area.boundaryarea)["amenity"="fire_station"];
>;
) ->.a;
.a is_in -> .b;
area.b[admin_level=8] -> .bf;
rel(area.boundaryarea)[admin_level=8];
map_to_area -> .bllf;
(.bllf; - .bf; );
rel(pivot);
(._;>;);
out;
例 3ː 郡ごとの薬屋の数を計数
[out:csv(::"type",::"id", name, admin_level,::"count")];
area[name="Saarland"][boundary];
rel(area)[boundary][admin_level=6];
map_to_area;
foreach->.d(
(.d;);out;
(node(area.d)[amenity=pharmacy];
way(area.d)[amenity=pharmacy];
relation(area.d)[amenity=pharmacy];);
out count;
);