bounding_boxes.html

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<style>
pre { background-color:yellow; padding:0.5em; }
</style>
<title>Bounding Boxes</title>
</head>
<body style="font-family:sans-serif; max-width:30em">

<p><a href="../index.html">Overpass API</a> &gt; <a href="index.html">Blog</a> &gt;</p>

<h1>Bounding Boxes</h1>

<p>Published: 2017-04-17</p>

<h3>Table of content</h3>

<a href="#global_bbox">Global Bounding Box</a><br/>
<a href="#lonlat_bbox">The <em>bbox</em> Parameter</a><br/>
<a href="#geom_bbox">Output with Bounding Box</a><br/>

<h3>Introduction</h3>

<p>As I <a href="final_0_7_54.html">have announced last week</a>,
I will walk through the <a href="https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_API_by_Example">examples page</a> for the next weeks.
I hope that I can bring that page back up-to-date.</p>

<p>The use of bounding boxes is the first thing that is out of date there.
For that reason, I would like to explain
which bounding boxes beyond the standard filter exist
and what they are good for.</p>

<h2 id="global_bbox">Global Bounding Box</h2>

<p>Have you ever, like me, typed a request like this one?
Do you see immediately what the problem here is?</p>
<pre>
node[amenity=restaurant];
out center;
</pre>
<p>Five seconds after sending the request I am stunned that the request is still running.
Another five seconds later I realize that I have forgotten the bounding box.
There are some hundred millions of ways with this tag,
thus neither the query engine nor the display engine can handle that amount of data in a sane way.
And that is just because I have forgotten the bounding box:</p>
<pre>
node[amenity=restaurant]({{bbox}});
out center;
</pre>

<p>This is where the Global Bounding Box is helpful:
The <a href="https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#Global_bounding_box_.28bbox.29">Global Bounding Box</a> is set once per request.
It then automatically applies to every query statement in the request.
This means that the following two requests do exactly the same. This one:</p>
<pre>
node[amenity=restaurant]({{bbox}});
out center;
</pre>
<p>and <a href="https://overpass-turbo.eu/s/ooM">this one</a>:</p>
<pre>
[bbox:{{bbox}}];
node[amenity=restaurant];
out center;
</pre>

<p>I, personally, have the global bounding box always in the request
and drop it only if the request is intended to be global.
You may ask why the Global Bounding Box is not turned on by default?
In general, the Overpass API cannot know which bounding box you are looking at.
It is a feature of <a href="https://wiki.openstreetmap.org/wiki/Overpass_turbo">Overpass Turbo</a> to show a map in a viewport
and to replace each occurrence of <em>{{bbox}}</em> by the boundaries of that viewport.
In particular, the exact boundaries depend on screen resolution,
i.e. the request may have different results on different clients.
For my computer, the actual sent request is</p>
<pre>
node[amenity=restaurant](40.79456207284583,-73.97092580795288,40.80971663141517,-73.94957542419434);
out center;
</pre>
<p>or alternatively</p>
<pre>
[bbox:40.79456207284583,-73.97092580795288,40.80971663141517,-73.94957542419434];
node[amenity=restaurant];
out center;
</pre>

<p>The Global Bounding Box is even more useful when you are asking for the bounding box multiple times:</p>
<pre>
( node[amenity=restaurant]({{bbox}});
  way[amenity=restaurant]({{bbox}});
  rel[amenity=restaurant]({{bbox}}); );
out center;
</pre>
<p>This <a href="https://overpass-turbo.eu/s/ooL">is simplified to</a>:</p>
<pre>
[bbox:{{bbox}}];
( node[amenity=restaurant];
  way[amenity=restaurant];
  rel[amenity=restaurant]; );
out center;
</pre>

<h2 id="lonlat_bbox">The <em>bbox</em> Parameter</h2>

<p>For historical reasons, there is also another mechanism to set an initial bounding box everywhere.
It has been designed to simplify using the Overpass API from <a href="https://openlayers.org/">OpenLayers</a>.</p>

<p>You can amend a request with <em>bbox=west,south,east,north</em>.
The Overpass API then replaces each occurence of <em>(bbox)</em> within the request with the proper bounding box
and <em>[bbox]</em> in the beginning with the proper global bounding box.
This means that e.g. the following two requests are equal:</p>
<p><strong><a href="https://overpass-api.de/api/interpreter?data=node[amenity=restaurant](40.79456207284583,-73.97092580795288,40.80971663141517,-73.94957542419434);out+center;">https://overpass-api.de/api/interpreter?data=node[amenity=restaurant](40.79456207284583,-73.97092580795288,40.80971663141517,-73.94957542419434);out+center;</a></strong></p>
<p>and</p>
<p><strong><a href="https://overpass-api.de/api/interpreter?data=node[amenity=restaurant](bbox);out+center;&amp;bbox=-73.97092580795288,40.79456207284583,-73.94957542419434,40.80971663141517">https://overpass-api.de/api/interpreter?data=node[amenity=restaurant](bbox);out+center;&amp;bbox=-73.97092580795288,40.79456207284583,-73.94957542419434,40.80971663141517</a></strong></p>

<p>Please note that the coordinates in this parameter are swapped.
This is because OpenLayers violates <a href="https://en.wikipedia.org/wiki/ISO_6709">that latitude comes first</a> as opposed to most other software.
Because I did neither want to rewrite OpenLayers nor to bother users with that,
this special syntax allows use of the Overpass API with coordinate order swapped.</p>

<h2 id="geom_bbox">Output with Bounding Box</h2>

<p>Have you ever tried to keep track of recent changes in a bounding box?
It turns out that relations of large extents will often clutter up the results.</p>

<p>This is why you can add a bounding box to the <em>geom</em> mode of <a href="https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#Print_.28out.29">the <em>out</em> statement</a>.
Just change <em>geom</em> to <em>geom({{bbox}})</em>.
This restricts the added coordinates to the given bounding box.</p>

<p>For example, <a href="https://overpass-turbo.eu/s/ooO">the following request</a> loads most data outside of its viewport:</p>
<pre>
rel
  [type=route]
  [route=railway]
  ({{bbox}});
out geom;
</pre>
<p>If you <a href="https://overpass-turbo.eu/s/ooN">add the geometry limits</a>
then only data needed to visualize the relations in the viewport is loaded:</p>
<pre>
rel
  [type=route]
  [route=railway]
  ({{bbox}});
out geom({{bbox}});
</pre>

<p>In practice, this feature is useful only for relations.
Nodes are either inside or outside the bounding box.
For ways, you can drop some coordinates.
But because you will, also, get the other member entries without coordinates,
there is not much data you can avoid.
Only for relations can you drop the geometry of way members completely outside the bounding box.
But in tracking changes, usually only the large scale relations are the problem.</p>

<p>The global bounding box does not automatically add a limit to the <em>geometry</em> mode.
By contrast, the <em>bbox</em> parameter would trigger a replacement of <em>(bbox)</em> by the proper bounding box
if you have written <em>geom(bbox)</em> in the request.</p>

</body>
</html>