Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Doc cleanup: fix API URLs & mention JSON area date #711

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Doc cleanup: fix API URLs & mention JSON area date #711

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
27c2d80
Specify server in URLs of all API examples
mikini Nov 6, 2023
10783d8
Fix typo in HTML anchor reference to XML date
mikini Nov 6, 2023
8d8ecb6
Mention the JSON area timestamp
mikini Nov 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/html/command_line.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ <h2><a name="headers">HTTP methods and headers</a></h2>

<p><strong>400 Bad Request</strong> is sent if the request has a syntax error. In this case the payload contains a HTML document describing what is wrong with the request. Please note that although the <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4">HTTP standard</a> requires such a payload, some HTTP clients, notably <em>wget</em> ignore the payload. Please try then <em>curl</em> or your favourite browser.</p>

<p><strong>429 Too Many Requests</strong> is sent if you pass multiple queries from one IP. This is a fair use policy to avoid that a single user uses up all server resources. If you want to terminate the runaway query that prevents you from sending other queries, you can surf to <a href="/api/kill_my_queries">/api/kill_my_queries</a>.</p>
<p><strong>429 Too Many Requests</strong> is sent if you pass multiple queries from one IP. This is a fair use policy to avoid that a single user uses up all server resources. If you want to terminate the runaway query that prevents you from sending other queries, you can surf to <a href="//overpass-api.de/api/kill_my_queries">/api/kill_my_queries</a>.</p>

<p><strong>504 Gateway Timeout</strong> is sent if the server has already so much load that the request cannot be executed. In most cases, it is best to try again later. Please note that the server decides this based on the <a href="https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#timeout">timeout</a> and <a href="https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL#element-limit">maxsize</a> parameters of the request, so smaller values for them may also make the request acceptable.</p>

Expand Down
27 changes: 17 additions & 10 deletions src/html/output_formats.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ <h2><a name="xml">OSM XML</a></h2>

<p>The format generally follows the <a href="https://wiki.openstreetmap.org/wiki/XML">description in the wiki</a>. It doesn't contain a <em>bounds</em> tag, and it may contain certain additional tags. Anyway, in all cases <a href="https://www.w3.org/TR/REC-xml/">well-formed XML</a> is returned.</p>

<p>A response (<a href="api/interpreter?data=out;">an example</a>) from Overpass API has always the following header and footer:</p>
<p>A response (<a href="//overpass-api.de/api/interpreter?data=out;">an example</a>) from Overpass API has always the following header and footer:</p>
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;osm version=&quot;0.6&quot; generator=&quot;Overpass API&quot;&gt;
Expand Down Expand Up @@ -70,10 +70,10 @@ <h2><a name="json">OSM JSON</a></h2>

<p>To get a response in format JSON, start the request with a <em>[out:json]</em> directive, for example:</p>
<pre>
<a href="api/interpreter?data=[out:json];out;">/api/interpreter?data=<strong>[out:json];</strong>out;</a>
<a href="//overpass-api.de/api/interpreter?data=[out:json];out;">/api/interpreter?data=<strong>[out:json];</strong>out;</a>
</pre>

<p>A response (<a href="api/interpreter?data=[out:json];out;">an example</a>) from Overpass API always has the following header and footer:</p>
<p>A response (<a href="//overpass-api.de/api/interpreter?data=[out:json];out;">an example</a>) from Overpass API always has the following header and footer:</p>
<pre>
{
&quot;version&quot;: 0.6,
Expand All @@ -89,7 +89,14 @@ <h2><a name="json">OSM JSON</a></h2>
]
}
</pre>
<p>The payload is contained between the brackets after <em>elements</em>. Each element is contained in a pair of curly braces, and two elements are separate by a comma. The <em>date</em> is constructed in the same way as for the <a href="#xml.data">XML format</a>.</p>
<p>The payload is contained between the brackets after <em>elements</em>. Each element is contained in a pair of curly braces, and two elements are separate by a comma.</p>

<p>As with XML, if a query involves areas a second timestamp is included, here as another property of the <em>osm3s</em> object with key <em>timestamp_areas_base</em>:</p>
<pre>
&quot;timestamp_areas_base&quot;: &quot;<em>date</em>&quot;,
</pre>

<p>The <em>date</em> value of both timestamp properties are constructed in the same way as for the <a href="#xml.date">XML format</a>.</p>

<p>We discuss the <em>node</em> representation (and <a href="#json.way">further down</a> the representations of
<em>way</em>s and <em>relation</em>s) by examples:</p>
Expand Down Expand Up @@ -194,19 +201,19 @@ <h2><a name="custom">Custom output and Redirects</a></h2>

