Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Elements

Query features by spatial predicate, bounding box, or H3 cell

POST/api/v1/features

Query features by spatial predicate, bounding box, or H3 cell

Query ParametersExpand Collapse
bbox: optional string

Legacy shorthand. Bounding box: south,west,north,east. Use spatial predicates (near, within, intersects) instead.

contains: optional string

Geometry that features must contain

crosses: optional string

Geometry that features must cross

cursor: optional string

Cursor for pagination

format: optional string

Response format. json (default) returns paginated GeoJSON. geojson/csv/ndjson stream via chunked transfer encoding.

h3: optional string

Legacy shorthand. H3 cell index. Use spatial predicates instead.

intersects: optional string

Geometry that features must intersect

limit: optional number

Maximum results (default 100, max 10000)

near: optional string

Point geometry for proximity search (lat,lng). Requires radius.

"output[buffer]": optional number

Buffer geometry by meters

"output[centroid]": optional boolean

Replace geometry with centroid

"output[fields]": optional string

Comma-separated property fields to include

"output[geometry]": optional boolean

Include geometry (default true)

"output[include]": optional string

Extra computed fields: bbox, distance, center

"output[precision]": optional number

Coordinate decimal precision (1-15, default 7)

"output[simplify]": optional number

Simplify geometry tolerance in meters

"output[sort]": optional string

Sort by: distance, name, osm_id

radius: optional number

Search radius in meters (for near) or buffer distance (for other predicates)

touches: optional string

Geometry that features must touch

type: optional string

Element types (comma-separated: node,way,relation)

within: optional string

Geometry that features must be within

ReturnsExpand Collapse
FeatureCollection = object { features, type }

GeoJSON FeatureCollection (RFC 7946). For paginated endpoints, metadata is returned in HTTP response headers rather than the body:

Header Description
X-Limit Requested result limit
X-Has-More true if more results exist
X-Next-Cursor Opaque cursor for next page (cursor pagination)
X-Next-Offset Numeric offset for next page (offset pagination)
Link RFC 8288 rel="next" link to the next page

Content-Type is application/geo+json.

features: array of GeoJsonFeature { geometry, properties, type, id }

Array of GeoJSON Feature objects

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:
Point = array of number

[longitude, latitude] or [longitude, latitude, elevation]

LineStringOrMultiPoint = array of array of number

Array of [lng, lat] positions

PolygonOrMultiLineString = array of array of array of number

Array of linear rings / line strings

MultiPolygon = array of array of array of array of number

Array of polygons

type: "Point" or "LineString" or "Polygon" or 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: map[unknown]

OSM tags flattened as key-value pairs, plus @type (node/way/relation) and @id (OSM ID) metadata fields. May include distance_m for proximity queries.

type: "Feature"

Always Feature

id: optional string

Compound identifier in type/osm_id format

type: "FeatureCollection"

Always FeatureCollection

Query features by spatial predicate, bounding box, or H3 cell

curl https://plaza.fyi/api/v1/features \
    -X POST \
    -H "Authorization: Bearer $PLAZA_API_KEY"
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "@id": "bar",
        "@type": "bar",
        "amenity": "bar",
        "cuisine": "bar",
        "name": "bar"
      },
      "type": "Feature",
      "id": "node/21154906"
    }
  ],
  "type": "FeatureCollection"
}
Returns Examples
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "@id": "bar",
        "@type": "bar",
        "amenity": "bar",
        "cuisine": "bar",
        "name": "bar"
      },
      "type": "Feature",
      "id": "node/21154906"
    }
  ],
  "type": "FeatureCollection"
}