User talk:Sanderd17/OverpassQLTutorial

From OpenStreetMap Wiki
Jump to: navigation, search

This page will try to guide you around the basics of the Overpass QL language. It is important that you know the primitive elements in OpenStreetMap, as the Overpass keywords are based on these elements.

Background and concepts

Overpass QL is a query language. This means you can use it to extract a certain selection out of the OpenStreetMap database for further usage. Overpass further also offers formatting the output in various formats which can be useful for different tools.

Overpass API can filter by the following criteria:

  • Geographical location (inside a bounding box, a polygon, close to some feature, ...)
  • Tags (exact matching tags, tags matching by regular expression, ...)
  • Metadata (date modified, last edited by a certain user, ...)
  • Relation to other elements (member of a relation, node in a way, ...)

This tutorial specifically handles the QL syntax, overpass also offers an XML syntax but that's not handled here. The QL syntax resembles well known programming languages (mainly C and all derivates), so should be easier to understand for someone with basic programming knowledge.

Overpass API and Overpass Turbo

Overpass Turbo is a web editor build around Overpass API. In particular, Overpass Turbo makes it easier to develop queries as you can view results immediately on a slippy map, and Overpass Turbo also has extra features such as a wizard to help you build queries, correct syntax highlighting, or styling options.

Overpass Turbo also adds a few extra features to the syntax which will be documented here.

Because Overpass Turbo loads the results directly in your browser, it is not suited to run big queries. If you need to run big queries, you can develop the query using Overpass Turbo, and then use the query in a direct Overpass API call. Overpass Turbo will generally warn you when the results are too big.

This tutorial includes links to Overpass Turbo, where you can test queries. Click on the Overpass-turbo.png button to try the query. Don't forget to click on the "run" button to actually execute the query.

Hello world!

Let's start as with about every programming tutorial: a "hello world" program:

try it yourself in overpass-turbo

The program above includes the two most important parts of a query. The first line is the filter. In this case, it filters out all nodes with a name "Helloworld" in the entire world. The second line is the output command, where you choose which data to output. The default out; command just outputs the results from the previous filter.

Filtering by location

Of course, we're lucky that there are only few nodes with "Helloworld" as a name. Often, we don't want to find worldwide features with a very specific tag, but we want to find more generic features, and limited to a certain location. Say you want all pubs in a certain bounding box. For that, we can add a filter to the line.

try it yourself in overpass-turbo

The bounding box syntax uses the (south,west,north,east) order of arguments.

 Note: In Overpass turbo, you can use the (bbox={{{minlon}}},{{{minlat}}},{{{maxlon}}},{{{maxlat}}}) variable. This value will be replaced by the bounding box of your visible map when running. It is ideal to test queries on smaller areas, but Overpass API isn't able to parse this directly.