Getting Started

1. Introduction

The 02Agent OSM Downloader is a QGIS Processing plugin providing four QGIS Processing algorithms for structured acquisition of OpenStreetMap (OSM) vector data via the Overpass API. Operating entirely within QGIS's native processing framework, the plugin translates user-specified thematic presets, custom key/value tags, or advanced multi-tag Boolean queries into bounded Overpass QL requests, automatically assembles multipolygon relations, transforms coordinates, and delivers three stratified output layers (points, lines, polygons).

OpenStreetMap represents the largest and most widely used volunteered geographic information (VGI) repository, containing over 10 billion geospatial elements as of 2026. The Overpass API provides a read-optimised query interface for selective OSM data extraction, enabling urban morphologists, transport planners, and environmental researchers to acquire domain-specific geospatial datasets without processing the entire planet file. This plugin formalises that acquisition into a reproducible, parameterised QGIS algorithm suite with stringent security and resource bounds.

The plugin does not accept raw query text, arbitrary URLs, file paths, API keys, shell commands, or external interpreter invocations. All Overpass QL is constructed internally from typed parameters via the shared core/query.py module, ensuring every request is syntactically bounded and free of injection vectors. This design satisfies the QGIS Hub security gate requirements (Bandit, detect-secrets) while remaining compatible with Qt6 / QGIS 4 environments.

1.1 Dock Workflows

The dock has four tabs: Presets, Query, Command, and Agent. The bottom run card is contextual: it is visible for Presets and Query, and hidden while the Agent connection panel is active.

Theme and multi-dataset selection

Choose a Theme first. The Presets tab shows a theme focus and related contexts before selection. Its Dataset list is checkable, so multiple datasets can be selected within the same theme—for example, Bus transit and Rail transit. The checked datasets are flattened into one validated TagSpec collection, duplicate selectors are removed, and one Overpass request produces the point, line, and polygon outputs. The selected dataset IDs remain visible in the output preset_id field, joined with a plus sign.

Urban Context is deliberately cross-disciplinary: its public-transport context includes bus stops, stop positions, platforms, stations, entrances and mapped bus or tram routes; its public-realm context includes crossings, signals, street lighting, benches, bicycle parking, drinking water, waste baskets, toilets, cafes and restaurants. The dedicated Public Transport theme provides the same transit domain when a narrower transport-only request is preferred.

The selection row reports n of m selected. Use Select all to build a broad context request or Clear to start over. Clearing the list is safe: no network request is sent until Download is pressed.

Structured Query workspace

The Query tab provides four bounded key/value rows. Key and value fields offer common OSM suggestions, the live counter shows how many rows are populated, and Clear filters resets the form. Load example supplies ready-to-edit patterns for accessibility, transit, healthcare, parks, waterways, historic features, pedestrian streets, electric charging, and building metadata. The read-only Overpass preview remains collapsed until Show preview is pressed.

Command workspace

Global command examples. The Load example menu includes named places from multiple regions so the parser can be tested with cities, districts and administrative names beyond one local dataset.

The Command tab accepts English dataset requests, safe key=value commands, and place-aware phrases. Examples include Download parks in London, Download public transport in Van, Download public transport in Tokyo, Download buildings in New York City, and London. After interpretation, review the checked Dataset list and the resolved place label before pressing Download. Command text is interpreted locally; only the explicit download operation performs a network request.

When a place-aware command is interpreted, the place resolver runs in a background QGIS task. Once a candidate is found, the map canvas automatically zooms to its administrative bounding box and the resolved label is shown in the dock. If the preview lookup is unavailable, the download action retries the same bounded lookup through the normal mirror-failover path.

Basemap and road hierarchy

Add OSM basemap adds one standard OpenStreetMap XYZ layer to the current project, marks it with duplicate protection and records the required attribution metadata. Repeated clicks reveal the existing layer instead of adding another copy. The Run card also offers By OSM highway category (the default) or Uniform road width. Category mode assigns a visual hierarchy to motorway/trunk, primary, secondary, tertiary, residential and service roads; the choice is stored in QGIS settings and applied to newly downloaded line layers.

1.2 Named Places

Place-aware commands use the download_place endpoint. The typed name is normalised and escaped as data, then sent to the same pinned Overpass mirrors used by ordinary downloads. The lookup searches administrative relations and ways plus named place=* nodes across common OSM name fields: name, official_name, alt_name, name:en, name:tr, and int_name.

Candidates are ranked by exact name match, administrative boundary type, administrative level, and available parent context. Thus a short command such as Konak can resolve to the OSM administrative Konak relation, while a fuller phrase such as Izmir Konak can use the final name token and retain the supplied parent context in the displayed label. The resolved bounding box is then used for the selected datasets. The normal 100 km² limit still applies; a large result such as London may need to be narrowed before download.

1.3 Reliability and Recovery

Downloads use three pinned HTTPS Overpass mirrors. The plugin tries them in order, records the response from each attempt, and reports the active mirror, HTTP status and failure reason in the QGIS message bar and Processing feedback. If one mirror is busy or unavailable, the next mirror is tried automatically.

