---
title: OpenStreetMap Area Graph (osmAG) Overview
url: https://www.emergentmind.com/topics/openstreetmap-area-graph-osmag
type: topic
---

# OpenStreetMap Area Graph (osmAG) Overview

OpenStreetMap Area Graph (osmAG) is a hierarchical semantic topometric map representation, and later a map standard, that encodes environments in OpenStreetMap (OSM) XML for mobile robotics. Its defining abstraction is an Area Graph in which areas are the primary spatial entities and passages are the traversable connections between them; unlike dense occupancy grids or point clouds, osmAG is intended to store topology, metric geometry, semantics, and hierarchy in one compact representation that spans indoor and outdoor space, multiple floors, and robot-relevant annotations such as stairs, elevators, door types, and terrain attributes [2309.04791, 2603.28271].

## 1. Conceptual origin and evolution

osmAG was introduced as an OSM-XML-based file format for “hierarchical semantic topometric Area Graph maps” because, in the cited formulation, no such format was popular within the robotics community [2309.04791]. The original motivation was to preserve what large-scale navigation and localization require at the global level—free-space structure, passages, semantics, and hierarchy—without inheriting the storage and scaling costs of point clouds, voxels, or monolithic occupancy grids. The representation was explicitly designed for mixed indoor/outdoor, multi-floor environments, and for planning conditioned on robot capabilities such as locomotion mode, curb handling, or door interaction [2309.04791].

The literature uses closely related expansions of the acronym. One paper describes osmAG as “Area Graph in OpenStreetMap format,” emphasizing the serialization of an Area Graph into OSM XML for compatibility with conventional robotic algorithms, humans, and large language models [2403.08228]. Later work treats osmAG as the “OpenStreetMap Area Graph” map standard and builds a full ROS2 navigation stack around it, indicating a shift from a file-format proposal to a broader systems substrate for planning, localization, and long-horizon autonomy [2603.28271].

A central design decision is that osmAG is region-centric rather than point-centric. In the original formulation, an area is a free-space polygon such as a room, corridor, terrain region, street segment, or larger grouped space, and a passage is a traversable connection between adjacent areas [2309.04791]. Later canonical descriptions sharpen this into an undirected area graph whose vertices are Areas and whose edges are Passages, with inner areas such as rooms, corridors, elevators, and stairs coexisting with structure areas such as floors, sectors, wings, and buildings [2603.28271]. This makes osmAG closer to architectural and functional decomposition than to classical street-network graphs or occupancy-grid cells.

## 2. Representational model and OSM encoding

At the data-model level, osmAG reuses the OSM/XML object model. Areas and passages are serialized as OSM `way` elements, while their geometry is stored as OSM `node` coordinates in WGS84; a designated root node anchors the local Cartesian robotic frame to geodetic OSM coordinates [2309.04791, 2603.28271]. In the 2023 formulation, the core reinterpretation is simple: a closed `way` denotes an area, and a line-like `way` denotes a passage [2309.04791]. This preserves compatibility with existing OSM tooling while assigning robotics-specific semantics to OSM primitives.

An area is a closed polygon defined by an ordered list of OSM nodes, and a passage is an explicit connector between two areas, represented geometrically as a line segment or short polyline on a shared interface; doors, corridor openings, elevator interfaces, and stair transitions are all modeled this way [2603.28271]. The hierarchy is encoded through parent-child containment. Rooms can belong to floors, floors to buildings, and buildings to campuses; later work extends the same mechanism to floors, sectors, and wings, with lowest-common-ancestor reasoning used directly by the planner [2309.04791, 2603.28271].

The schema has evolved but remains centered on a stable set of tags and constraints [2309.04791, 2603.28271].

| Tag or field | Function | Note |
|---|---|---|
| `osmAG:id` | Stable osmAG-internal identifier | Introduced to avoid dependence on mutable OSM IDs |
| `osmAG:type` | Distinguishes area vs passage | Core discriminator in both early and later descriptions |
| `osmAG:from`, `osmAG:to` | Passage endpoints | Store the two incident areas of a passage |
| `osmAG:parent` | Hierarchical containment | Encodes parent area |
| `osmAG:areatype` / `osmAG:areaType` | Area category | Early work emphasizes `inner` vs `structure`; later work uses classes such as `room`, `corridor`, `structure`, `elevator`, `stairs` |
| `height`, `level` | Elevation and floor information | Used for multi-floor modeling |

