# Available Layer Types in Prettymaps: Streets, Water, and Buildings

> Discover the available layer types in prettymaps: streets, water, and buildings. Learn how each layer type is fetched, transformed, and drawn for beautiful map rendering.

- Repository: [Marcelo de Oliveira Rosa Prates/prettymaps](https://github.com/marceloprates/prettymaps)
- Tags: getting-started
- Published: 2026-08-20

---

**Prettymaps renders maps by pulling OpenStreetMap data into named layers—`streets`, `water`, and `building`—where each identifier triggers a distinct fetch, transform, and draw pipeline.**

The `marceloprates/prettymaps` library generates artistic maps by organizing OpenStreetMap (OSM) data into semantic layers. Understanding the available layer types in prettymaps is essential because each name controls how geometries are retrieved, whether they are treated as graphs or polygons, and how they appear in the final composition.

## Core Prettymaps Layer Types

Prettymaps recognizes specific string names that determine how OSM data is queried and what geometry type is produced.

### Streets

The **`streets`** layer is a graph-based layer. In [`prettymaps/fetch.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/fetch.py), the function `unified_osm_request` detects this name and calls `osmnx.graph_from_polygon` to retrieve the street network inside the query polygon. The graph is then converted with `ox.graph_to_gdfs`. In [`prettymaps/draw.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/draw.py), the helper `gdf_to_shapely` dispatches to `graph_to_shapely`, turning every edge into a buffered line whose width can be customized. This produces the main road network rendered as thick or thin lines.

### Water

The **`water`** layer uses `ox.features.features_from_polygon` with the OSM tag `{ "natural": "water" }`. It produces a collection of **LineString** and **Polygon** geometries representing rivers, streams, canals, and lakes. The name **`waterway`** is also accepted and uses the tag `"waterway"`, making it ideal for river networks and canals. When rendered, these typically appear as blue-coloured water bodies.

### Building

The **`building`** layer pulls OSM features with the tag `{ "building": True }`. Because it is not part of the special graph-based family, `unified_osm_request` falls back to a simple feature query. The raw geometries are polygons or multipolygons representing building footprints. In [`prettymaps/draw.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/draw.py), these pass through `geometries_to_shapely` and are rendered as solid or outlined blocks that create the urban texture.

## Fetch and Render Pipeline

The distinction between layer types is hard-coded in two core files.

In **[`prettymaps/fetch.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/fetch.py)**, `unified_osm_request` decides whether a layer belongs to the graph family. Only `streets`, `railway`, and `waterway` receive the `ox.graph_from_polygon` treatment. All other names—including `water` and `building`—are fetched as standard OSM features.

In **[`prettymaps/draw.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/draw.py)**, `gdf_to_shapely` routes graph-based layers to `graph_to_shapely` and everything else to `geometries_to_shapely`. For non-graph layers, `geometries_to_shapely` simply buffers points or lines if a `point_size` or `line_width` is supplied; otherwise it passes the geometry through unchanged.

Style control happens through dictionaries such as `GPX_STYLE` or user-provided `style` arguments, where you can set face colour (`fc`), edge colour (`ec`), line width (`lw`), and hatch patterns per layer name.

## Customizing Layers in Code

You can configure the available layer types in prettymaps directly inside the `layers` and `style` arguments of `pm.plot`.

### Basic Three-Layer Map

```python
import prettymaps as pm

pm.plot(
    query="Porto Alegre, Brazil",
    layers={
        "streets": {"width": 1.5},          # street network (graph)

        "water":   {"fc": "#a0c8f0"},       # water bodies (polygons)

        "building": {"fc": "#d9c5a1"},      # building footprints

    },
    style={
        "streets": {"ec": "#475657", "lw": 0},
        "water":   {"ec": "#2F3737"},
        "building": {"ec": "#2F3737"},
    },
    figsize="a4",
    show=True,
)

```

### Custom Street Widths and Transparent Buildings

```python
pm.plot(
    query="Manhattan, NY",
    layers={
        "streets": {"width": {"motorway": 4, "primary": 2, "secondary": 1}},
        "building": {"fc": "#F1E6D0", "alpha": 0.6},
        "water": {"fc": "#CDE4F5"},
    },
    style={},
    show=True,
)

```

### Combining Water and Waterway Layers

```python
pm.plot(
    query="Zurich, Switzerland",
    layers={
        "streets":  {},
        "building": {},
        "water":    {},                 # natural water (lakes, ponds)

        "waterway": {"fc": "#6AA9FF"}  # rivers & canals

    },
    style={},
    show=True,
)

```

## Auxiliary Layers and Fallback Behavior

Beyond the three main visual layers, prettymaps defines auxiliary layers such as `hillshade`, `sea`, `gpx`, and `perimeter`. These support extra effects like relief shading, sea masks, and GPS track overlays, but they are not visualized as standard streets, water, or buildings.

When a layer name is not one of the recognized graph-based identifiers, prettymaps automatically falls back to `geometries_to_shapely`. This behavior ensures that any valid OSM feature tag can be passed through and rendered without requiring explicit hard-coding in the library.

## Summary

- **`streets`** is fetched as an OSMnx graph, converted to GeoDataFrames, and rendered as buffered lines via `graph_to_shapely`.
- **`water`** queries `natural=water` features, while **`waterway`** queries waterway features; both produce LineString or Polygon geometries.
- **`building`** queries `building=True` features and produces Polygon or MultiPolygon footprints.
- [`prettymaps/fetch.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/fetch.py) and [`prettymaps/draw.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/draw.py) split the pipeline into graph-based vs. geometry-based processing.
- Layer appearance is controlled through the `layers` and `style` dictionaries passed to `pm.plot`.

## Frequently Asked Questions

### What are the default layer types available in prettymaps?

Prettymaps supports three primary visual layer types out of the box: `streets` for road networks, `water` for natural water bodies, and `building` for structure footprints. It also accepts `waterway` as a variant of the water layer and provides auxiliary layers such as `hillshade`, `sea`, `gpx`, and `perimeter` for additional effects.

### How does prettymaps fetch street networks differently from water or buildings?

According to the `marceloprates/prettymaps` source code, the `unified_osm_request` function in [`prettymaps/fetch.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/fetch.py) treats `streets` as a graph. It uses `osmnx.graph_from_polygon` and `ox.graph_to_gdfs`, whereas `water` and `building` are fetched as standard OSM features through `ox.features.features_from_polygon`.

### Can I plot both `water` and `waterway` in the same prettymaps composition?

Yes. The `water` layer renders natural water bodies like lakes and ponds, while `waterway` targets linear features such as rivers and canals. You can include both keys in the `layers` dictionary simultaneously and assign each its own style parameters.

### Where does the conversion from OSM data to Shapely geometries happen?

The conversion is handled in [`prettymaps/draw.py`](https://github.com/marceloprates/prettymaps/blob/main/prettymaps/draw.py). The `gdf_to_shapely` helper dispatches graph-based layers to `graph_to_shapely` and all other layers to `geometries_to_shapely`, which either buffers points and lines or passes polygon geometries through unchanged.