# Elements ## Query features by spatial predicate, bounding box, or H3 cell `FeatureCollection elements().query(ElementQueryParamsparams = ElementQueryParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/api/v1/features` Query features by spatial predicate, bounding box, or H3 cell ### Parameters - `ElementQueryParams params` - `Optional bbox` Legacy shorthand. Bounding box: south,west,north,east. Use spatial predicates (near, within, intersects) instead. - `Optional contains` Geometry that features must contain - `Optional crosses` Geometry that features must cross - `Optional cursor` Cursor for pagination - `Optional h3` Legacy shorthand. H3 cell index. Use spatial predicates instead. - `Optional intersects` Geometry that features must intersect - `Optional limit` Maximum results (default 100, max 10000) - `Optional near` Point geometry for proximity search (lat,lng). Requires radius. - `Optional outputBuffer` Buffer geometry by meters - `Optional outputCentroid` Replace geometry with centroid - `Optional outputFields` Comma-separated property fields to include - `Optional outputGeometry` Include geometry (default true) - `Optional outputInclude` Extra computed fields: bbox, distance, center - `Optional outputPrecision` Coordinate decimal precision (1-15, default 7) - `Optional outputSimplify` Simplify geometry tolerance in meters - `Optional outputSort` Sort by: distance, name, osm_id - `Optional radius` Search radius in meters (for near) or buffer distance (for other predicates) - `Optional touches` Geometry that features must touch - `Optional type` Element types (comma-separated: node,way,relation) - `Optional within` 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`. - `List features` Array of GeoJSON Feature objects - `GeoJsonGeometry geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List` - `List>` - `List>>` - `List>>>` - `Type type` Geometry type - `POINT("Point")` - `LINE_STRING("LineString")` - `POLYGON("Polygon")` - `MULTI_POINT("MultiPoint")` - `MULTI_LINE_STRING("MultiLineString")` - `MULTI_POLYGON("MultiPolygon")` - `Properties properties` 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 type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format - `Type type` Always `FeatureCollection` - `FEATURE_COLLECTION("FeatureCollection")` ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.FeatureCollection; import com.plazafyi.models.elements.ElementQueryParams; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); FeatureCollection featureCollection = client.elements().query(); } } ``` #### 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 `FeatureCollection elements().queryPost(ElementQueryPostParamsparams = ElementQueryPostParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **post** `/api/v1/features` Query features by spatial predicate, bounding box, or H3 cell ### Parameters - `ElementQueryPostParams params` - `Optional bbox` Legacy shorthand. Bounding box: south,west,north,east. Use spatial predicates (near, within, intersects) instead. - `Optional contains` Geometry that features must contain - `Optional crosses` Geometry that features must cross - `Optional cursor` Cursor for pagination - `Optional h3` Legacy shorthand. H3 cell index. Use spatial predicates instead. - `Optional intersects` Geometry that features must intersect - `Optional limit` Maximum results (default 100, max 10000) - `Optional near` Point geometry for proximity search (lat,lng). Requires radius. - `Optional outputBuffer` Buffer geometry by meters - `Optional outputCentroid` Replace geometry with centroid - `Optional outputFields` Comma-separated property fields to include - `Optional outputGeometry` Include geometry (default true) - `Optional outputInclude` Extra computed fields: bbox, distance, center - `Optional outputPrecision` Coordinate decimal precision (1-15, default 7) - `Optional outputSimplify` Simplify geometry tolerance in meters - `Optional outputSort` Sort by: distance, name, osm_id - `Optional radius` Search radius in meters (for near) or buffer distance (for other predicates) - `Optional touches` Geometry that features must touch - `Optional type` Element types (comma-separated: node,way,relation) - `Optional within` 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`. - `List features` Array of GeoJSON Feature objects - `GeoJsonGeometry geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List` - `List>` - `List>>` - `List>>>` - `Type type` Geometry type - `POINT("Point")` - `LINE_STRING("LineString")` - `POLYGON("Polygon")` - `MULTI_POINT("MultiPoint")` - `MULTI_LINE_STRING("MultiLineString")` - `MULTI_POLYGON("MultiPolygon")` - `Properties properties` 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 type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format - `Type type` Always `FeatureCollection` - `FEATURE_COLLECTION("FeatureCollection")` ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.FeatureCollection; import com.plazafyi.models.elements.ElementQueryPostParams; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); FeatureCollection featureCollection = client.elements().queryPost(); } } ``` #### 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 `GeoJsonFeature elements().retrieve(ElementRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **get** `/api/v1/features/{type}/{id}` Get feature by type and ID ### Parameters - `ElementRetrieveParams params` - `String type` - `Optional 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. - `GeoJsonGeometry geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List` - `List>` - `List>>` - `List>>>` - `Type type` Geometry type - `POINT("Point")` - `LINE_STRING("LineString")` - `POLYGON("Polygon")` - `MULTI_POINT("MultiPoint")` - `MULTI_LINE_STRING("MultiLineString")` - `MULTI_POLYGON("MultiPolygon")` - `Properties properties` 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 type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.GeoJsonFeature; import com.plazafyi.models.elements.ElementRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); ElementRetrieveParams params = ElementRetrieveParams.builder() .type("type") .id(0L) .build(); GeoJsonFeature geoJsonFeature = client.elements().retrieve(params); } } ``` #### 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 `GeoJsonFeature elements().lookup(ElementLookupParamsparams = ElementLookupParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **post** `/api/v1/features/lookup` Get feature by type and ID ### Parameters - `ElementLookupParams params` ### 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. - `GeoJsonGeometry geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List` - `List>` - `List>>` - `List>>>` - `Type type` Geometry type - `POINT("Point")` - `LINE_STRING("LineString")` - `POLYGON("Polygon")` - `MULTI_POINT("MultiPoint")` - `MULTI_LINE_STRING("MultiLineString")` - `MULTI_POLYGON("MultiPolygon")` - `Properties properties` 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 type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.GeoJsonFeature; import com.plazafyi.models.elements.ElementLookupParams; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); GeoJsonFeature geoJsonFeature = client.elements().lookup(); } } ``` #### 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 `FeatureCollection elements().batch(ElementBatchParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **post** `/api/v1/features/batch` Fetch multiple features by type and ID ### Parameters - `ElementBatchParams params` - `BatchRequest batchRequest` Fetch multiple OSM elements by their type and ID in a single request. Maximum 100 elements per batch. ### 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`. - `List features` Array of GeoJSON Feature objects - `GeoJsonGeometry geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List` - `List>` - `List>>` - `List>>>` - `Type type` Geometry type - `POINT("Point")` - `LINE_STRING("LineString")` - `POLYGON("Polygon")` - `MULTI_POINT("MultiPoint")` - `MULTI_LINE_STRING("MultiLineString")` - `MULTI_POLYGON("MultiPolygon")` - `Properties properties` 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 type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format - `Type type` Always `FeatureCollection` - `FEATURE_COLLECTION("FeatureCollection")` ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.FeatureCollection; import com.plazafyi.models.elements.BatchRequest; import com.plazafyi.models.elements.ElementBatchParams; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); BatchRequest params = BatchRequest.builder() .addElement(BatchRequest.Element.builder() .id(21154906L) .type(BatchRequest.Element.Type.NODE) .build()) .addElement(BatchRequest.Element.builder() .id(4589123L) .type(BatchRequest.Element.Type.WAY) .build()) .build(); FeatureCollection featureCollection = client.elements().batch(params); } } ``` #### 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 `FeatureCollection elements().nearby(ElementNearbyParamsparams = ElementNearbyParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/api/v1/features/nearby` Find features near a geographic point ### Parameters - `ElementNearbyParams params` - `Optional lat` Legacy shorthand. Latitude (-90 to 90). Use near param instead. - `Optional limit` Maximum results (default 20, max 100) - `Optional lng` Legacy shorthand. Longitude (-180 to 180). Use near param instead. - `Optional near` Point geometry for proximity search (lat,lng or GeoJSON). Alternative to lat/lng params. - `Optional outputBuffer` Buffer geometry by meters - `Optional outputCentroid` Replace geometry with centroid - `Optional outputFields` Comma-separated property fields to include - `Optional outputGeometry` Include geometry (default true) - `Optional outputInclude` Extra computed fields: bbox, distance, center - `Optional outputPrecision` Coordinate decimal precision (1-15, default 7) - `Optional outputSimplify` Simplify geometry tolerance in meters - `Optional outputSort` Sort by: distance, name, osm_id - `Optional radius` 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`. - `List features` Array of GeoJSON Feature objects - `GeoJsonGeometry geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List` - `List>` - `List>>` - `List>>>` - `Type type` Geometry type - `POINT("Point")` - `LINE_STRING("LineString")` - `POLYGON("Polygon")` - `MULTI_POINT("MultiPoint")` - `MULTI_LINE_STRING("MultiLineString")` - `MULTI_POLYGON("MultiPolygon")` - `Properties properties` 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 type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format - `Type type` Always `FeatureCollection` - `FEATURE_COLLECTION("FeatureCollection")` ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.FeatureCollection; import com.plazafyi.models.elements.ElementNearbyParams; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); FeatureCollection featureCollection = client.elements().nearby(); } } ``` #### 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 `FeatureCollection elements().nearbyPost(ElementNearbyPostParamsparams = ElementNearbyPostParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **post** `/api/v1/features/nearby` Find features near a geographic point ### Parameters - `ElementNearbyPostParams params` - `Optional lat` Legacy shorthand. Latitude (-90 to 90). Use near param instead. - `Optional limit` Maximum results (default 20, max 100) - `Optional lng` Legacy shorthand. Longitude (-180 to 180). Use near param instead. - `Optional near` Point geometry for proximity search (lat,lng or GeoJSON). Alternative to lat/lng params. - `Optional outputBuffer` Buffer geometry by meters - `Optional outputCentroid` Replace geometry with centroid - `Optional outputFields` Comma-separated property fields to include - `Optional outputGeometry` Include geometry (default true) - `Optional outputInclude` Extra computed fields: bbox, distance, center - `Optional outputPrecision` Coordinate decimal precision (1-15, default 7) - `Optional outputSimplify` Simplify geometry tolerance in meters - `Optional outputSort` Sort by: distance, name, osm_id - `Optional radius` 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`. - `List features` Array of GeoJSON Feature objects - `GeoJsonGeometry geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List` - `List>` - `List>>` - `List>>>` - `Type type` Geometry type - `POINT("Point")` - `LINE_STRING("LineString")` - `POLYGON("Polygon")` - `MULTI_POINT("MultiPoint")` - `MULTI_LINE_STRING("MultiLineString")` - `MULTI_POLYGON("MultiPolygon")` - `Properties properties` 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 type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format - `Type type` Always `FeatureCollection` - `FEATURE_COLLECTION("FeatureCollection")` ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.FeatureCollection; import com.plazafyi.models.elements.ElementNearbyPostParams; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); FeatureCollection featureCollection = client.elements().nearbyPost(); } } ``` #### 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. - `List elements` Array of element references to fetch - `long id` OSM element ID - `Type type` OSM element type - `NODE("node")` - `WAY("way")` - `RELATION("relation")`