Zh-hant:Overpass API

From OpenStreetMap Wiki
Jump to navigation Jump to search
Overpass API - Other languages
Overpass API logo.svg
edit
Overpass API · Language reference · Language guide · Technical terms · Areas · Query examples · Sparse Editing · Permanent ID · FAQ · more (中文（繁體）) · 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 · more (中文（繁體）) · Development · Source code and issues · Web site
Overpass Ultra · Overpass Ultra extensions · MapLibre stylesheets ·more (中文（繁體）) · Source code and issues · Web site
Overpass API logo.svg

簡介

Overpass API (先前被稱為OSM Server Side Scripting，或是2011年前被稱為OSM3S)，是唯讀，可選擇特定的開放街圖圖資的API。Overpass API扮演網路上的資料庫角色：客戶端送出檢索指令到API這邊，然後得到檢索相關的地圖資料。

Overpass API不像主要的API那樣針對編輯的需求最佳化，而是高度針對資料消費者需求，像是只要稍微看幾個東西，或是用幾分鐘時間下載上億的物件，只要選擇適當的搜尋選項，如：地點、資料類型、標籤內容、周圍，或是上述選項的組合。Overpass API扮演不少服務的後端資料庫。

要得到更詳細資訊，請閱讀完整使用者手冊。

Overpass API 比起先前的XAPI為基礎的工具，使用相當強大的檢索語言。要得到更詳細資訊，請見介紹性質的語言指南，或是完整的Overpass檢索語法指南/語法大全。通常我們建議透過interactive 網頁版的前端overpass turbo熟悉Overpass API不同的功能。要為了先前的服務，則有[#XAPI Compatibility Layer|相容性層]]來容許從XAPI順暢的轉換。

公開的Overpass API

要支援小型或是良好擴充的 OSM 主要服務，Overpass API 以第三方服務的方式提供服務。你可以用公開服務的站台：

名稱 資料覆蓋範圍 端點 版本 最新資料 硬體 Munin 使用政策
Main Overpass API instance Global https://lz4.overpass-api.de/api/interpreter 0.7.56.7 b85c4387 是 4 實體核心, 64 GB RAM, SSD Link 三個伺服器任何一個都能每天接受1,000,000的連線請求，你只要每天連線沒有超過10,000檢索，或每天下載量少於5GB資料的話，肯定不會防礙其他使用者。網址overpass-api.de與端點https://overpass-api.de/api/interpreter https://overpass-api.de/api/interpreter]會持續運作，並且每次輪流導向z與lz4
主要Overpass API站臺 Global https://z.overpass-api.de/api/interpreter 0.7.56.8 7d656e78 是 4 實體核心, 64 GB RAM, SSD Link
俄羅斯Overpass API站臺 全球 http://overpass.osm.rambler.ru/cgi/interpreter 0.7.55.7 8b86ff77 没有 8 核心, 64 GB RAM, 硬碟 ?
法國Overpass API站臺 全球 http://api.openstreetmap.fr/oapi/interpreter 0.7.54.10 2e325488 没有 8 核心, 16 GB RAM, SSD [1] 歡迎任何目的用API，只要每天每個"專案"連線沒有超過1,000次檢索的話。(用"專案"計算表示用API在你的智慧型手機App，每天客戶有10,000次檢索，你應該就超過數目了)
瑞士Overpass API站臺 只有瑞士 http://overpass.osm.ch/api/interpreter 0.7.55.7 8b86ff77 没有 12 核心, 64 GB RAM, 硬碟 ? 詢問User:Datendelphin
kumi.systems Overpass API 全球 https://overpass.kumi.systems/api/interpreter 0.7.56.3 eb200aeb 是 20 核心 3 臺伺服器, 256GB RAM, 每個 SSD - 儘管為任何專案使用這臺伺服器，每一臺伺服器都能個別透過 1.overpass.kumi.systems, 2.overpass.kumi.systems 和 3.overpass.kumi.systems 找到。到主要的網址都能平均分配到每一臺，並且儘可能使用。操作上的疑問/問題嗎？請到張貼支援票。

開放歷史地圖也有Overpass API端點。

Overpass API的檢索型式有XML或是Overpass QL，請在下面的章節觀看系統性的解釋。你可以使用Overpass turbo前端來創造或顯示前面提到的Overpass API站臺。

Overpass API也提供永久連結。

社群：我能幫上什麼？

當然：請先詳讀說明文件。

已經有許多針對Overpass API和Overpass Turbo相關問題提供協助的社群網站，如果你的問題其他也有興趣，一般建議可以在上面詢問入門到專家等級的問題。

請注意這些網站上面的老問題與解答常常已經過時了。還沒有的功能已經實作了，而繞道的方式已經主流了，我預測大概兩年後就失效了。

此外，只有OSM Help是由OSM社群經營的園地，其他網站由第三方維運。

網站 語言 常見問題最常用的'標籤'
OSM Help 英語 overpass, overpass-turbo
GIS StackExchange 英語 overpass-api
Stack Overflow 英語 overpass-api
OSM US Slack (channel #overpass) 英語
OSM Dev Telegram group 英語
OSM World Discord (channel #developer) 英語

開發者 / 系統管理員

你可以從最新穩定版，或者從git原始碼倉櫥(最新版本)安裝你自己的站臺。相關程式碼授權為Affero GPL v3.

這項專案由Roland Olbricht (mail: roland.olbricht@gmx.de)維護。而像是回報臭多或是pull requests 到原始碼則相當歡迎。

另外也有開發者郵件論壇

限制

每項服務都有其限制，Overpass API 當然也不例如：

下載巨量資料
由於只有在下載完成的情形下我們才知道Overpass API檢索的大小，因此下載當下並無法預估需要的時間。而從Overpass API動態產生的檔案通常會比下載相同區域的靜態截取還要久 因此，如果你想要截取一個國家區域內所有(近所有)的資料時，建議最好是使用planet.osm的鏡像。當你只有載取一個地方特定的資料時，Overpass API才會很好用
檢索OSM歷史資料
Overpass API並沒有提供changeset為基礎的檢索。雖然是可以用基於時間的diffs來做到，但並不直觀。Overpass API 也無法給你物件的完整歷史，只有基於時間的選取，知道特定時間物件的狀態(retro 和 timeline從版本 0.7.55 開始支援，詳情參見時間與空間片段 )。
資料庫資料時間差
編輯變動會花幾分鐘才會到資料庫，才會出現在 Overpass API 檢索結果當中。每一次檢索會回傳osm_base 的時間戳記來顯示資料何時更新的。overpass-api.de 站臺來說，你可以透過 Munin 察看即時資料與歷史資料庫的時間差(lz4 和 z)。

地圖檢索

在仔細解釋語法之後，我們先討論最常遇到的使用情境，那就是地圖檢索，能夠收集指定的邊界框內(這些請求都會壓縮到最小；注意圖示連結過去的請求也包含算繪地圖中心點的經緯度與縮放層級參數，以及在載入時就立即執行檢索)所有的資料(包括中繼資料)：

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指令時，相關中括號的選項也許能在使用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試試o
[timeout:900][maxsize:1073741824];
node(51.15,7.0,51.35,7.3);
out;

這個檢索將時間從3分鐘延長為15分鐘(寫成900秒)。除此之外，記憶體使用的軟性量度設為1 GiB (等於1073741824位元)。

警告：當執行這個例子時，會收到超過100 MiB的資料(即便沒有給出第一個範例的詳細資料，這邊只會回傳節點以及其標籤清單。)如果直接在瀏覽器渲染資料在地圖上，Overpass會警告你繼續的話，瀏覽器的頁籤會當掉。大型請求的結果應當要先下載後，再用其他工作來處理。

資源限制無法設為較高數值：每個Overpass API站台可能拒絕提高門檻(視伺服器的能力以及目前伺服器負載)，或是檢索失敗出現錯誤訊息(和不OK的HTTP伺服器錯誤狀況)。

進階使用範例

接下來的範例會介紹剩下的指令遞歸(recurse)與附近(around)，兩者都需要與其他指令搭配才行。

再說一次，你可以藉由複製程式片段到檢索視窗來測試範例。

注意：執行檢索會花上數分鐘來完成，如果你遇到時間截止的情形，你可以延長timeout時間。

遞歸(recurse)

使用遞歸(recurse)，你可以檢索關係的成員，像是取得所有路徑參照的節點，用在關係則能取得所有成員節點或成員路徑。另一方面，也能取得節點、路徑或關係屬於成員的上層路徑或關係。你能藉由type屬性來選取元素所屬的種類。

範例：取得所有有鍵ref的值為E61的關係下的節點，就是取得E61下所有的公車站。

Overpass QL Overpass XML
try it yourself in overpass-turbo
rel[ref="E61"];
node(r);

out body;
try it yourself in overpass-turbo
<osm-script><query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-node"/>

<print/></osm-script>


取得所有有鍵ref的值為E61的關係下的路徑，就是取得E61下所有經過的路徑。

Overpass QL Overpass XML
try it yourself in overpass-turbo
rel[ref="E61"];
way(r);

out body;
try it yourself in overpass-turbo
<osm-script><query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>

<print/></osm-script>


取得所有前面提及路徑的節點，你因而不會取得公車站，但這是刻意為之的 - 請見下面的union範例。

Overpass QL Overpass XML
try it yourself in overpass-turbo
rel[ref="E61"];
way(r);
node(w);

out body;
try it yourself in overpass-turbo
<osm-script><query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>
<recurse type="way-node"/>

<print/></osm-script>


取得所有關係中成員名稱為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/>

你也可以符合第一個條件附近的節點的條件下，連鎖方式取得符合第二個篩選條件的節點。像是，我們可以搜尋酒吧"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/>

檢索建構元素

我們仍有幫助性質的解釋，特別是聯集(union)、物件(item)，變數機制與套用所有(foreach)。

再次要強調，下列所有的範例都可以透過複製程式碼片段到這個表單來測試。

聯集(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/>

這邊需要花篇幅解釋：

  • 檢索時收集ref為CE 61的關係，接著寫入結果到預設的變數_，然後用交集(union)來收集資料。
  • 遞歸(recurse)關係-節點收集上述找到的關係成員當中節點的部分，結果會寫入變數nodes當中(我們不再需要了，只是把關係放到預設變數)。然後用交集來收集資料。
  • 遞歸(recurse)關係-路徑再次見到預設變數當中的關係，回傳關係成員當中為路徑的成員，再次用聯集來收集結果。
  • 遞歸(recurse)路徑-節點最後則是針對剛剛收集的路徑中，屬於路徑成員一員的節點，這就構成資料的最後一塊了，也收集聯集(union)結果。

如果你覺得這一切太複雜的話，的確是這樣的。我開放任何改進的看法，但我還沒找到系統性改善的方式。

現在我們已經能藉由bbox-query與數個遞歸參數，並藉由聯集(union)整合來執行地圖呼叫。


物件

物件與變數背後的點子你已經在先前的範例見識到了：每一個聲稱從輸入的變數取得，接著輸出結果到變數。如果你想省略變數名稱，則預設為_。這讓這刪除幾乎所有顯著的變數規範成為可能。 輸入總是從屬性from命名的變數中取得，輸出總是放入into指定的變數當中。 

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

舉例來說，這個相關的例子結果與列印(print)，但是使用顯著聲明的變數foo。

為了使這個概念完全通用，物件(item)允許您在 聯集(union)和檢索(query)中指定一個集合作為輸入： 

<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)確保先前為公車站收集的資料，已經包含在聯集(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)限制先前步驟找到的物件。因此，我們能有一個完整的檢詢來找到在bbox中使用任意標籤的方法。

為每一個(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)，請自行到區域的wiki頁面來查閱詳情。檢索(query)的第一部分收集所有具備特定性質的關係，第二部分則是我們希望為檢索(query)內的每一個元素做些事情，這就要用到為每一個(foreach)。回圈的主體會在輸入的每一個元素都執行一次，包括輸出集合當中，被命名為樞紐(pivot)的單一元素。

中介資料(Meta data)

除了特殊的列印(print)模式之外，有兩個聲稱與檢索特殊中介資料有關，使用者(user)和更新(newer)。

使用者(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)

更新可以用在檢索聲稱內(而且不能用在獨立的聲稱)，更新能夠限制輸出的元件的日期比給定的日期更新。 日期的格式必須是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"/>

如果你想要取得邊界框內所有比給定時間還新的節點，你可以在物件(item)次聲稱內使用檢索(query)。 

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

大眾運輸範例

線段顯示的範例預纜 6 (APS Mobilità)。

如何整合Overpass API進到應用程式的有趣例子 - 產生大眾運輸線段圖案的服務。

右邊有事先渲染的範例。這一頁有更多範例。

在這個wiki站，你可以用有詳細內容的說明文件 {{Sketch Line}}模版。

(請有點耐心點 - 每次請求會需要10秒鐘來產生，視伺服器的負擔狀況。)

注意：Overpass API v0.7.52版本之下，PTv2支援有點問題，造成重覆的站名或是空檔，請見Github issue #190。較新的PTvX版本也有可能出現渲染問題。

XAPI 相容性層

詳細介紹與範例請見：

Overpass相關程式/腳本

Python API

Node.js API

轉換器

演講與工作坊

This section lists previous presentation, talks, workshops on Overpass API and related topics. Many presentations are a good start even for beginners with lots of examples.

日期 活動 地點 題目 性質 講者 語言 連結
2020年2月 OSMit 2020 Torino (IT) Overpass Turbo: oltre il wizard 演講 Andrea Albani 義大利語 簡報 範例
2019年9月 SotMUS 2019 明尼亞波利(美國) A turbo introduction to Overpass 演講 Minh Nguyễn 英語 影片, 簡報, 簡報+筆記
August 2019 COSCUP 2019 OpenStreetMap x Wikidata track 臺北(臺灣) Overpass API/ Turbo 入門：地理資訊應用 (取消) Presentation Assanges 台灣華語
2017年秋季 Université Rennes (FR) Introduction aux données OpenStreetMap et à l'API Overpass Turbo 演講 Boris Mericskay 法語 簡報
August 2017 COSCUP 2017 Open GIS track 臺北 (臺灣) OpenStreetMap and Overpass Turbo Presentation Thomas Tsai 台灣華語 Slides, Video
2016年9月 SotM 2016 布魯塞爾 (比利時) Gardening OSM data with Overpass API 演講 Roland Olbricht 英語 影片
2016年7月 FOSSGIS 2016 - OSM-Sonntag Salzburg (AT) Overpass-Abfragen jenseits key=value selber schreiben 工作坊 Nakaner 德語 簡報
2016年5月 SOTM FR 2016 Clermont-Ferrand (FR) Démystifier l'API Overpass / Demystify the Overpass API 工作坊 Antoine Riche 法語 影片
2015年10月 FOSS@HFT Stuttgart Stuttgart (DE) Parametrisierter Download aus einer weltweiten Geodatenbank (OpenStreetmap) sowie daran anschliessend mit dem Workshop Algorithmik und Technik, Hypothesenprüfung 演講/工作坊 Roland Olbricht 德語 影片
2015年7月 AGIT 2015 Salzburg (AT) Overpass API: OpenStreetMap-Daten vorgefiltert beziehen 演講 Roland Olbricht 德語 ?
2015年6月 SotM US 2015 NYC (US) Working with OSM diffs / The Overpass API 工作坊 Roland Olbricht 英語 ?, 摘要
2015年4月 geo-spatial.org Cluj (RO) Overpass API: utilizarea datelor OpenStreetMap pentru a realiza hărți tematice 工作坊 Alex Morega 羅馬尼亞語 工作坊素材
2015年3月 FOSSGIS 2015 Münster (DE) Schatzsuche in OpenStreetMap 演講 Roland Olbricht 德語 摘要, 影片
2015年3月 FOSSGIS 2015 Münster (DE) OpenStreetMap-Daten pflegen und finden mit der Overpass API 工作坊 (付費) Roland Olbricht 德語 沒有素材
2015年2月 FOSDEM 2015 Bruxelles (BE) Overpass-API - A service to query OpenStreetMap data 演講 Roland Olbricht 英語 簡報, 影片
2014年9月 Bonn (DE) Overpass-API Seminar bei ZERA 工作坊 Roland Olbricht 德語 手稿, 簡報
2014年6月 SotM-EU 2014 Karlsruhe (DE) Overpass API v0.7.50 - The temporal dimension 演講 Roland Olbricht 英語 簡報/影片
2014年6月 SotM-EU 2014 Karlsruhe (DE) Sparse Editing - Editing Large-Scale Objects 演講 Roland Olbricht 英語 簡報/影片
2014年4月 Grazer Linuxtage 2014 Graz (AT) OpenStreetMap Daten nutzen 演講 Martin Raifer 德語 簡報
2014年3月 FOSSGIS 2014 Berlin (DE) Daten aus OpenStreetMap extrahieren, analysieren und filtern mit der Overpass API 工作坊 (付費) Roland Olbricht 德語 沒有提供素材
2013年10月 Intergeo 2013 Essen (DE) OSM-Daten direkt nutzen mit der Overpass API 演講 Roland Olbricht 德語 簡報
2013年10月 OSMit 2013 Rovereto (IT) Overpass Turbo 演講 Martin Raifer 義大利語 簡報
2013年3月 FOSSGIS 2013 Rapperswil (CH) Daten aus OpenStreetMap extrahieren, analysieren und filtern mit der Overpass API 工作坊 Roland Olbricht 德語 簡報
2013年3月 FOSSGIS 2013 Rapperswil (CH) overpass turbo - Einfache Analyse von OpenStreetMap Daten 演講 Martin Raifer 德語 簡報, 影片, Tagungsband FOSSGIS 2013
2013年3月 FOSSGIS 2013 Rapperswil (CH) Mobile Karten erstellen mit OSM, OpenLayers und Overpass API 演講 Roland Olbricht 德語 簡報, 影片
2012年12月 OSMDE009 OSM Talk: Die Overpass API Podcast Roland Olbricht, Stephan/RadioOSM 德語 錄音
2012年3月 FOSSGIS 2012 Berlin (DE) Overpass API 演講 Roland Olbricht 德語 簡報, Tagungsband FOSSGIS 2012
2011年7月 SotM-EU 2011 Vienna (AT) Overpass API - an open and slim XAPI alternative 演講 Roland Olbricht 英語 簡報, 影片

書籍

Olbricht, Roland (2015). “OpenStreetMap in GIScience”. in Jokar Arsanjani, J.; Zipf, A.; Mooney, P. et al.. Springer International Publishing Switzerland. pp. 101-122. ISBN 978-3-319-14280-7. 

Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=Zh-hant:Overpass_API&oldid=2402400"