<p>The simplest variant is the redirect with potential disambiguation page. We give two examples:</p>
<ul>
<li><a href="api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%22A%20555%22%5D%5B%22network%22%3D%22BAB%22%5D%3Bout%3B">/api/interpreter?data=<strong>[out:custom];</strong>rel[ref=&quot;A 555&quot;][network=BAB];out;</a> (at the moment without disambiguation page).</li>
<li><a href="api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%2263%22%5D%5B%22network%22%3D%22VRS%22%5D%3Bout%3B">/api/interpreter?data=<strong>[out:custom];</strong>rel[ref=63][network=VRS];out;</a> (with disambiguation page).</li>
<li><a href="//overpass-api.de/api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%22A%20555%22%5D%5B%22network%22%3D%22BAB%22%5D%3Bout%3B">/api/interpreter?data=<strong>[out:custom];</strong>rel[ref=&quot;A 555&quot;][network=BAB];out;</a> (at the moment without disambiguation page).</li>
<li><a href="//overpass-api.de/api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%2263%22%5D%5B%22network%22%3D%22VRS%22%5D%3Bout%3B">/api/interpreter?data=<strong>[out:custom];</strong>rel[ref=63][network=VRS];out;</a> (with disambiguation page).</li>
</ul>
<p>In the first example, no disambiguation is necessary because the search criteria describe an unique object. In the second example, three objects exist and do so for good reason. Thus, a disambiguation page is necessary and therefore displayed.</p>

<p>If you want always a disambiguation page, you can add the directive <em>redirect=no</em> to the end. This forces a disambiguation page to be displayed:</p>
<ul>
<li><a href="api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%22A%20555%22%5D%5B%22network%22%3D%22BAB%22%5D%3Bout%3B&amp;redirect=no">/api/interpreter?data=[out:custom];rel[ref=&quot;A 555&quot;][network=BAB];out;<strong>&amp;redirect=no</strong></a> (at the moment without disambiguation page).</li>
<li><a href="//overpass-api.de/api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%22A%20555%22%5D%5B%22network%22%3D%22BAB%22%5D%3Bout%3B&amp;redirect=no">/api/interpreter?data=[out:custom];rel[ref=&quot;A 555&quot;][network=BAB];out;<strong>&amp;redirect=no</strong></a> (at the moment without disambiguation page).</li>
</ul>

<p>You can of course also change the destination URL. Add <em>url=</em>something to the end. For example, we replace the element view on the main database by a full map view in the above query:</p>
<ul>
<li><a href="api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%22A%20555%22%5D%5B%22network%22%3D%22BAB%22%5D%3Bout%3B&amp;url=https://www.openstreetmap.org/?{{{type}}}={{{id}}}">/api/interpreter?data=[out:custom];rel[ref=&quot;A 555&quot;][network=BAB];out;<strong>&amp;url=https://www.openstreetmap.org/?{{{type}}}={{{id}}}</strong></a> (at the moment without disambiguation page).</li>
<li><a href="//overpass-api.de/api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%22A%20555%22%5D%5B%22network%22%3D%22BAB%22%5D%3Bout%3B&amp;url=https://www.openstreetmap.org/?{{{type}}}={{{id}}}">/api/interpreter?data=[out:custom];rel[ref=&quot;A 555&quot;][network=BAB];out;<strong>&amp;url=https://www.openstreetmap.org/?{{{type}}}={{{id}}}</strong></a> (at the moment without disambiguation page).</li>
</ul>
<p>Note that the URL usually depends on the id and the type of the found results. To customize this, you can add the placeholders <em>{{{type}}}</em> and <em>{{{id}}}</em> anywhere in the URL; these will be replaced by the proper type (<em>node</em>, <em>way</em> or <em>relation</em>) and the id of the found object.</p>

Expand All @@ -217,8 +224,8 @@ <h2><a name="custom">Custom output and Redirects</a></h2>
</ul>
<p>By default, <em>default.wiki</em> is used as template. To select another template, for example the just introduced <em>base.wiki</em>, use the <em>template=</em>something directive. Please compare:</p>
<ul>
<li><a href="api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%2263%22%5D%5B%22network%22%3D%22VRS%22%5D%3Bout%3B&amp;template=default.wiki">/api/interpreter?data=<strong>[out:custom];</strong>rel[ref=63][network=VRS];out;<strong>&amp;template=default.wiki</strong></a> (same as without template parameter).</li>
<li><a href="api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%2263%22%5D%5B%22network%22%3D%22VRS%22%5D%3Bout%3B&amp;template=base.wiki">/api/interpreter?data=<strong>[out:custom];</strong>rel[ref=63][network=VRS];out;<strong>&amp;template=base.wiki</strong></a> (use the basic layout instead).</li>
<li><a href="//overpass-api.de/api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%2263%22%5D%5B%22network%22%3D%22VRS%22%5D%3Bout%3B&amp;template=default.wiki">/api/interpreter?data=<strong>[out:custom];</strong>rel[ref=63][network=VRS];out;<strong>&amp;template=default.wiki</strong></a> (same as without template parameter).</li>
<li><a href="//overpass-api.de/api/interpreter?data=%5Bout%3Acustom%5D%3Brelation%5B%22ref%22%3D%2263%22%5D%5B%22network%22%3D%22VRS%22%5D%3Bout%3B&amp;template=base.wiki">/api/interpreter?data=<strong>[out:custom];</strong>rel[ref=63][network=VRS];out;<strong>&amp;template=base.wiki</strong></a> (use the basic layout instead).</li>
</ul>
<p>Technically, the template is taken from the subdirectory <em>templates</em> of the database directory of the server. For the public instances, there exist also a mechanism to upload a completetly custom template from the wiki to this directory. The upload mechanism is explained on <a href="https://wiki.openstreetmap.org/Overpass_API/Permanent_ID">the Wiki employment page</a>. The syntax of the template page is explained in the following:</p>

Expand Down