# Elements ## Query features by spatial predicate, bounding box, or H3 cell `elements.query(**kwargs) -> FeatureCollection` **get** `/api/v1/features` Query features by spatial predicate, bounding box, or H3 cell ### Parameters - `bbox: String` Legacy shorthand. Bounding box: south,west,north,east. Use spatial predicates (near, within, intersects) instead. - `contains: String` Geometry that features must contain - `crosses: String` Geometry that features must cross - `cursor: String` Cursor for pagination - `h3: String` Legacy shorthand. H3 cell index. Use spatial predicates instead. - `intersects: String` Geometry that features must intersect - `limit: Integer` Maximum results (default 100, max 10000) - `near: String` Point geometry for proximity search (lat,lng). Requires radius. - `output_buffer: Float` Buffer geometry by meters - `output_centroid: bool` Replace geometry with centroid - `output_fields: String` Comma-separated property fields to include - `output_geometry: bool` Include geometry (default true) - `output_include: String` Extra computed fields: bbox, distance, center - `output_precision: Integer` Coordinate decimal precision (1-15, default 7) - `output_simplify: Float` Simplify geometry tolerance in meters - `output_sort: String` Sort by: distance, name, osm_id - `radius: Float` Search radius in meters (for near) or buffer distance (for other predicates) - `touches: String` Geometry that features must touch - `type: String` Element types (comma-separated: node,way,relation) - `within: String` Geometry that features must be within ### Returns - `class FeatureCollection` 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[GeoJsonFeature]` Array of GeoJSON Feature objects - `geometry: GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array[Float]` [longitude, latitude] or [longitude, latitude, elevation] - `Array[Array[Float]]` Array of [lng, lat] positions - `Array[Array[Array[Float]]]` Array of linear rings / line strings - `Array[Array[Array[Array[Float]]]]` Array of polygons - `type: :Point | :LineString | :Polygon | 3 more` Geometry type - `:Point` - `:LineString` - `:Polygon` - `:MultiPoint` - `:MultiLineString` - `:MultiPolygon` - `properties: Hash[Symbol, untyped]` 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` - `:Feature` - `id: String` Compound identifier in `type/osm_id` format - `type: :FeatureCollection` Always `FeatureCollection` - `:FeatureCollection` ### Example ```ruby require "plaza" plaza = Plaza::Client.new( api_key: "My API Key", environment: "local" # defaults to "production" ) feature_collection = plaza.elements.query puts(feature_collection) ``` #### Response ```json { "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" } ``` ## Query features by spatial predicate, bounding box, or H3 cell `elements.query_post(**kwargs) -> FeatureCollection` **post** `/api/v1/features` Query features by spatial predicate, bounding box, or H3 cell ### Parameters - `bbox: String` Legacy shorthand. Bounding box: south,west,north,east. Use spatial predicates (near, within, intersects) instead. - `contains: String` Geometry that features must contain - `crosses: String` Geometry that features must cross - `cursor: String` Cursor for pagination - `h3: String` Legacy shorthand. H3 cell index. Use spatial predicates instead. - `intersects: String` Geometry that features must intersect - `limit: Integer` Maximum results (default 100, max 10000) - `near: String` Point geometry for proximity search (lat,lng). Requires radius. - `output_buffer: Float` Buffer geometry by meters - `output_centroid: bool` Replace geometry with centroid - `output_fields: String` Comma-separated property fields to include - `output_geometry: bool` Include geometry (default true) - `output_include: String` Extra computed fields: bbox, distance, center - `output_precision: Integer` Coordinate decimal precision (1-15, default 7) - `output_simplify: Float` Simplify geometry tolerance in meters - `output_sort: String` Sort by: distance, name, osm_id - `radius: Float` Search radius in meters (for near) or buffer distance (for other predicates) - `touches: String` Geometry that features must touch - `type: String` Element types (comma-separated: node,way,relation) - `within: String` Geometry that features must be within ### Returns - `class FeatureCollection` 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[GeoJsonFeature]` Array of GeoJSON Feature objects - `geometry: GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array[Float]` [longitude, latitude] or [longitude, latitude, elevation] - `Array[Array[Float]]` Array of [lng, lat] positions - `Array[Array[Array[Float]]]` Array of linear rings / line strings - `Array[Array[Array[Array[Float]]]]` Array of polygons - `type: :Point | :LineString | :Polygon | 3 more` Geometry type - `:Point` - `:LineString` - `:Polygon` - `:MultiPoint` - `:MultiLineString` - `:MultiPolygon` - `properties: Hash[Symbol, untyped]` 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` - `:Feature` - `id: String` Compound identifier in `type/osm_id` format - `type: :FeatureCollection` Always `FeatureCollection` - `:FeatureCollection` ### Example ```ruby require "plaza" plaza = Plaza::Client.new( api_key: "My API Key", environment: "local" # defaults to "production" ) feature_collection = plaza.elements.query_post puts(feature_collection) ``` #### Response ```json { "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" } ``` ## Get feature by type and ID `elements.retrieve(id, **kwargs) -> GeoJsonFeature` **get** `/api/v1/features/{type}/{id}` Get feature by type and ID ### Parameters - `type: String` - `id: Integer` ### Returns - `class GeoJsonFeature` GeoJSON Feature representing an OSM element. Tags from the original OSM element are flattened directly into `properties` (not nested under a `tags` key). Metadata fields `@type` and `@id` identify the OSM element type and ID within properties. - `geometry: GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array[Float]` [longitude, latitude] or [longitude, latitude, elevation] - `Array[Array[Float]]` Array of [lng, lat] positions - `Array[Array[Array[Float]]]` Array of linear rings / line strings - `Array[Array[Array[Array[Float]]]]` Array of polygons - `type: :Point | :LineString | :Polygon | 3 more` Geometry type - `:Point` - `:LineString` - `:Polygon` - `:MultiPoint` - `:MultiLineString` - `:MultiPolygon` - `properties: Hash[Symbol, untyped]` 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` - `:Feature` - `id: String` Compound identifier in `type/osm_id` format ### Example ```ruby require "plaza" plaza = Plaza::Client.new( api_key: "My API Key", environment: "local" # defaults to "production" ) geo_json_feature = plaza.elements.retrieve(0, type: "type") puts(geo_json_feature) ``` #### Response ```json { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "@id": "bar", "@type": "bar", "amenity": "bar", "cuisine": "bar", "name": "bar" }, "type": "Feature", "id": "node/21154906" } ``` ## Get feature by type and ID `elements.lookup() -> GeoJsonFeature` **post** `/api/v1/features/lookup` Get feature by type and ID ### Returns - `class GeoJsonFeature` GeoJSON Feature representing an OSM element. Tags from the original OSM element are flattened directly into `properties` (not nested under a `tags` key). Metadata fields `@type` and `@id` identify the OSM element type and ID within properties. - `geometry: GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array[Float]` [longitude, latitude] or [longitude, latitude, elevation] - `Array[Array[Float]]` Array of [lng, lat] positions - `Array[Array[Array[Float]]]` Array of linear rings / line strings - `Array[Array[Array[Array[Float]]]]` Array of polygons - `type: :Point | :LineString | :Polygon | 3 more` Geometry type - `:Point` - `:LineString` - `:Polygon` - `:MultiPoint` - `:MultiLineString` - `:MultiPolygon` - `properties: Hash[Symbol, untyped]` 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` - `:Feature` - `id: String` Compound identifier in `type/osm_id` format ### Example ```ruby require "plaza" plaza = Plaza::Client.new( api_key: "My API Key", environment: "local" # defaults to "production" ) geo_json_feature = plaza.elements.lookup puts(geo_json_feature) ``` #### Response ```json { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "@id": "bar", "@type": "bar", "amenity": "bar", "cuisine": "bar", "name": "bar" }, "type": "Feature", "id": "node/21154906" } ``` ## Fetch multiple features by type and ID `elements.batch(**kwargs) -> FeatureCollection` **post** `/api/v1/features/batch` Fetch multiple features by type and ID ### Parameters - `elements: Array[{ id, type}]` Array of element references to fetch - `id: Integer` OSM element ID - `type: :node | :way | :relation` OSM element type - `:node` - `:way` - `:relation` ### Returns - `class FeatureCollection` 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[GeoJsonFeature]` Array of GeoJSON Feature objects - `geometry: GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array[Float]` [longitude, latitude] or [longitude, latitude, elevation] - `Array[Array[Float]]` Array of [lng, lat] positions - `Array[Array[Array[Float]]]` Array of linear rings / line strings - `Array[Array[Array[Array[Float]]]]` Array of polygons - `type: :Point | :LineString | :Polygon | 3 more` Geometry type - `:Point` - `:LineString` - `:Polygon` - `:MultiPoint` - `:MultiLineString` - `:MultiPolygon` - `properties: Hash[Symbol, untyped]` 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` - `:Feature` - `id: String` Compound identifier in `type/osm_id` format - `type: :FeatureCollection` Always `FeatureCollection` - `:FeatureCollection` ### Example ```ruby require "plaza" plaza = Plaza::Client.new( api_key: "My API Key", environment: "local" # defaults to "production" ) feature_collection = plaza.elements.batch(elements: [{id: 21154906, type: :node}, {id: 4589123, type: :way}]) puts(feature_collection) ``` #### Response ```json { "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" } ``` ## Find features near a geographic point `elements.nearby(**kwargs) -> FeatureCollection` **get** `/api/v1/features/nearby` Find features near a geographic point ### Parameters - `lat: Float` Legacy shorthand. Latitude (-90 to 90). Use near param instead. - `limit: Integer` Maximum results (default 20, max 100) - `lng: Float` Legacy shorthand. Longitude (-180 to 180). Use near param instead. - `near: String` Point geometry for proximity search (lat,lng or GeoJSON). Alternative to lat/lng params. - `output_buffer: Float` Buffer geometry by meters - `output_centroid: bool` Replace geometry with centroid - `output_fields: String` Comma-separated property fields to include - `output_geometry: bool` Include geometry (default true) - `output_include: String` Extra computed fields: bbox, distance, center - `output_precision: Integer` Coordinate decimal precision (1-15, default 7) - `output_simplify: Float` Simplify geometry tolerance in meters - `output_sort: String` Sort by: distance, name, osm_id - `radius: Integer` Search radius in meters (default 500, max 10000) ### Returns - `class FeatureCollection` 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[GeoJsonFeature]` Array of GeoJSON Feature objects - `geometry: GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array[Float]` [longitude, latitude] or [longitude, latitude, elevation] - `Array[Array[Float]]` Array of [lng, lat] positions - `Array[Array[Array[Float]]]` Array of linear rings / line strings - `Array[Array[Array[Array[Float]]]]` Array of polygons - `type: :Point | :LineString | :Polygon | 3 more` Geometry type - `:Point` - `:LineString` - `:Polygon` - `:MultiPoint` - `:MultiLineString` - `:MultiPolygon` - `properties: Hash[Symbol, untyped]` 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` - `:Feature` - `id: String` Compound identifier in `type/osm_id` format - `type: :FeatureCollection` Always `FeatureCollection` - `:FeatureCollection` ### Example ```ruby require "plaza" plaza = Plaza::Client.new( api_key: "My API Key", environment: "local" # defaults to "production" ) feature_collection = plaza.elements.nearby puts(feature_collection) ``` #### Response ```json { "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" } ``` ## Find features near a geographic point `elements.nearby_post(**kwargs) -> FeatureCollection` **post** `/api/v1/features/nearby` Find features near a geographic point ### Parameters - `lat: Float` Legacy shorthand. Latitude (-90 to 90). Use near param instead. - `limit: Integer` Maximum results (default 20, max 100) - `lng: Float` Legacy shorthand. Longitude (-180 to 180). Use near param instead. - `near: String` Point geometry for proximity search (lat,lng or GeoJSON). Alternative to lat/lng params. - `output_buffer: Float` Buffer geometry by meters - `output_centroid: bool` Replace geometry with centroid - `output_fields: String` Comma-separated property fields to include - `output_geometry: bool` Include geometry (default true) - `output_include: String` Extra computed fields: bbox, distance, center - `output_precision: Integer` Coordinate decimal precision (1-15, default 7) - `output_simplify: Float` Simplify geometry tolerance in meters - `output_sort: String` Sort by: distance, name, osm_id - `radius: Integer` Search radius in meters (default 500, max 10000) ### Returns - `class FeatureCollection` 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[GeoJsonFeature]` Array of GeoJSON Feature objects - `geometry: GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array[Float]` [longitude, latitude] or [longitude, latitude, elevation] - `Array[Array[Float]]` Array of [lng, lat] positions - `Array[Array[Array[Float]]]` Array of linear rings / line strings - `Array[Array[Array[Array[Float]]]]` Array of polygons - `type: :Point | :LineString | :Polygon | 3 more` Geometry type - `:Point` - `:LineString` - `:Polygon` - `:MultiPoint` - `:MultiLineString` - `:MultiPolygon` - `properties: Hash[Symbol, untyped]` 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` - `:Feature` - `id: String` Compound identifier in `type/osm_id` format - `type: :FeatureCollection` Always `FeatureCollection` - `:FeatureCollection` ### Example ```ruby require "plaza" plaza = Plaza::Client.new( api_key: "My API Key", environment: "local" # defaults to "production" ) feature_collection = plaza.elements.nearby_post puts(feature_collection) ``` #### Response ```json { "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" } ``` ## Domain Types ### Batch Request - `class BatchRequest` Fetch multiple OSM elements by their type and ID in a single request. Maximum 100 elements per batch. - `elements: Array[{ id, type}]` Array of element references to fetch - `id: Integer` OSM element ID - `type: :node | :way | :relation` OSM element type - `:node` - `:way` - `:relation`