ES:API de Overpass

From OpenStreetMap Wiki
Jump to navigation Jump to search
Overpass API logo.svg
edit
API de Overpass · Referencia de lenguaje · Guía de lenguaje · Términos técnicos · Áreas · Ejemplos de consultas · Ejemplos avanzados · Edición dispersa · ID permanente · Preguntas frecuentes · más (español) · Sitio web
Estado de servidores · Versiones · Desarrollo · Diseño técnico · Instalación · Capa de compatibilidad XAPI · Esquemas de transporte público · Aplicaciones · Código fuente e incidencias
Overpass turbo · Asistente · Atajos de teclado de Overpass turbo · Hojas de estilo MapCSS · Exportar a GeoJSON · más (español) · Desarrollo · Código fuente e incidencias · Sitio web
Overpass API logo.svg

Introducción

La API Overpass (anteriormente conocida como OSM Server Side Scripting u OSM3S antes de 2011) es una API de solo lectura que sirve partes seleccionadas personalizadas de los datos del mapa OSM. Actúa como una base de datos en la web: el cliente envía una consulta a la API y recupera el conjunto de datos que corresponde a la consulta.

A diferencia de la API principal, que está optimizada para editar, Overpass API está optimizada para consumidores de datos que necesitan algunos pocos elementos al instante o hasta aproximadamente 10 millones de elementos en algunos minutos, todo ello seleccionado mediante criterios de búsqueda como por ejemplo ubicación, tipo de objetos, propiedades de etiquetas, proximidad o combinaciones de ellos. Actúa como un servidor de base de datos para varios servicios.

La API de Overpass tiene un potente lenguaje de consulta con muchas más funciones que las herramientas basadas en la tradicional API Extendida (XAPI) de OSM . Para obtener más información, consulte el nivel introductorio de la guía de lenguaje o la completa Guía de QL de Overpass/referencia de lenguaje. Se recomienda encarecidamente familiarizarse con varias funciones a través de overpass turbo, una interfaz web interactiva basada en la web. Para aplicaciones heredadas también hay una capa de compatibilidad para permitir una transición suave desde XAPI.

Instancias de la API de Overpass públicas

Para soportar los servicios principales de OSM pequeños y bien escalados, la API de Overpass se ejecuta como un servicio de terceros. Puede usar las siguientes instancias públicas:

Nombre Cobertura de datos Endpoint Versión Attic data Hardware Munin Usage policy
Main Overpass API instance Global https://lz4.overpass-api.de/api/interpreter 0.7.55 sí 4 physical cores, 64 GB RAM, SSD Enlace Cualquiera de los tres servidores tiene una capacidad total de aproximadamente 1.000.000 de solicitudes por día. Puede asumir con seguridad que no molesta a otros usuarios cuando hace menos de 10.000 consultas por día y descarga menos de 5 GB de datos por día. La dirección overpass-api.de y el punto final https://overpass-api.de/api/interpreter continuarán para trabajar y redirigir a z y lz4 .
Instancia de API de Overpass principal Global https://z.overpass-api.de/api/interpreter 0.7.55 sí 4 physical cores, 32 GB RAM, SSD Link
Instancia de API de Overpass rusa Global http://overpass.openstreetmap.ru/cgi/interpreter 0.7.54 no 8 cores, 64 GB RAM, hard disks ?
Instancia de API de Overpass francesa Global http://overpass.openstreetmap.fr/api/interpreter 0.7.54 no 8 cores, 16 GB RAM, SSD [1] Puede utilizar esa API para cualquier propósito siempre y cuando no exceda 1000 consultas por día por "proyecto" (por "proyecto" quiere decir que si usa esta API en una aplicación de teléfono inteligente y tiene 10.000 consultas de clientes una vez al día, entonces está por encima del límite). Actualmente con un retraso de 10h
Instancia de API de Overpass principal suiza Suiza únicamente http://overpass.osm.ch/api/interpreter ? no 12 cores, 64 GB RAM, hard disks ? Preguntar a User:Datendelphin
Instancia de API de Overpass irlandesa Isla de Irlanda solamente http://overpass.openstreetmap.ie/api/interpreter (http://overpass-turbo.openstreetmap.ie/) 0.7.54 no 4 x 2.6GHz cores, 8GB RAM, hard disks ? El servidor también ejecuta varios otros servicios, solo para uso ligero.
Instancia de API de Overpass irlandesa de Kumi Systems Global https://overpass.kumi.systems/api/interpreter 0.7.55.7 8b86ff77 tal vez, attic queries fail with runtime errors 4 servers with 20 cores, 256GB RAM, SSD each - Siéntase libre de usar estos servidores en cualquier proyecto. No hay límite de tarifa. Los servidores individuales se pueden encontrar en 1.overpass.kumi.systems, 2.overpass.kumi.systems, 3.overpass.kumi.systems y 4.overpass.kumi.systems, respectivamente. La URL principal se reenviará a uno de ellos a través de round-robin y debe usarse siempre que sea posible. Para problemas operativos/preguntas/comentarios, por favor, publique un ticket de soporte.
Instancia de API de Overpass taiwanesa Global https://overpass.nchc.org.tw/api/interpreter 0.7.55.5 2ca3f387 sí ? ? Si tiene alguna pregunta o comentario, por favor contacte con OSM.tw o NCHC FSL