The later canonical schema also imposes validity constraints: hierarchy must form a tree or forest, children must lie geometrically within parents, sibling areas on the same level under the same parent must have disjoint interiors, and each passage must connect exactly two existing named areas [2603.28271]. Vertical topology is represented natively rather than by planner-side special cases: each floor-specific elevator or stair footprint is its own area, and inter-floor passages connect those floor-specific vertical areas across adjacent floors [2603.28271].

This representational choice also explains why osmAG is described as topometric rather than merely topological. The map is sparse enough for graph reasoning, but areas remain polygons and passages remain geometric connectors. The planner can therefore render local submaps, compute within-area traversal costs, and retain human-readable semantics at the same time [2309.04791, 2603.28271].

## 3. Map generation, hierarchy formation, and source modalities

osmAG maps can be constructed from several upstream modalities. The original paper states that osmAGlib can convert from 2D grid maps using earlier Area Graph extraction work, from CAD files after manual layer cleanup, from 3D point clouds using previous hierarchical topometric mapping work, and by merging multiple maps based on node distances and point consolidation [2309.04791]. This already positioned osmAG as a unifying output layer rather than a sensor-specific map.

The most explicit generation pipeline appears in “Generation of Indoor Open Street Maps for Robot Navigation from CAD Files” [2507.00552]. There the workflow is a complete and automated system that converts architectural CAD floor plans into a hierarchical topometric OSM representation tailored to robot navigation. The pipeline first isolates key structural layers from raw CAD data, then applies AreaGraph-based topological segmentation to partition the building layout into a hierarchical graph of navigable spaces, automatically associates textual labels from the CAD source, and finally merges multiple building floors into a unified, topologically-correct model [2507.00552]. The paper characterizes this as an alternative to SLAM-centric map production in large, dynamic indoor spaces, because CAD encodes permanent structural information rather than transient clutter [2507.00552].

AreaGraph-based segmentation is the critical intermediate step. The free-space layout inferred from walls and openings is partitioned into rooms, corridors, and related navigable subregions, with passages aligned to doors or other transitions. The details trace back to the cited AreaGraph line of work rather than being re-derived in the CAD paper, but the role is explicit: the final osmAG is an OSM-encoded hierarchical graph of navigable areas rather than a raw floor-plan export [2507.00552].

Hierarchy is not only descriptive. In the original osmAG design, multiple neighboring areas can be grouped into larger areas for abstraction, while floors are stacked as 2D areas with height annotations [2309.04791]. Later work generalizes this into building $\supset$ floor $\supset$ sector $\supset$ room containment trees, enabling campus-scale and multi-floor maps to be represented uniformly [2603.28271]. This suggests that osmAG is best understood as a layered semantic decomposition of navigable space rather than a flat adjacency graph.

## 4. Planning, localization, and navigation systems

A recurrent theme in the osmAG literature is that planning cost does not reside naturally on area vertices. The 2023 paper argues that planning directly on the area graph is problematic because traversal cost is associated with moving through an area from one passage to another, not merely with entering or leaving a node [2309.04791]. It therefore renders each area as a local 2D grid and computes within-area traversal cost with A*, then transforms the problem into a passage graph in which vertices are passages and edges represent feasible traversals across an area [2309.04791]. The planning procedure finds the leaf areas of the start and goal, temporarily connects start and goal to the passages of their containing areas using A* on rendered 2D grids, then runs A* in the passage-level graph and returns either a list of passages and areas or point-wise traces from the local grids [2309.04791].

The first quantitative demonstration used a large osmAG map containing two multi-story buildings and one outdoor area, with 4908 nodes, 500 areas, and 347 passages in an 883.9 kb XML file. The reported indoor area was approximately \(22300\,m^2\), the outdoor area approximately \(3000\,m^2\), the planned path length \(157.57\,m\), topological-level planning time about \(3100\,\mu s\), and pre-computation time about \(200\,ms\) on an Intel i7-6700 CPU [2309.04791]. These results established the compactness and mixed indoor/outdoor, multi-floor planning scope of the representation.

