Overpass API >

Command line

Perform a Download

To download data (by hand or in a script) from Overpass API, you can use for example the well-known program wget. Alternatives are for example curl or, in case of FreeBSD, fetch. We assume here that you plan to use it in a script or other non-interactive way, because otherwise the query form might be a more convenient alternative.

The possible formats of the downloaded file are described on the output formats page.

For short queries, the usage is very simple: Just write the query in the command line:

wget "http://overpass-api.de/api/interpreter?data=node[name=\"Gielgen\"];out;"

Please note that we need to escape the quotation mark ("). Because we have enclosed the URL in quotation marks, we must escape only two more characters: the dollar ($) sign should get (\$) and the backslash (\) should be doubled (\\).

In most cases it would be helpful to store the results with a meaningful filename. Use -O for that purpose:

wget -O target.osm "http://overpass-api.de/api/interpreter?data=node[name=\"Gielgen\"];out;"

For longer queries, it could be helpful to have the query in a separate file. That is also possible:

echo "data=node[name=\"Gielgen\"];out;" >query.osm
wget -O target.osm --post-file=query.osm "http://overpass-api.de/api/interpreter"

A subtle detail you may have recognized in the last example is the prefix data=. This can be omitted, but has slightly different meaning: If the data= prefix is present, then Overpass API assumes the query behind this prefix is URL encoded. This is what usually happens when it comes from a HTML form and sometimes by some HTTP clients. If you omit the prefix, Overpass API takes the data to be verbatim and does no URL deocding.

HTTP methods and headers

Overpass API accepts both HTTP GET and HTTP POST requests. Both are handled as similar as possible, so we treat them together. Additionally, Overpass API handles HTTP OPTIONS requests. We explain the details in the last paragraph.

If an HTTP Origin header is sent, the response always contains the header

Access-Control-Allow-Origin: *

regardless of other properties of the query. This is to allow HTTP cross-origin sharing, especially for JavaScript executed in a browser as a client.

For HTTP GET and POST, no other headers affect the behaviour of Overpass API. If the string data= is present in the request, the query is assumed to be the substring between data= and the next literal "&". Overpass API will URL decode this string, but also will keep all not encoded characters verbatim. Thus, a verbatim request behaves exactly the same like an URL encoded request. If no string data= is present, then the whole query string is assumed to be the query and taken verbatim.

Overpass API may return on GET or POST requests the HTTP status codes 200, 302, 400, or 504. We explain all more detailed.

200 OK is sent when the query has been successfully answered. The payload of the response is the result data. The possible formats are described on the output formats page.

302 Moved is only relevant in the context of the permanent id feature. It is the status code for the redirection to the corresponding main API page. No payload is sent in this case.

400 Bad Request 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 HTTP standard requires such a payload, some HTTP clients, notably wget ignore the payload. Please try then curl or your favourite browser.

429 Too Many Requests 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 /api/kill_my_queries.

504 Gateway Timeout 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 timeout and maxsize parameters of the request, so smaller values for them may also make the request acceptable.

Overpass API handles the HTTP OPTIONS method to implement the server part of CORS. This is relevant only for the nonetheless important use case to access Overpass API from the JavaScript of another website executed in the browser. The response to the HTTP OPTIONS consists always only of headers: If the HTTP header Request-Method is set by the client, Overpass API contains the header

Access-Control-Allow-Methods: GET, POST, OPTIONS

in the response. If the HTTP header Request-Headers is set by the client, all the header names there are echoed in the response at the then included HTTP header Access-Control-Allow-Headers. POST requests don't get any more details in their response, GET requests may see a 400 Bad Request response if there is a syntax error in the request. This discrimination sounds a little bit odd, but is explicity required by the HTTP 1.1 standard: for GET requests, the whole request is part of the URL; for POST requests, the Overpass QL script is not part of the URL.