Zh-hans:Overpass API
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 · more (中文（简体）) · Development · Source code and issues · Web siteOverpass Ultra · Examples · Overpass Ultra extensions · MapLibre stylesheets · URL Params · more (中文（简体）) · Source code and issues · Web site
| Overpass API | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
 | ||||||||||||||||||||
| 作者： | drolbr/Overpass-API/graphs/contributors GitHub | |||||||||||||||||||
| 执照： | GNU AGPL v3 (免费) | |||||||||||||||||||
Status ：
|
Active | |||||||||||||||||||
| 版本： | 0.7.62.4 (2024-11-21) | |||||||||||||||||||
| 网站： | overpass-api.de | |||||||||||||||||||
| 源代码： | drolbr/Overpass-API GitHub | |||||||||||||||||||
| 编程语言： | C++ | |||||||||||||||||||
|
A database engine to query the OpenStreetMap data |
||||||||||||||||||||
| ||||||||||||||||||||
简介
Overpass API (原名OSM Server Side Scripting, 2011年前也被称为OSM3S), 是一个只读, 用来获取特定OSM地图数据的API. 作为一个网络数据库, 用户向其发送API请求, 从而返回对应的数据.
不同于主要的 API 对编辑功能进行了优化, Overpass API 是针对数据消费者进行了优化, 通过不同的筛选条件, 比如: 位置, 数据类型, 标签, 周围, 或者以上的组合, 可以使用户瞬间获取少量数据, 或数分钟内获取数以千万级的数据, 其扮演着多种服务的后端数据库角色.
如需更加详细的介绍, 请参考完整的用户手册.
此外, 关于Overpass QL, 请参考这里. 我们强烈建议您通过overpass turbo 来进一步了解各种功能特性. 对于旧的应用程序, 您可以使用兼容层来确保可以从 XAPI 顺利地迁移过来.
公开的 Overpass API 实例
为了支撑小型及良好扩充的OSM 主服务, Overpass API 以第三方服务的形式运行. 您可以使用以下开放的公共实例:
| 名称 | 数据覆盖范围 | 接口 | 版本 | Attic data | 硬件 | Munin | 使用政策 |
|---|---|---|---|---|---|---|---|
| Main Overpass API instance | 全球 | https://lz4.overpass-api.de/api/interpreter | 0.7.57.1 74a55df1 | Yes | 4 physical cores, 64 GB RAM, SSD | Link | Any of the three servers has a total capacity of about 1,000,000 requests per day. You can safely assume that you don't disturb other users when you do less than 10,000 queries per day and download less than 5 GB data per day. The address overpass-api.de and endpoint https://overpass-api.de/api/interpreter will continue to work and redirects per round robin to z and lz4. |
| Main Overpass API instance | 全球 | https://z.overpass-api.de/api/interpreter | 0.7.57 93a4d346 |
Yes | 4 physical cores, 64 GB RAM, SSD | Link | |
| VK Maps Overpass API instance (Russia) | 全球 | https://maps.mail.ru/osm/tools/overpass/api/interpreter | 0.7.57.1 |
Yes | 2 servers with 56 physical cores, 384Gb RAM, SSD each | - | Feel free to use our services in any project. There are currently no requests limitations and we will try to keep this approach in the future.
Note: Due to a missing |
| Russian Overpass API instance | 全球 | https://overpass.openstreetmap.ru/api/interpreter | 0.7.57.1 |
No | 8 cores, 64 GB RAM, hard disks | ||
| Swiss Overpass API instance | 瑞士 | https://overpass.osm.ch/api/interpreter | 0.7.56.8 7d656e78 |
No | 12 cores, 64 GB RAM, hard disks | Ask User:Datendelphin | |
| Kumi Systems Overpass Instance | 全球 | https://overpass.kumi.systems/api/interpreter | 0.7.57 93a4d346 |
Yes | 4 servers with 20 cores, 256GB RAM, SSD each | Feel free to use our service in any project, there is no rate limit in place. Please notify us in advance if you intend to use our service in a large scale project. Operational issues/questions/feedback? Please post a support ticket. |
Overpass API 接口也可用于开放历史地图。
对 Overpass API 的查询采用 XML 或 Overpass QL 格式。 请参阅下面解释的语义。 您可以使用 Overpass turbo 前端为上述 Overpass API 实例创建和显示查询。
Overpass API 还提供永久链接。
社区: 如何获取帮助?
首先 - 请注意 Overpass Turbo 与 Overpass API 的文档是分开的。 Overpass API 文档是无法搜索的，除非您已经非常熟悉 Overpass API 本身，否则它实际上不会对您有太大帮助。 如果您通过 .e.g Taginfo 来到 Overpass，那么您真正想要的是 可能是Overpass Turbo 的文档（其中包括一个查询向导）。
有部分社区网站可以提供有关 Overpass API 和 overpass turbo 的帮助。 建议您去这些相关的渠道, 求助从入门至进阶, 或者更加普遍的问题.
请注意，这些网站上的旧问题和旧答案可能已过时。 在此期间, 某些缺失的功能可能已经实现，或者有了变通方法。 如果您在 IRC 或 Slack 等实时帮助网站上提问，那么您会得到最新的答案。
此外，只有 IRC 和 OSM 帮助链接由 OSM 社区管理, 其他站点由第三方控制。
| 站点 | 语言 | 常用的问题标签 |
|---|---|---|
| IRC - #osm channel | 英文 | n/a - just ask your question |
| 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 维护（邮件：roland.olbricht@gmx.de）。 欢迎通过提交错误报告或拉取请求来对源代码做出贡献.
此外, 也有一个开份发人员的邮件清单.
限制
正如任何服务都有限制, Overpass API 也不例外:
- 下载大量资料
- 由于 Overpass API 查询结果的大小只有在下载完成后才能知道，所以在下载时无法给出 ETA。 并且从 Overpass API 动态生成的文件来下载, 通常比从现有静态资源提取同样区域的文件更耗时。 因此，当您想要提取包含所有（或几乎所有）数据的国家级文件时，最好使用planet.osm 镜像。 当所需的数据只是部分区域时，Overpass API 最有用。
- 查询OSM历史资料
- Overpass API 不提供基于changeset 的检索。但您仍然可以实现。
The map query
Before we get to a detailed syntax explanation, we present the probably most common use case, the map query, to collect all data (including metadata) from a given bounding box (these requests are compacted to the minimum; note that the icon links to run those requests also include parameters to set the center of the rendered map at specified coordinates and zoom level, and to run the request immediately on load):
| Overpass QL | Overpass XML |
|---|---|
 (
node(51.249,7.148,51.251,7.152);
<;
);
out meta;
|
<union>
<bbox-query s="51.249" w="7.148" n="51.251" e="7.152"/>
<recurse type="up"/>
</union>
<print mode="meta"/>
|
To run this query, you can feed it into this query form, or you can use Overpass Turbo to see the results on a map.
The order of values in the bounding box (51.249,7.148,51.251,7.152) is minimum latitude, minimum longitude, maximum latitude, maximum longitude (or South-West-North-East). See more details about bbox below.
Simple usage examples
To find out more about the Overpass API query language, see Overpass API Language Guide, as well as the Overpass API Query Language description.
Resource management options (osm-script)
The osm-script is silently added if you don't specify it explicitly when using the XML syntax. The reason to specify one explicitly is to tweak the resource management options by setting optional XML attributes (equivalent bracketted options may also be specified in an empty statement at start of your query when using the QL syntax).
| Overpass XML | Overpass QL |
|---|---|
<osm-script timeout="900" element-limit="1073741824">
<bbox-query s="51.15" w="7.0" n="51.35" e="7.3"/>
<print/>
</osm-script>
|
[timeout:900][maxsize:1073741824];
node(51.15,7.0,51.35,7.3);
out;
|
This query extends the timeout from 3 minutes to 15 minutes (written as 900 seconds). Additionally, the soft quota for memory usage is set to 1 GiB (equals 1073741824 byte).
Warning: when running this example, more than 100 MiB of data will be retrieved (even if it does not recurse up to give all details like in the first example, here it will only retrieve a flat list of nodes with their tags). Overpass will alert you if you run it directly in your browser to render the data on the map, the browser tab may crash if you continue loading it. The results of such large requests should be downloaded for processing by other tools.
These resource limits cannot be set to arbitrary high values: each Overpass API instance may refuse to extend them above some threshold (depending on server capabilities or current server load), or the query may just fail with an error message (and non-OK HTTP server error status).
Advanced usage examples
The following examples introduce the remaining commands recurse and around. They only make sense in combination with other commands.
Again, all of the following examples can be tested by copying the snippets to this query form.
Note: Queries may take several minutes to be completed. If you receive timeouts, you can extend the timeout period.
Recurse
With recurse, you query for membership relations. It is available for ways to get all referred nodes, for relations to get all member nodes or member ways. Or the other way round, to get for a node, way or relation the ways or relations the element is member of. You select among the type of element by the type attribute.
Example: Get the nodes of all relations that have the key ref with value E61. In fact, get all bus stops served by E61.
Get the ways of all relations that have the key ref with value E61. In fact, that is the itinerary served by E61.
Get the nodes of the above mentioned ways. You don't get the bus stops, but that is intentionally - see below at the union examples.
Get all relations that have the nodes named Lichtscheid as members. These are the bus lines stopping there.
<query type="node">
<has-kv k="name" v="Lichtscheid"/>
</query>
<recurse type="node-relation"/>
<print/>
Get all the ways that have a node member within the given bounding box.
<bbox-query s="51.249" n="51.251" w="7.149" e="7.151"/>
<recurse type="node-way"/>
<print/>
And we can also get relation members of relations:
<query type="relation">
<has-kv k="name" v="VRR Buslinien"/>
</query>
<recurse type="relation-relation"/>
<print/>
Or the same thing backwards:
<query type="relation">
<has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-backwards"/>
<print/>
Around
around allows you to get all nodes near one or more given nodes. For example, to get all nodes that are at most 10 meters around the nodes called Bristol:
<query type="node">
<has-kv k="name" v="Bristol"/>
</query>
<around radius="10"/>
<print/>
You can also chain queries to get only nodes satisfying a second criterion that are located near nodes matching the first criterion. Here, we will search for all bus stops within 100 meters of pubs named "Bristol":
<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/>
Building blocks
We still have some helper statements to explain, in particular union, item, the variable mechanism, and foreach.
Again, all of the following examples can be tested by copying the snippets to this form.
Union
Union allows you to group the results of several queries. For example, you can get all nodes that have name Lichtscheid or 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/>
Another usage would be to get a relation with all of its members, including the nodes of member ways.
<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/>
This needs some explanation:
- query collects the relations with ref CE 61. It writes the result to the default variable _. And the embracing union collects the data.
- recurse relation-node collects the nodes that are members of the above found relations. The result is placed in the variable nodes (we don't need it there anymore, just to keep relations in the default variable). And it is collected by the embracing union.
- recurse relation-way sees again the relations from the default variable and returns the ways that are members of the default variable's relations. Again, the embracing union collects the results.
- recurse way-node finally returns the nodes that are members of the ways just collected. This is the last piece of data that goes into the union's result.
If you think this is complicated, you are right. I'm open to suggestions how to improve the statement semantics, but I haven't found anything systematic yet.
Now we are ready to assemble the map call, by combining a bbox-query with several recurse statements and embracing the whole thing with an union.
Item
Part of the idea behind item and variables you have already seen in the preceding example: every statement fetches its input from a variable and puts its output into a variable. If you omit the variable name, it defaults to _. This makes in possible to remove almost all explicit specifications of variables. The input is always fetched from the variable named by the attribute from, the output is always put into the variable specified with into.
<query type="way" into="foo">
<has-kv k="name" v="Am Hofe"/>
</query>
<print from="foo"/>
E.g., this does the same as the respective example at print, but it uses the explicitly stated variable foo. To make this concept fully versatile, item allows you to specify a set as input in union and 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/>
Here, in the middle, the item ensures that the beforehand collected data for bus_stop is included in the results of union. This also shows how the variable stops is necessary to make the query possible.
<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/>
The item in query restricts the possibly found items to those already found in the step before, with recurse. Thus, we have a complete query to find ways with arbitrary tags within a 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>
This is the essential part of the rule that creates the areas. We do not explain the make-area here, please have a look at Areas wiki page for details. The first part with query collects all relations with certain properties. In the second part, we want to do something with each element in the result of query. This does foreach. The body of the loop is executed once for every element in the input set, containing exactly this single element in the output set, here named as pivot.
Meta data
Beside the special mode of print, there are two statements dedicated to query for specific meta data, user and newer.
User
You can select all data that has been touched the last time by a particular user. Choose the user name (for example, mine):
<user name="Roland Olbricht"/>
<print mode="meta"/>
Or choose a user id:
<user uid="65282"/>
<print mode="meta"/>
This statement can also be used within a query statement. It then restricts the result to data that has been last touched by the provided user:
<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 can be used within query statement (and not as a standalone statement). It restricts the output to elements that are newer than the given date. The date must be in the format YYYY-MM-DDTHH:MM:SSZ. It refers, as the results, always to the timezone 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"/>
If you want to get all nodes newer than a certain date from a bbox, you can use query with an item substatement.
<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"/>
Public transport example
An interesting example of how the Overpass API can be integrated into an application - a service to generate line diagrams for public transport.
See example prerendered views on the right. More examples on this page.
On this wiki, you can create links to this tool with the documented {{Sketch Line}} template.
(Please be patient - each request can take up to 10 seconds to generate, depending on server load.)
Note: As of Overpass API v0.7.52, PTv2 support has some known issues, resulting in duplicate stop names or some gaps, see Github issue #190. Rendering issues for newer PTvX versions or variations thereof may be possible as well.
XAPI Compatibility Layer
For details and examples see:
- Overpass API/XAPI Compatibility Layer
- Overpass XAPI query builder at harrywood.co.uk
Programs/Scripts around Overpass
Python API
- There is a Python transpiler which converts a Python function to an Overpass query
- There is a simple Python wrapper written by Martijn van Exel (talk).
- There is an advanced Python wrapper called OverPy
- OSMPythonTools provides easy access to OSM related services, including Overpass
Node.js API
- query-overpass is a simple API wrapper and CLI for Overpass.
Converters
- To GPX output osm2node source code and Online service
- API 0.6 wrapper source code and Online service
- osmtogeojson converts OSM data to GeoJSON and has full support for Overpass API's extended geometry output modes.
- gimmeOSM lets you enter a feature ID and returns it as GeoJSON.
Talks, Presentations, Workshops
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.
| Date | Event | Location | Title | Type | Speaker | Language | Links |
|---|---|---|---|---|---|---|---|
| February 2020 | OSMit 2020 | Torino (IT) | Overpass Turbo: oltre il wizard | Presentation | Andrea Albani | Italian | Slides Examples |
| September 2019 | SotMUS 2019 | Minneapolis (US) | A turbo introduction to Overpass | Presentation | Minh Nguyễn | English | Video, Slides, Slides+notes |
| August 2019 | COSCUP 2019 OpenStreetMap x Wikidata track | Taipei (TW) | Geographic Data for Beginners - An introduction to Overpass API Turbo (Canceled) | Presentation | Assanges | Mandarin | |
| Autumn 2017 | Université Rennes (FR) | Introduction aux données OpenStreetMap et à l'API Overpass Turbo | Presentation | Boris Mericskay | French | Slides | |
| August 2017 | COSCUP 2017 Open GIS track | Taipei (TW) | OpenStreetMap and Overpass Turbo | Presentation | Thomas Tsai | Mandarin | Slides, Video |
| September 2016 | SotM 2016 | Brussels (BE) | Gardening OSM data with Overpass API | Presentation | Roland Olbricht | English | Video |
| July 2016 | FOSSGIS 2016 - OSM-Sonntag | Salzburg (AT) | Overpass-Abfragen jenseits key=value selber schreiben | Workshop | Nakaner | German | Slides |
| May 2016 | SOTM FR 2016 | Clermont-Ferrand (FR) | Démystifier l'API Overpass / Demystify the Overpass API | Workshop | Antoine Riche | French | Video |
| Oct 2015 | FOSS@HFT Stuttgart | Stuttgart (DE) | Parametrisierter Download aus einer weltweiten Geodatenbank (OpenStreetmap) sowie daran anschliessend mit dem Workshop Algorithmik und Technik, Hypothesenprüfung | Presentation/Workshop | Roland Olbricht | German | Video |
| July 2015 | AGIT 2015 | Salzburg (AT) | Overpass API: OpenStreetMap-Daten vorgefiltert beziehen | Presentation | Roland Olbricht | German | ? |
| June 2015 | SotM US 2015 | NYC (US) | Working with OSM diffs / The Overpass API | Workshop | Roland Olbricht | English | ?, Abstract |
| April 2015 | geo-spatial.org | Cluj (RO) | Overpass API: utilizarea datelor OpenStreetMap pentru a realiza hărți tematice | Workshop | Alex Morega | Romanian | Workshop materials |
| March 2015 | FOSSGIS 2015 | Münster (DE) | Schatzsuche in OpenStreetMap | Presentation | Roland Olbricht | German | Abstract, Video |
| March 2015 | FOSSGIS 2015 | Münster (DE) | OpenStreetMap-Daten pflegen und finden mit der Overpass API | Workshop (paid) | Roland Olbricht | German | no material available |
| February 2015 | FOSDEM 2015 | Bruxelles (BE) | Overpass-API - A service to query OpenStreetMap data | Presentation | Roland Olbricht | English | Slides, Video |
| September 2014 | Bonn (DE) | Overpass-API Seminar bei ZERA | Workshop | Roland Olbricht | German | Manuscript, Slides | |
| June 2014 | SotM-EU 2014 | Karlsruhe (DE) | Overpass API v0.7.50 - The temporal dimension | Presentation | Roland Olbricht | English | Slides/Video |
| June 2014 | SotM-EU 2014 | Karlsruhe (DE) | Sparse Editing - Editing Large-Scale Objects | Presentation | Roland Olbricht | English | Slides/Video |
| April 2014 | Grazer Linuxtage 2014 | Graz (AT) | OpenStreetMap Daten nutzen | Presentation | Martin Raifer | German | Slides |
| March 2014 | FOSSGIS 2014 | Berlin (DE) | Daten aus OpenStreetMap extrahieren, analysieren und filtern mit der Overpass API | Workshop (paid) | Roland Olbricht | German | no material available |
| October 2013 | Intergeo 2013 | Essen (DE) | OSM-Daten direkt nutzen mit der Overpass API | Presentation | Roland Olbricht | German | Slides |
| October 2013 | OSMit 2013 | Rovereto (IT) | Overpass Turbo | Presentation | Martin Raifer | Italian | Slides |
| March 2013 | FOSSGIS 2013 | Rapperswil (CH) | Daten aus OpenStreetMap extrahieren, analysieren und filtern mit der Overpass API | Workshop | Roland Olbricht | German | Slides |
| March 2013 | FOSSGIS 2013 | Rapperswil (CH) | overpass turbo - Einfache Analyse von OpenStreetMap Daten | Presentation | Martin Raifer | German | Slides, Video, Tagungsband FOSSGIS 2013 |
| March 2013 | FOSSGIS 2013 | Rapperswil (CH) | Mobile Karten erstellen mit OSM, OpenLayers und Overpass API | Presentation | Roland Olbricht | German | Slides, Video |
| December 2012 | OSMDE009 OSM Talk: Die Overpass API | Podcast | Roland Olbricht, Stephan/RadioOSM | German | Audio | ||
| March 2012 | FOSSGIS 2012 | Berlin (DE) | Overpass API | Presentation | Roland Olbricht | German | Slides, Tagungsband FOSSGIS 2012 |
| July 2011 | SotM-EU 2011 | Vienna (AT) | Overpass API - an open and slim XAPI alternative | Presentation | Roland Olbricht | English | Slides, Video |
Books
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.
| Overpass QL | Overpass XML |
|---|---|
rel[ref="E61"];
node(r);
out body;
|
<osm-script><query type="relation">
<has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-node"/>
<print/></osm-script>
|
| Overpass QL | Overpass XML |
|---|---|
rel[ref="E61"];
way(r);
out body;
|
<osm-script><query type="relation">
<has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>
<print/></osm-script>
|
| Overpass QL | Overpass XML |
|---|---|
rel[ref="E61"];
way(r);
node(w);
out body;
|
<osm-script><query type="relation">
<has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>
<recurse type="way-node"/>
<print/></osm-script>
|