The full systems elaboration is “osmAG-Nav: A Hierarchical Semantic Topometric Navigation Stack for Robust Lifelong Indoor Autonomy” [2603.28271]. That stack adopts a “System of Systems” architecture separating global semantic-topological reasoning from local metric execution. A Hierarchical osmAG planner replaces dense grid searches with an LCA-anchored pipeline over a passage-centric graph whose edge costs derive from local raster traversability rather than Euclidean distance; a Rolling Window rasterizes a fixed-size local occupancy grid around the robot; and Segmented Execution dispatches intermediate goals to standard ROS2 controllers [2603.28271]. The frame decomposition is also explicit: `AGmap` for global semantic-topological reasoning, `map` for metric navigation consumed by Nav2, and `odom` for short-term motion [2603.28271].

The performance claims are correspondingly system-level. On a real multi-story indoor-outdoor campus of more than \(11{,}025\,m^2\), the osmAG representation required 1.4 MB for the whole campus, compared to about 48.5 MB for a 2D occupancy grid at 0.05 m resolution and about 1536 MB for a 0.1 m voxel point cloud [2603.28271]. On 696 same-floor benchmark queries, hierarchical osmAG planning reached \(1.361\,ms\) on long routes versus \(10641.0\,ms\) for Grid A*, yielding the reported \(7816\times\) lower planning latency on long routes while maintaining low path-length overhead [2603.28271]. A caching ablation showed that removing static caches increased hierarchical query latency from \(1.827\,ms\) to \(106.011\,ms\) without changing paths, identifying cached compact graphs as a decisive implementation detail [2603.28271].

Localization has followed the same structure-first logic. In osmAG-Nav, AGLoc++ performs structure-aware LiDAR localization against permanent architectural priors, filtering dynamic clutter before point-to-line ICP and reporting \(15.6\,ms\) per frame, lab ATE \(0.07\,m\), and corridor ATE \(0.36\,m\), compared with larger corridor errors for both the original AGLoc and AMCL [2603.28271]. A separate WiFi-based localization framework leverages “osmAG's geometric and topological priors” in a large-scale indoor environment: its abstract reports mean AP localization error \(3.79\,m\), a \(35.3\%\) improvement over trilateration, mean robot localization error \(3.12\,m\) in fingerprinted areas, and \(3.83\,m\) in non-fingerprinted areas, with an \(81.05\%\) improvement in the latter case over the comparison baseline across an \(11{,}025\,m^2\) multi-floor environment [2508.10144]. The supplied material for that paper does not include the missing methods section, so its precise osmAG instantiation is not recoverable from the provided text, but the structural-prior role is explicit [2508.10144].

## 5. Textual reasoning, LLM comprehension, and reactive autonomy

A distinctive feature of osmAG is that, because it is serialized in OSM XML and can be reduced to a compact textual form, it has been used not only by conventional planning and localization algorithms but also by language models. “Empowering Robot Path Planning with Large Language Models: osmAG Map Topology & Hierarchy Comprehension with LLMs” treats osmAG as a text-based hierarchical, topometric semantic map representation and evaluates LLMs on topology and hierarchy comprehension rather than metric reasoning [2403.08228]. In that work, areas are graph nodes, passages are line segments of area polygons connecting neighboring areas, and parent-child tags encode containment chains such as room $\rightarrow$ zone $\rightarrow$ floor $\rightarrow$ wing $\rightarrow$ building [2403.08228]. The authors introduced textual variants of osmAG in which connectivity is made increasingly explicit, including a `connected_area` tag and a more lexicalized `current area name_directly_connected_room` form, and found that the textualization materially affected comprehension [2403.08228].

The quantitative result is that base LLaMA2 models were weak on osmAG comprehension, while fine-tuned models became highly accurate. Fine-tuned LLaMA2-13B reached \(0.95\) on the main topological Dataset 2, \(0.97\) on the unseen-layout Dataset 3, and \(0.99\) on the hierarchical Dataset 4, exceeding ChatGPT-3.5 and, on Dataset 2, surpassing ChatGPT-4.0 as reported in the paper [2403.08228]. The same work also describes a real-life demonstration in which ChatGPT-4 replanned around an elevator closure after being given an email notification, using osmAG as the structural map prior [2403.08228]. This made explicit a use case already implicit in the design: osmAG can serve as a shared textual and geometric substrate between symbolic reasoning and conventional navigation.

