GeoJSON Primer

Plaza returns all spatial data as GeoJSON (RFC 7946). Here’s what you need to know.

Coordinates are [longitude, latitude]

This trips up everyone at least once. GeoJSON uses [lng, lat], not [lat, lng].

[2.3522, 48.8566]

That’s Paris. Longitude first (east-west), latitude second (north-south). If your points end up in the ocean off the coast of Africa, you probably swapped them.

Google Maps, Leaflet defaults, and most people’s intuition use lat/lng. GeoJSON doesn’t. Double-check this when things look wrong.

Geometry types

Point

A single location. Plaza returns nodes (POIs, addresses, trees, traffic lights) as Points.

{
  "type": "Point",
  "coordinates": [2.3522, 48.8566]
}

LineString

An ordered list of points forming a line. Roads, rivers, power lines, etc. come back as LineStrings.

{
  "type": "LineString",
  "coordinates": [
    [2.3522, 48.8566],
    [2.3530, 48.8570],
    [2.3545, 48.8580]
  ]
}

Minimum two points. Order matters — it defines the direction of the line.

Polygon

A closed shape — first and last coordinate must be identical. Buildings, parks, lakes, and land use areas come back as Polygons.

{
  "type": "Polygon",
  "coordinates": [[
    [2.3522, 48.8566],
    [2.3530, 48.8566],
    [2.3530, 48.8570],
    [2.3522, 48.8570],
    [2.3522, 48.8566]
  ]]
}

The double array holds rings — the first is the exterior boundary, additional rings are holes (like a building courtyard). Most polygons have one ring.

Coordinates follow the right-hand rule: exterior rings are counterclockwise, holes are clockwise.

MultiPoint, MultiLineString, MultiPolygon

Collections of the same geometry type. MultiPolygon is common — an archipelago, a country with exclaves, or a building with detached annexes.

{
  "type": "MultiPolygon",
  "coordinates": [
    [[[2.35, 48.85], [2.36, 48.85], [2.36, 48.86], [2.35, 48.86], [2.35, 48.85]]],
    [[[2.37, 48.85], [2.38, 48.85], [2.38, 48.86], [2.37, 48.86], [2.37, 48.85]]]
  ]
}

Features and FeatureCollections

A Feature pairs a geometry with properties:

{
  "type": "Feature",
  "id": "node/21154906",
  "geometry": {
    "type": "Point",
    "coordinates": [2.3522, 48.8566]
  },
  "properties": {
    "@type": "node",
    "@id": 21154906,
    "name": "Tour Eiffel",
    "tourism": "attraction",
    "height": "330"
  }
}

A FeatureCollection is a list of Features — what Plaza returns for most queries:

{
  "type": "FeatureCollection",
  "features": [
    { "type": "Feature", "geometry": { ... }, "properties": { ... } },
    { "type": "Feature", "geometry": { ... }, "properties": { ... } }
  ]
}

How Plaza uses GeoJSON

Every response is a FeatureCollection. Each Feature has:

• id — A string identifying the feature. For OSM data this combines type and ID, e.g. "node/21154906". For dataset features, this is the dataset feature ID.
• geometry — Point for nodes, LineString or Polygon for ways, and the appropriate Multi* type for relations.
• properties — For OSM features, includes @type, @id, and all tags as top-level keys. For dataset features, includes the dataset’s custom properties. Some endpoints add computed fields (like distance_m for nearby queries).

Single-resource lookups (e.g., GET /features/node/21154906) return a single GeoJSON Feature. List endpoints return a FeatureCollection.

Spatial filters

Plaza accepts GeoJSON geometry objects for spatial queries. Use within with a GeoJSON Polygon to filter by 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]]]
    }
  }'

A FeatureCollection response may include a top-level bbox field:

{
  "type": "FeatureCollection",
  "bbox": [2.33, 48.85, 2.35, 48.87],
  "features": [...]
}

Working with GeoJSON

Most mapping libraries consume GeoJSON natively:

• Mapbox GL / MapLibre GL — map.addSource('data', { type: 'geojson', data: response })
• Leaflet — L.geoJSON(response).addTo(map)
• Deck.gl — new GeoJsonLayer({ data: response })
• QGIS — Drag and drop a .geojson file onto the map
• Python (Shapely) — shape(feature['geometry'])
• Go — geojson.UnmarshalFeatureCollection(data)

geojson.io is handy for visualizing and debugging GeoJSON by hand.