OSM Data Model

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. For real-world usage stats, check 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:

# 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 — Usage counts, common combinations, and geographic distribution. The most useful reference for OSM tags.
• wiki.openstreetmap.org/wiki/Map_features — Community-maintained tagging conventions.
• overpass-turbo.eu — Visual query builder for prototyping.

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