HaltNav extends this idea from map comprehension to closed-loop vision-language navigation under changing local connectivity [2603.12696]. There the prior is modeled as a dynamic weighted directed graph
$$\mathcal{G}_t = (\mathcal{V}, \mathcal{E}, W_t),$$
with semantic nodes corresponding to regions and traversable passages represented in the edge set [2603.12696]. The actual planner operates on a derived passage-level graph
$$\mathcal{G}_p = (\mathcal{P}, \mathcal{E}_p),$$
where stored traversal costs between passages are maintained over time [2603.12696]. When Reactive Visual Halting detects that the world contradicts the static prior, the planner updates the cost matrix by
$$
C_{t+1}(p_i, p_j) = \begin{cases}
\infty, & \text{if visual anomaly is detected},\\
C_t(p_i, p_j), & \text{otherwise}.
\end{cases}
$$
This converts a blocked connector into a pruned topological option without rebuilding the whole map [2603.12696].

In simulation and on a real Fetch robot in a university building, the paper reports that this osmAG-grounded hierarchy improves robustness under sparse instructions and blocked doors. In real-world obstacle settings, HaltNav achieved success rates of \(56.66\) for L0-O and \(46.66\) for L2-O, while both baselines in those obstacle settings collapsed to \(0\%\) success rate [2603.12696]. The paper interprets this as evidence that lightweight topological priors are essential, not merely helpful, for robust real-world VLN under underspecified instructions and environmental changes [2603.12696].

## 6. Distinctions, trade-offs, and recurrent misconceptions

osmAG is frequently adjacent to, but should not be conflated with, several other OSM-derived graph families. Street-network graphs such as the OSMnx-style primal, directed, nonplanar weighted multidigraphs of intersections and street segments are fundamentally intersection-centric rather than area-centric [1705.02198]. Billion-scale systems such as OSM+ standardize OSM into road-network graphs whose vertices are intersections and POI points and whose edges are road segments, again without an area-passage decomposition [2512.06743]. Heterogeneous local OSM graphs such as OSMGraphCLIP keep points, lines, and polygons as typed nodes connected by DE-9IM-style relations, which is useful for geospatial representation learning but is not the same as osmAG’s navigable area hierarchy [2606.08046]. WorldKG, similarly, is an ontology-backed semantic geographic knowledge graph over OSM entities rather than a topometric navigation graph over areas and passages [2109.10036].

A common misconception is that osmAG is merely raw OpenStreetMap adapted for indoor maps. The papers are more specific. osmAG is a robotics-oriented convention layered on top of OSM XML that reinterprets OSM primitives to encode navigable free-space areas, passages, hierarchy, and robotics-specific semantics such as locomotion-relevant surface or door properties [2309.04791]. Another misconception is that it simply replaces occupancy grids. The later navigation stack is explicit that local metric rasterization remains necessary; osmAG replaces the monolithic global grid with sparse global semantics and topology, while Nav2 still consumes bounded occupancy grids produced by the Rolling Window mechanism [2603.28271].

The trade-offs are equally explicit. The original proposal is largely offline and acknowledges manual effort in some source modalities, such as CAD layer cleanup [2309.04791]. Later work notes that osmAG assumes environments can be decomposed into meaningful areas and passages; in open-plan or weakly structured spaces, segmentation may be ambiguous [2603.28271]. The topology is treated as structurally static: the current systems invalidate blocked passages or assign infinite traversal cost, but do not learn entirely new connectivity online [2603.12696, 2603.28271]. Edge costs remain geometry-aware proxies derived from raster A* rather than full kinodynamic or learned semantics [2603.28271]. And while cross-floor planning is native, fully autonomous physical elevator interaction still requires additional engineering modules such as behavior-tree orchestration, floor recognition, and transition-specific recovery [2603.28271].

Taken together, these works define osmAG as a compact OSM-based representation for structured navigable space: areas as first-class entities, passages as explicit transitions, hierarchy as a planning primitive, and semantics as a bridge between embodiment, architecture, and high-level reasoning. Its subsequent uses in ROS2 navigation, LiDAR and WiFi localization, LLM map comprehension, and reactive vision-language navigation indicate that the representation is not merely a storage format but a unifying abstraction for large-scale, multi-floor, semantically grounded mobile autonomy [2309.04791, 2603.28271, 2403.08228, 2603.12696, 2508.10144].

Source: https://www.emergentmind.com/topics/openstreetmap-area-graph-osmag