2. System Architecture

The plugin follows a layered architecture with strict separation of concerns:

1. Presentation layer — QGIS Processing parameter widgets (preset multi-select preset enum, extent selector, tag key/value text fields, geometry type enum) defined in osm_algorithms.py via the initAlgorithm() methods of each algorithm subclass.
2. Authority boundary — core/query.py and core/catalog.py, and core/places.py are shared between the Processing provider, the optional plugin dock widget, and the agent manifest. All query construction, tag normalisation, and validation flows through these modules; no other code path synthesises Overpass QL.
3. Network layer — Three pinned Overpass endpoints with sequential failover with per-mirror status diagnostics. Requests use QgsBlockingNetworkRequest's POST method with application/x-www-form-urlencoded encoding and Accept: application/json. The User-Agent identifies the plugin version and GitHub repository.
4. Geometry layer — Coordinate extraction, multipolygon ring assembly, unary union, difference, and CRS transformation. All geometry is constructed using QGIS native geometry classes (QgsGeometry, QgsPointXY, QgsCoordinateTransform).
5. Cache layer — Thread-safe in-session dictionary with TTL-based expiration and LRU eviction (8 entries, 15-minute TTL). Cached by raw query string to avoid redundant network requests during iterative analysis.

where \(Q(P)\) is the query builder function, \(i\) iterates over the three failover endpoints, \(\Phi\) is the kind classifier, \(\Gamma\) the geometry constructor, and \(\Pi\) the CRS projector.

2.1 Processing Provider

The AgentOsmProvider (provider ID: zero2agentosm) registers four algorithms under the group "OSM acquisition" with group ID osm_acquisition. The provider icon is loaded from icons/icon.png relative to the plugin root. Each algorithm is instantiated fresh via createInstance(), ensuring QGIS can configure parallel algorithm runs with independent parameter state.

2.2 Network Endpoints

The failover strategy is sequential, not parallel: if the primary endpoint (overpass-api.de) fails due to network error or non-2xx HTTP status, the second is attempted, then the third. Only if all three fail is an exception raised. A successful response from any endpoint is cached and returned immediately, skipping remaining mirrors.

3. OpenStreetMap Data Primitives

The OpenStreetMap data model comprises three fundamental geometric primitives, each identified by a unique 64-bit integer ID and augmented with a set of key-value tags (Mooney & Corcoran, 2012):

3.1 Nodes

A node is a single geospatial point defined by a (longitude, latitude) coordinate pair in the WGS84 (EPSG:4326) datum. Nodes may represent features themselves (e.g., a bus stop, a tree, a traffic signal) or serve as vertices that define the geometry of ways. In this plugin, nodes are always mapped to the point output layer.

3.2 Ways

A way is an ordered list of node references. An open way (where the first and last nodes differ) represents a linear feature such as a road, footpath, waterway, or barrier. A closed way (where the first and last nodes are identical and there are at least three distinct nodes) may represent either a linear feature that happens to form a loop or an area feature such as a building footprint, park, or water body. Classification depends on the element's tags and the tag specifications provided by the user.

3.3 Relations

A relation is an ordered collection of members—nodes, ways, or other relations—each assigned a role string (commonly "outer" or "inner" for multipolygon relations). Relations model complex geographic features: multipolygons with holes, bus routes, turn restrictions, and administrative boundaries. This plugin implements a multipolygon assembly algorithm (Section 7) to reconstruct area geometries from fragmented relation members.

where element geometry \(geom_e\) is a point coordinate pair for nodes, an ordered vertex sequence for ways, and a structured member list with role annotations for relations.

4. Overpass Query Language

Overpass QL is a declarative, block-structured query language for the Overpass API, a read-only OSM data extraction service. Queries consist of an output format declaration, optional timeout, a parenthesised statement block, and an output directive (Olbricht, 2021).

4.1 Formal Grammar

The subset of Overpass QL generated by this plugin obeys the following formal grammar in extended Backus-Naur form:

where each coordinate is rendered to 7 decimal places (approximately 1 cm precision at the equator), and the output format is always JSON. No CSV, XML, or interactive endpoints are used.

4.2 Query Construction Algorithm

In any match mode, each tag specification generates one or two selector statements depending on its geometry kind:

• Point specs → node[...](bbox);
• Line specs → way[...](bbox);
• Polygon specs → way[...](bbox); + relation[...](bbox);

Duplicate selectors are removed via dictionary ordering (dict.fromkeys). In all match mode, selectors are grouped by geometry kind, and all tag selectors for that geometry are concatenated onto a single primitive statement, expressing an AND conjunction at the Overpass level.

where \(S_g = \{\sigma \in S \mid \sigma.\!geom = g\}\) and \(k = |S_g|\).

5. Tag Matching Semantics

Tag matching is performed client-side after the Overpass response is received. While Overpass QL supports tag-based filtering at the server, this plugin additionally filters responses to handle geometry-kind disambiguation (ways that could be either lines or polygons) and to support AND-mode conjunctions that may not have been fully expressible in a single Overpass query.