Puede encontrar una herramienta de evaluación de calidad muy simple que supervisa los servidores Overpass aquí: [2]. Un endpoint de la API de Overpass también está disponible para Open Historical Map.

Las consultas a la API de Overpass están en formato XML o Overpass QL. Consulte la semántica explicada a continuación.

Puede usar la interfaz Overpass turbo para crear y mostrar consultas para las instancias de la API de Overpass mencionadas anteriormente.

La API de Overpass también proporciona enlaces permanentes.

¿Dónde puedo obtener ayuda de la comunidad?

Hay varios sitios donde la comunidad brindan ayuda para cuestiones sobre la API de Overpass y preguntas relacionadas con Overpass Turbo. Estos son los canales recomendados para preguntas introductorias a nivel experto o de manera más general si su pregunta es interesante para un público más amplio.

Sitio Idioma Etiquetas usadas frecuentemente para las cuestiones
OSM Help Inglés overpass, overpass-turbo
GIS StackExchange Inglés overpass-api
Stack Overflow Inglés overpass-api

Desarrolladores/Administradores del sistema

Puede instalar su propia instancia desde la última versión estable o desde el repositorio de código fuente git (última versión). Se distribuye bajo licencia Affero GPL v3.

El proyecto es mantenido por Roland Olbricht (correo electrónico: roland.olbricht@gmx.de). Las contribuciones como informes de errores o solicitudes de extracción a el código fuente son bienvenidas.

Asimismo, eciste una lista de correo para desarrolladores

Limitaciones

Cada servicio posee sus limitaciones y también las tiene la API de Overpass:

  • Descarga de grandes extractos de datos:

Como el tamaño del resultado de una consulta de la API de Overpass solo se conoce cuando se completa la descarga, es imposible determina un Tiempo Estimado (ETA) durante la descarga. Asímismo, los archivos generados dinámicamente desde la API de Overpass generalmente tardan más en crearse y descargarse que descargar extractos estáticos ya existentes de la misma región. Como resultado, cuando desea extraer regiones del tamaño de un país con todos (o casi todos) los datos en él, es mejor usar espejos del planet.osm para eso. La API de Overpass es más útil cuando la cantidad de datos necesarios es solo una selección de los datos disponibles en la región.

  • Consulta del historial de datos OSM:

La API de Overpass no ofrece criterios basados en conjunto de cambios. Es posible evitar esto utilizando diferenciales basados en el tiempo, pero esto puede ser poco útil. La API de Overpass tampoco puede proporcionarle el historial completo de un objeto, pero los criterios de selección basados en el tiempo pueden proporcionarle el estado de un objeto en un momento determinado.

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

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
try it yourself in 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>
try it yourself in overpass-turbo
[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 http://www.overpass-api.de/query_form.html.

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.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-node"/>

<print/>
try it yourself in overpass-turbo
rel[ref="E61"];
node(r);

out body;

Get the ways of all relations that have the key ref with value E61. In fact, that is the itinerary served by E61.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>

<print/>
try it yourself in overpass-turbo
rel[ref="E61"];
way(r);

out body;

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.

Overpass XML Overpass QL
try it yourself in overpass-turbo
<query type="relation">
  <has-kv k="ref" v="E61"/>
</query>
<recurse type="relation-way"/>
<recurse type="way-node"/>

<print/>
try it yourself in overpass-turbo
rel[ref="E61"];
way(r);
node(w);

out body;

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:

try it yourself in overpass-turbo
<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":

try it yourself in 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/>

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 http://www.overpass-api.de/query_form.html.

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

Example preview of line 6 (APS Mobilità).

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:

Programs/Scripts around Overpass

Python API

Node.js API

Converters

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
Autumn 2017 Université Rennes (FR) Introduction aux données OpenStreetMap et à l'API Overpass Turbo Presentation Boris Mericskay French Slides
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 Link
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

Libros

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