---
title: OSM Data Model | Plaza Docs
description: How OpenStreetMap structures geographic data and how Plaza exposes it through the API.
---

Plaza includes the full OpenStreetMap (OSM) planet as one of its core data sources. Understanding how OSM models the world helps you write better queries and interpret results when working with OSM data.

## Three element types

Everything in OSM is one of three types.

### Nodes

A node is a point on the map — a single latitude/longitude pair. Nodes represent discrete things: a cafe, a bench, a traffic light, a tree, a summit. There are roughly 8 billion nodes in the OSM planet.

Many nodes exist only as coordinates in a way (see below) and have no tags of their own. A node with tags is a point of interest.

### Ways

A way is an ordered list of nodes forming a line or shape. If the first and last node are the same, it’s a closed way — usually representing an area (a building, a park, a lake). If they differ, it’s an open way — usually a road, path, river, or wall.

There are roughly 1 billion ways in the planet.

### Relations

A relation is a group of nodes, ways, or other relations with assigned roles. They model things that can’t be expressed with a single way:

- **Multipolygons** — A lake with islands, a building with a courtyard.
- **Routes** — A bus line, a hiking trail spanning many ways.
- **Boundaries** — Administrative borders (country, state, city).
- **Turn restrictions** — “No left turn from way A to way B via node C.”

There are roughly 15 million relations in the planet.

## Tags

Tags are how OSM describes what things are. Every element can have zero or more tags, each a key=value string pair.

Some common keys:

| Key                | Example values                       | What it describes     |
| ------------------ | ------------------------------------ | --------------------- |
| `name`             | `Tour Eiffel`, `Broadway`            | The name of the thing |
| `amenity`          | `cafe`, `hospital`, `school`         | Points of interest    |
| `highway`          | `residential`, `motorway`, `footway` | Roads and paths       |
| `building`         | `yes`, `apartments`, `church`        | Buildings             |
| `shop`             | `supermarket`, `bakery`, `clothes`   | Retail                |
| `natural`          | `tree`, `water`, `peak`              | Natural features      |
| `opening_hours`    | `Mo-Fr 09:00-18:00`                  | Operating hours       |
| `cuisine`          | `italian`, `sushi`, `burger`         | Restaurant food type  |
| `addr:street`      | `Rue de Rivoli`                      | Street address        |
| `addr:housenumber` | `42`                                 | House number          |

Tags are freeform — anyone can use any key. In practice, the community follows conventions on the [OSM wiki](https://wiki.openstreetmap.org/wiki/Map_features). For real-world usage stats, check [taginfo.openstreetmap.org](https://taginfo.openstreetmap.org/).

## OSM IDs

Every element has a numeric ID unique within its type. Node 123 and way 123 are different things. The pair (type, id) is globally unique.

IDs are assigned sequentially and stable through edits. Deleted elements leave gaps — don’t assume IDs are contiguous or that higher IDs are newer.

## How Plaza exposes this

Plaza returns OSM data as GeoJSON Features. Tags are flattened into `properties` alongside `@type` and `@id`:

```
{
  "@type": "way",
  "@id": 123456789,
  "building": "yes",
  "name": "Musée du Louvre",
  "tourism": "museum",
  "wikipedia": "en:Louvre"
}
```

The geometry type depends on the element:

| OSM type                | GeoJSON geometry   |
| ----------------------- | ------------------ |
| Node                    | Point              |
| Way (open)              | LineString         |
| Way (closed)            | Polygon            |
| Relation (multipolygon) | MultiPolygon       |
| Relation (route)        | MultiLineString    |
| Relation (other)        | GeometryCollection |

### Filtering by tags

Most endpoints accept tag filters via bracket syntax — filter by key existence, exact value, or regex:

Terminal window

```
# All cafes within a bounding area
curl -X POST https://plaza.fyi/api/v1/features \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "within": {
      "type": "Polygon",
      "coordinates": [[[2.33, 48.85], [2.35, 48.85], [2.35, 48.87], [2.33, 48.87], [2.33, 48.85]]]
    },
    "type": "node",
    "tags": { "amenity": "cafe" }
  }'


# All buildings with a name
curl -X POST https://plaza.fyi/api/v1/features \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "within": {
      "type": "Polygon",
      "coordinates": [[[2.33, 48.85], [2.35, 48.85], [2.35, 48.87], [2.33, 48.87], [2.33, 48.85]]]
    },
    "type": "way",
    "tags": { "building": "yes", "name": "~." }
  }'
```

`"amenity": "cafe"` means “has `amenity` tag with value `cafe`.” Use `"name": "~."` for regex matching (here, any non-empty `name` value). Multiple tag filters are ANDed together.

## Browsing the tag ecosystem

- **[taginfo.openstreetmap.org](https://taginfo.openstreetmap.org/)** — Usage counts, common combinations, and geographic distribution. The most useful reference for OSM tags.
- **[wiki.openstreetmap.org/wiki/Map\_features](https://wiki.openstreetmap.org/wiki/Map_features)** — Community-maintained tagging conventions.
- **[overpass-turbo.eu](https://overpass-turbo.eu/)** — Visual query builder for prototyping.

Workflow: find tags on taginfo, test a small query with Plaza, then scale up.