5.1 Matching Function

Given an OSM element's tag dictionary \(t : K \rightharpoonup V\) and a set of tag specifications \(S_g\) for a particular geometry kind \(g\), the matching function \(\mu\) is defined as:

where \(\varepsilon\) denotes the empty string (meaning "any value for this key"). A tag specification with an empty value matches any element possessing that key, regardless of its value.

5.2 Geometry Kind Classification

Element classification into output layers follows a precedence rule:

1. Nodes → always classified as point if they match at least one point-tagged specification.
2. Relations → always classified as polygon if they match at least one polygon-tagged specification.
3. Ways → checked against both line and polygon specifications. If only one geometry kind matches, that kind is selected. If both match, the way is classified as polygon if and only if its vertex sequence forms a closed ring (first coordinate equals last); otherwise, it is classified as line.

where \(\text{closed}(geom_e)\) is true when the way's first and last coordinates are equal and the ring has at least 4 points (3 distinct vertices plus the closure).

6. Cache Architecture

The plugin implements an in-session, in-memory response cache to minimise redundant Overpass API calls during iterative QGIS workflows. The cache is thread-safe, bound, and temporally limited.

6.1 Cache Structure

Each cache entry associates a raw query string key with a tuple of (monotonic timestamp, validated JSON payload). The timestamp uses time.monotonic() to remain unaffected by system clock adjustments.

6.2 Eviction Policy

Two independent policies govern cache eviction:

1. TTL expiration (time-based): On read, if the entry's age exceeds \(T_{\text{cache}}\), it is removed and the lookup proceeds to a network request. This ensures stale data does not persist across long analysis sessions.
2. LRU eviction (space-based): On write, if the cache has reached \(C_{\max}\) entries, the entry with the earliest monotonic timestamp is evicted. The monotonic counter ensures stable ordering even if cache entries have identical ages.

6.3 Thread Safety

All cache operations are guarded by a single threading.RLock(), allowing re-entrant access from the same thread while preventing data races from concurrent QGIS algorithm executions. TTL expiry checks and evictions occur within the critical section, ensuring atomic read-modify operations.

7. Multipolygon Assembly Algorithm

Overpass API returns relation members as discrete way fragments with independent geometry—a multipolygon representing a building with a courtyard may appear as four separate open ways for the outer shell and two for the inner hole. Treating each member as a standalone polygon silently drops these features. The _member_rings() function reconstructs closed rings by joining fragments at shared endpoints.

7.1 Algorithm

Phase 1 (Indexing): Collect all way-type members matching the target role ("outer" or "inner"). Build an endpoint dictionary mapping each (x, y) coordinate pair to the list of segment indices that begin or end there.

Phase 2 (Chaining): While unused segment indices remain, pop one segment to start a new chain. At each step, attempt to find a segment whose endpoint matches the chain's current open end. If a match is found, extend the chain with appropriate orientation (forward if endpoints match head-to-tail, reversed otherwise). If no match exists at the chain end, attempt the chain start. If neither finds a neighbour, the chain is closed and added to the ring set.

Phase 3 (Validation): Rings with fewer than 4 points (3 distinct vertices plus closure) are discarded. Only rings where \(p_0 = p_{n-1}\) are retained.

7.2 Relation Polygon Assembly

After ring assembly, outer rings are unioned via QgsGeometry.unaryUnion() to handle multi-part outer boundaries (e.g., a land-use area split by a road). Inner rings are similarly unioned, then subtracted from the outer union via QgsGeometry.difference() to create holes. The result is converted to MultiPolygon type via convertToMultiType() before being stored.

8. CRS Transformation

All OSM data is natively in WGS84 (EPSG:4326), a geographic coordinate system using latitude and longitude in decimal degrees. QGIS projects, however, commonly use projected coordinate systems (e.g., UTM zones, national grids) in linear units (metres) for distance and area calculations. The plugin performs automatic coordinate transformation:

1. Extent transformation (input): The user-selected download extent, which may be in any CRS, is transformed to WGS84 for Overpass query bounding box construction.
2. Geometry transformation (output): Each feature geometry constructed from WGS84 coordinates is transformed to the output CRS (the extent's CRS, or the project CRS as fallback).

8.1 Affine Formulation

While QGIS implements full datum transformations using PROJ pipelines (including grid-shift files for high-accuracy transforms), the fundamental operation for point coordinates under a linearised approximation is:

where \(\mathbf{A}\) is the Jacobian of the map projection at the centroid of the extent, and \(\mathbf{t}\) is a translation vector. For Bursa-Wolf datum transformations, the full 7-parameter Helmert transformation is used internally by PROJ.

9. Extent Validation

9.1 Bounding Box Constraints

The validate_bbox() function enforces geographic and resource constraints on the download extent:

The constant 111.32 km/degree is the approximate length of one degree of latitude (or one degree of longitude at the equator). The cosine factor accounts for meridian convergence at higher latitudes. The lower bound of 0.01 on the cosine prevents degenerate behaviour near the poles.

9.2 Haversine Distance

While the plugin uses the simplified rectangular approximation above for area estimation (sufficient for the 100 km² extent gate), the theoretically correct great-circle distance between two WGS84 points is given by the Haversine formula:

where \(\phi_1, \phi_2\) are latitudes in radians, \(\Delta\phi = \phi_2 - \phi_1\), \(\Delta\lambda = \lambda_2 - \lambda_1\), and \(R\) is the Earth's mean radius.

10. Algorithm 1: Download Curated OSM Thematic Preset

Algorithm ID: download_preset
Display name: Download curated OSM thematic preset
Group: OSM acquisition

10.1 Theoretical Background

Thematic preset downloads operationalise the concept of curated OSM knowledge schemas—predefined collections of OSM key/value/geometry triples organised by analytical domain. In VGI research, the absence of a fixed data schema is both a strength (enabling community-driven tagging) and a challenge (requiring domain expertise to identify relevant tags). Preset catalogues bridge this gap by encoding expert knowledge of OSM's emergent tag ontology (Mooney & Corcoran, 2012; Barrington-Leigh & Millard-Ball, 2017).

Each preset bundles a set of TagSpec objects—(key, value, geometry_kind) triples—under a thematic group. The Urban Context preset, for example, selects highways (lines), buildings (polygons), trees (points), and tree rows (lines) to provide a comprehensive base map for urban morphology analysis. The Green-blue system preset combines parks, forests, woods, water bodies, waterways, and coastlines for ecological network analysis.

The presets operate in any (OR) match mode: an element is selected if it matches any single TagSpec. This yields inclusive, broad-coverage downloads suitable for initial exploration and base map construction.

10.1.1 Preset Selection as Indexed Retrieval

Formally, each preset \(p \in \mathcal{P}\) is a tuple containing a unique identifier, thematic group, and an ordered tuple of tag specifications. The preset selection parameter is a non-empty index set \(I \subseteq \{0, \ldots, |\mathcal{P}|-1\}\) containing one or more datasets from this catalogue:

where the total number of tag selectors across all presets is \(\sum_{j=0}^{27} m_j\) and each individual preset satisfies \(1 \leq m_j \leq 32\) (the MAX_SELECTORS bound enforced by normalized_specs()).

10.1.2 Geometry Projection and Selector Expansion

The Overpass query generated from a preset's tag specifications expands each TagSpec into one or two Overpass selector statements depending on the geometry kind. The mapping from TagSpec tuple to Overpass QL selector set is:

The expansion factor \(\rho = |\psi_{\text{preset}}| / m_j\) satisfies \(1 \leq \rho \leq 2\), with \(\rho = 2\) occurring when all specifications are polygon-kind (each generating both a way and a relation selector). After deduplication via dict.fromkeys(), the number of unique selectors may be less than the raw expansion product.

10.1.3 Preset Execution and Element Yield

For a selected preset index set \(I\), extent \(e\), and output CRS \(c\), the expected element yield is governed by OSM feature density within the extent. The classification function \(\kappa\) (discussed in Section 5) partitions elements into the three output layers:

where \(E_{\text{query}}\) is the set of elements returned by the Overpass query, \(\kappa\) is the kind classifier, and \(\gamma\) is the geometry constructor. The inequality reflects that some elements may be discarded if their geometry fails to construct (empty or invalid).

The preset catalogue spans 30 presets across 15 thematic groups (urban context, networks, morphology, green-blue infrastructure, public transport, religious facilities, tourism, sport, cycling, automotive, traffic, health, education, emergency services, and named places), providing coverage for the most common GIS analytical workflows in urban planning, transport engineering, and environmental science.

10.1.4 OSM Tag Ontology and Preset Design

OSM's tagging system is a folksonomy: a collaboratively maintained, unstructured vocabulary that has converged toward a de facto standard through community conventions documented on the OSM Wiki. The preset catalogue reflects this convergence. Each preset's tag set is sourced from established OSM tagging conventions and has been validated against real-world data availability. Tags use the standard OSM key format (^[A-Za-z0-9_:.~-]{1,80}$) and values optionally specify particular OSM value strings (e.g., "highway"="bus_stop"), with empty value strings indicating wildcard matching for that key.

10.2 Parameters

10.3 Outputs

All four algorithms produce identical output schemas. Each output layer contains the following 22 fields (all of type QString):

All 22 fields are of type QString (QMetaType.Type.QString). The tags_json field is compacted to approximately 16 KB maximum; if the full tag set exceeds this limit, the JSON object is truncated with a _truncated: true sentinel key.

10.4 Interpretation Guidance

• Data completeness: OSM coverage varies geographically. Urban areas in Europe and North America typically have near-complete building footprints and road networks, while coverage in developing regions may be sparse (Haklay, 2010; Barrington-Leigh & Millard-Ball, 2017).
• Tagging consistency: Different contributors may apply different tag combinations for the same real-world feature. The matched_tags field records only the tags that triggered the match, while tags_json preserves the full tag set for post-hoc analysis.
• Duplicate geometry: A single real-world feature may appear in multiple output layers (e.g., a building tagged with both building=yes and amenity=school would appear as a polygon in both the Buildings and Education presets if downloaded separately). The osm_id field enables cross-layer deduplication.
• Extent limits: The 100 km² maximum extent is designed to keep response sizes manageable and respect Overpass API fair-use policies. For larger areas, download multiple adjacent extents and merge.

10.4.1 References

1. Goodchild, M.F. (2007). Citizens as sensors: the world of volunteered geography. GeoJournal, 69(4), 211-221. DOI: 10.1007/s10708-007-9111-y
2. Haklay, M. (2010). How good is volunteered geographical information? A comparative study of OpenStreetMap and Ordnance Survey datasets. Environment and Planning B: Planning and Design, 37(4), 682-703. DOI: 10.1068/b35097
3. Mooney, P. & Corcoran, P. (2012). Characteristics of heavily edited objects in OpenStreetMap. Future Internet, 4(4), 880-906. DOI: 10.3390/fi4030880
4. Barrington-Leigh, C. & Millard-Ball, A. (2017). The world's user-generated road map is more than 80% complete. PLOS ONE, 12(8), e0180698. DOI: 10.1371/journal.pone.0171362
5. Neis, P. & Zipf, A. (2012). Analyzing the contributor activity of a volunteered geographic information project — the case of OpenStreetMap. ISPRS International Journal of Geo-Information, 1(2), 146-165. DOI: 10.3390/fi4030880
6. Boeing, G. (2017). OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks. Computers, Environment and Urban Systems, 65, 126-139. DOI: 10.1016/j.compenvurbsys.2017.05.004
7. Haklay, M. & Weber, P. (2008). OpenStreetMap: User-generated street maps. IEEE Pervasive Computing, 7(4), 12-18. DOI: 10.1145/1463434.1463442
8. Schmidt, M. & Weiser, P. (2010). OpenStreetMap data quality — assessment and assurance. IEEE Computer, 43(12), 94-97. DOI: 10.1109/MC.2010.21

11. Algorithm 2: Download Custom OSM Key/Value Tag

Algorithm ID: download_custom_tag
Display name: Download custom OSM key/value tag
Group: OSM acquisition

11.1 Theoretical Background

The custom tag algorithm provides direct access to OSM's full tag space without requiring a pre-defined preset. This supports exploratory VGI analysis: researchers investigating tag adoption patterns, data completeness for niche features, or the spatial distribution of any key or key/value combination across a study area.

The algorithm accepts a single OSM key (required) and an optional value. An empty or wildcard (*) value matches any element possessing that key regardless of its associated value. The user selects a target geometry type (Point, Line, or Polygon), which constrains the Overpass query to the relevant OSM primitive and the post-query classification to the chosen geometry kind.

11.1.1 Tag Normalization Function

The normalize_tag() function maps raw user input strings to a safe, bounded key/value pair suitable for Overpass QL embedding:

The resulting value \(\varepsilon\) (empty string) signals any-value matching to both the Overpass query builder (omitting the value selector) and the post-query tag matcher (accepting any value for the given key).

11.1.2 Tag Validation Constraints

Tag validation follows the OSM key naming convention and restricts characters that carry special semantics in Overpass QL:

11.1.3 Query Construction for Custom Tags

A custom tag query constructs a single TagSpec and normalizes it, producing an Overpass query with exactly one selector (for point or line geometries) or two selectors (for polygon, querying both ways and relations):

This is significant in the context of OSM data quality research: the ability to query any single tag enables spatial data quality assessments (Haklay, 2010), completeness metrics, and temporal analyses of tag evolution when combined with OSM history data. The geometry constraint also provides a natural filtering mechanism — researchers can isolate, for example, only point representations of amenities, excluding polygon footprints of the same feature type.

11.2 Parameters

11.3 Outputs

Same 22-field output schema as Algorithm 1 (see Section 10.3). The preset_id field is set to "custom" and theme to "Custom tag". Only the output layer corresponding to the selected geometry type will contain features; the other two layers will be empty.

11.4 Interpretation Guidance

• Key-only queries: When the value field is blank, the algorithm retrieves all elements with that key. For high-frequency keys like building or highway, this can return very large result sets even within the 100 km² extent. Consider specifying a value to narrow results.
• Tag frequency analysis: Use the tags_json field to analyse the distribution of values for a given key, supporting research on OSM tag adoption and heterogeneity.
• Cross-preset validation: Custom tag downloads can be compared with preset downloads to verify that presets capture all relevant features (e.g., comparing amenity=hospital custom download against the Healthcare preset).

11.4.1 References

1. Goodchild, M.F. (2007). Citizens as sensors: the world of volunteered geography. GeoJournal, 69(4), 211-221. DOI: 10.1007/s10708-007-9111-y
2. Haklay, M. (2010). How good is volunteered geographical information? A comparative study of OpenStreetMap and Ordnance Survey datasets. Environment and Planning B, 37(4), 682-703. DOI: 10.1068/b35097
3. Mooney, P. & Corcoran, P. (2012). Characteristics of heavily edited objects in OpenStreetMap. Future Internet, 4(4), 880-906. DOI: 10.3390/fi4030880
4. Barrington-Leigh, C. & Millard-Ball, A. (2017). The world's user-generated road map is more than 80% complete. PLOS ONE, 12(8), e0180698. DOI: 10.1371/journal.pone.0171362
5. Boeing, G. (2017). OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks. Computers, Environment and Urban Systems, 65, 126-139. DOI: 10.1016/j.compenvurbsys.2017.05.004
6. Haklay, M. & Weber, P. (2008). OpenStreetMap: User-generated street maps. IEEE Pervasive Computing, 7(4), 12-18. DOI: 10.1145/1463434.1463442
7. Neis, P. & Zipf, A. (2012). Analyzing the contributor activity of a volunteered geographic information project. ISPRS Int. J. Geo-Inf., 1(2), 146-165. DOI: 10.3390/fi4030880
8. Schmidt, M. & Weiser, P. (2010). OpenStreetMap data quality. IEEE Computer, 43(12), 94-97. DOI: 10.1109/MC.2010.21

12. Algorithm 3: Download Structured Advanced OSM Query

Algorithm ID: download_advanced
Display name: Download structured advanced OSM query
Group: OSM acquisition

12.1 Theoretical Background

The advanced query algorithm provides multi-tag Boolean query construction without exposing raw Overpass QL to the user. This design bridges the gap between the simplicity of presets and the power of direct Overpass queries, while maintaining the plugin's security boundary. In the OSM research literature, such structured query interfaces support multi-criteria spatial data selection—identifying features that satisfy combinations of tag constraints across potentially different geometry types (Neis & Zipf, 2012; Boeing, 2017).

The algorithm supports up to 4 tag filters (each a key/value pair), two Boolean match modes (ANY/OR and ALL/AND), and four geometry scopes (All geometries, Points, Lines, Polygons). This yields a combinatorial query space of \(2 \times 4 \times 4^4 = 2,048\) possible queries (without considering the continuous extent parameter), each of which is rendered as a syntactically valid, bounded Overpass QL string.

12.1.1 Boolean Match Semantics

In ANY (OR) mode, each tag filter independently generates Overpass selectors. An OSM element is retained if it matches at least one filter. This is the most permissive mode, suitable for broad thematic queries (e.g., "all features tagged as either retail or office or industrial").

In ALL (AND) mode, all tag filters must match for a given geometry kind. The Overpass query groups selectors by geometry kind and concatenates all tag filters for that geometry onto each primitive selector. Additionally, the same OSM key cannot appear in more than one filter (because a single element cannot have two different values for the same key). Client-side validation enforces this constraint through set-based key deduplication. This mode supports precision queries (e.g., "all ways that are both highway=residential AND surface=asphalt").

12.1.2 AND-Mode Conjunction Algebra

In AND mode, the client-side matching operates as a logical conjunction over the set of tag specifications for each geometry kind. An element passes the filter if and only if all specifications in its geometry group are simultaneously satisfied:

The AND-mode additionally enforces key uniqueness across all filters: no two filter specifications may share the same OSM key. This constraint is validated in advanced_specs() by comparing the set of keys against the list length: if \(|\{k_i\}| < |\{ (k_i, v_i) \}|\), the request is rejected with a descriptive error. This prevents the logical contradiction of requiring a single element to have two different values for the same key.

12.1.3 Advanced Spec Combinatorics

The advanced_specs() function generates the Cartesian product of geometry kinds and tag filters, bounded by the maximum filter count:

The final expression emphasises that while the structural parameters (match mode, geometry scope, filter count) yield a finite set of 2,048 structural configurations, the actual query space is vast due to the combinatorial explosion of possible OSM key/value combinations.

12.1.4 Query Expressivity

The advanced algorithm's expressivity is deliberately constrained. It does not support: spatial operators (around, poly), recursion operators, difference/union of query results, regular expression matching, or conditional logic. This constraint is by design: it keeps queries predictable, performant, and safe for the Overpass public service infrastructure (Olbricht, 2021). For users requiring these capabilities, the raw Overpass API or local OSM data processing tools (osmium, osm2pgsql) are recommended.

12.2 Parameters

12.3 Outputs

Same 22-field output schema as Algorithm 1 (see Section 10.3). The preset_id field is set to "advanced" and theme to "Advanced query". Output layers are populated according to the geometry scope and the matching elements' classified geometry kinds.

12.4 Interpretation Guidance

• AND-mode result sizes: AND mode is significantly more restrictive than OR mode. A query for buildings that are ALSO schools (building=* AND amenity=school) will return far fewer results than the union of all buildings and all schools. This is by design: AND mode identifies the intersection of tag sets.
• Geometry scope interactions: When geometry scope is "All geometries", the advanced_specs() function generates TagSpec objects for all three geometry kinds (point, line, polygon). The resulting Overpass query includes node, way, and relation selectors. Post-download, each element is classified according to the kind classification function.
• Key-value emptiness: In AND mode, if all values are empty (any-value matching), the query is logically equivalent to "elements that have ALL of these keys." For example, highway=* AND surface=* in AND mode returns highway elements that also have a surface tag, which is a useful query for assessing tag co-occurrence completeness.
• Overpass server load: Advanced queries with 4 filters in "All geometries" mode generate the largest number of Overpass selectors (up to \(3 \times 4 = 12\) in OR mode). For large extents, consider reducing the geometry scope or filter count.

12.4.1 References

1. Goodchild, M.F. (2007). Citizens as sensors: the world of volunteered geography. GeoJournal, 69(4), 211-221. DOI: 10.1007/s10708-007-9111-y
2. Haklay, M. (2010). How good is volunteered geographical information? A comparative study of OpenStreetMap and Ordnance Survey datasets. Environment and Planning B, 37(4), 682-703. DOI: 10.1068/b35097
3. Mooney, P. & Corcoran, P. (2012). Characteristics of heavily edited objects in OpenStreetMap. Future Internet, 4(4), 880-906. DOI: 10.3390/fi4030880
4. Neis, P. & Zipf, A. (2012). Analyzing the contributor activity of a volunteered geographic information project. ISPRS Int. J. Geo-Inf., 1(2), 146-165. DOI: 10.3390/fi4030880
5. Barrington-Leigh, C. & Millard-Ball, A. (2017). The world's user-generated road map is more than 80% complete. PLOS ONE, 12(8), e0180698. DOI: 10.1371/journal.pone.0171362
6. Boeing, G. (2017). OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks. Computers, Environment and Urban Systems, 65, 126-139. DOI: 10.1016/j.compenvurbsys.2017.05.004
7. Haklay, M. & Weber, P. (2008). OpenStreetMap: User-generated street maps. IEEE Pervasive Computing, 7(4), 12-18. DOI: 10.1145/1463434.1463442
8. Schmidt, M. & Weiser, P. (2010). OpenStreetMap data quality. IEEE Computer, 43(12), 94-97. DOI: 10.1109/MC.2010.21

13. Algorithm 4: Download Curated OSM Datasets for a Named Place

Algorithm ID: download_place
Display name: Download curated OSM datasets for a named place
Group: OSM acquisition

This endpoint combines the multi-dataset preset request with a bounded place lookup. It first constructs a safe administrative-name query, ranks the OSM results, and replaces the temporary extent with the selected candidate's bounding box. It then follows the same selector normalisation, geometry classification, output-sink, caching, and cancellation pipeline as download_preset.

13.1 Parameters

13.2 Outputs

The output schema is the same 22-field schema used by the other download algorithms. The preset_id value contains the selected preset IDs joined by +; theme contains the first selected preset's group title. Processing feedback reports the resolved candidate label and administrative level when available.

13.3 Interpretation Guidance

• Short names: Konak, Van, and London are valid place inputs. The resolver searches multiple OSM name fields rather than relying on a fixed local city list.
• Parent context: A phrase such as Izmir Konak queries the full phrase and the final name token, retaining the supplied parent context for a useful display label.
• Large boundaries: A valid match can still be rejected if its bounding box exceeds 100 km². This prevents a place name from bypassing the normal request-area guard.
• Failure handling: No match, malformed place text, network failure, oversized response, timeout, and cancellation all produce an actionable Processing error without creating partial output layers.

14. Thematic Preset Catalog

The preset catalogue encodes 30 curated OSM feature collections across 15 thematic groups. Each preset comprises a set of tag specifications, each specifying an OSM key, an optional value filter, and a target geometry kind. The table below enumerates all presets.

Each preset also carries English keywords used by the natural-language intent router in core/catalog.py. The interpret_prompt() function performs Unicode NFKD normalisation, case-folding, diacritic removal, and substring matching against these keywords to map free-text user input to the nearest preset. It also extracts a place phrase from connectors such as in, near, and within. A place-only command such as Konak selects the administrative-places preset and is resolved by the named-place endpoint at download time.

13.1 Intent Router Algorithm

where \(t \sqsubseteq \text{normalize}(\text{prompt})\) denotes substring containment after normalisation, and \(\text{terms}(\text{preset}) = \text{keywords} \cup \{\text{title}, \text{group_title}\}\).

15. Security Architecture

The 02Agent OSM Downloader is designed to pass the QGIS Plugin Hub's automated security scanning gates (Bandit static analysis and detect-secrets credential scanning) and the Qt6/metadata compliance validation. The following design decisions enforce this:

14.1 Input Validation

• Tag key validation: Regular expression ^[A-Za-z0-9_:.~-]{1,80}$ — restricts keys to the OSM character set and length limit.
• Tag value validation: Maximum 120 characters; rejects control characters (0x00-0x1f, 0x7f), double quotes, backslashes, semicolons, brackets, parentheses, and braces — all characters with special meaning in Overpass QL or JSON.
• Extent validation: Geographic bounds check (-90 to 90 latitude, -180 to 180 longitude), finiteness check, area limit (100 km²), and non-degenerate extent check (south < north, west < east).
• Response validation: Type check (must be dict), remark check (server timeout indicator), elements list existence, element count limit (150,000), and per-element type check.
• Place-name validation: Maximum 120 characters; control characters, quotes, and backslashes are rejected before the value is escaped into a bounded name-field regular expression.

14.2 No Arbitrary Code Execution

• No raw query input: The plugin never accepts raw Overpass QL from any user-facing parameter.
• No file paths: No file dialog, path parameter, or file I/O beyond QGIS sink outputs (which use QGIS's sandboxed temporary directory infrastructure).
• No shell / subprocess: No subprocess, os.system, or equivalent calls. All network operations use Qt's QgsBlockingNetworkRequest.
• No external interpreters: No eval, exec, or importlib dynamic loading.
• Hard-coded endpoints: The three Overpass endpoints are compile-time constants in core/query.py; no URL parameter exists.
• Place lookup remains bounded: Place resolution uses the same pinned endpoints and only reads tags, centres, and bounding boxes. It cannot submit a user-supplied query, URL, path, or credential.

14.3 Resource Bounds

OpenStreetMap attribution and service notices

Downloaded OpenStreetMap data is © OpenStreetMap contributors and is available under the Open Database License 1.0. Keep OpenStreetMap attribution with retained layers, maps, screenshots, exports, and derived databases as applicable.

The optional XYZ basemap is supplied by the public OpenStreetMap tile service; keep its visible attribution and follow the tile usage policy. Downloads use the public Overpass mirrors listed in THIRD_PARTY_NOTICES.md; those services are external and subject to their own availability and fair-use limits.

16. References

1. Goodchild, M.F. (2007). Citizens as sensors: the world of volunteered geography. GeoJournal, 69(4), 211-221. DOI: 10.1007/s10708-007-9111-y
2. Haklay, M. (2010). How good is volunteered geographical information? A comparative study of OpenStreetMap and Ordnance Survey datasets. Environment and Planning B: Planning and Design, 37(4), 682-703. DOI: 10.1068/b35097
3. Mooney, P. & Corcoran, P. (2012). Characteristics of heavily edited objects in OpenStreetMap. Future Internet, 4(4), 880-906. DOI: 10.3390/fi4030880
4. Neis, P. & Zipf, A. (2012). Analyzing the contributor activity of a volunteered geographic information project — the case of OpenStreetMap. ISPRS International Journal of Geo-Information, 1(2), 146-165. DOI: 10.3390/fi4030880
5. Barrington-Leigh, C. & Millard-Ball, A. (2017). The world's user-generated road map is more than 80% complete. PLOS ONE, 12(8), e0180698. DOI: 10.1371/journal.pone.0171362
6. Boeing, G. (2017). OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks. Computers, Environment and Urban Systems, 65, 126-139. DOI: 10.1016/j.compenvurbsys.2017.05.004
7. Haklay, M. & Weber, P. (2008). OpenStreetMap: User-generated street maps. IEEE Pervasive Computing, 7(4), 12-18. DOI: 10.1145/1463434.1463442
8. Schmidt, M. & Weiser, P. (2010). OpenStreetMap data quality — assessment and assurance. IEEE Computer, 43(12), 94-97. DOI: 10.1109/MC.2010.21
9. Olbricht, R. (2021). Overpass API: Programmatic access to OpenStreetMap data. In A. Mobasheri (Ed.), OpenStreetMap in GIScience (pp. 109-128). Springer. DOI: 10.1007/978-3-319-14280-7_6
10. Girres, J.F. & Touya, G. (2010). Quality assessment of the French OpenStreetMap dataset. Transactions in GIS, 14(4), 435-459. DOI: 10.1111/j.1467-9671.2010.01203.x
11. Zielstra, D. & Zipf, A. (2010). A comparative study of proprietary geodata and volunteered geographic information for Germany. Proceedings of the 13th AGILE International Conference on Geographic Information Science, Guimarães, Portugal.
12. Corcoran, P., Mooney, P. & Bertolotto, M. (2013). Analysing the growth of OpenStreetMap networks. Spatial Statistics, 3, 21-41. DOI: 10.1016/j.spasta.2013.01.002
13. Jokar Arsanjani, J., Zipf, A., Mooney, P. & Helbich, M. (Eds.). (2015). OpenStreetMap in GIScience: Experiences, Research, and Applications. Springer. DOI: 10.1007/978-3-319-14280-7
14. Senaratne, H., Mobasheri, A., Ali, A.L., Capineri, C. & Haklay, M. (2017). A review of volunteered geographic information quality assessment methods. International Journal of Geographical Information Science, 31(1), 139-167. DOI: 10.1080/13658816.2016.1189556