# Query ## Execute a multi-step query pipeline `QueryExecuteResponse query().execute(QueryExecuteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **post** `/api/v1/query` Execute a multi-step query pipeline ### Parameters - `QueryExecuteParams params` - `List steps` Ordered list of query steps to execute - `Type type` Step type: `overpass`, `sparql`, `filter`, or `transform` - `OVERPASS("overpass")` - `SPARQL("sparql")` - `FILTER("filter")` - `TRANSFORM("transform")` - `Optional query` Query string for this step (required for overpass/sparql steps) ### Returns - `class QueryExecuteResponse:` Pipeline execution result containing the output of each step. - `List steps` Results from each pipeline step in execution order ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.query.QueryExecuteParams; import com.plazafyi.models.query.QueryExecuteResponse; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); QueryExecuteParams params = QueryExecuteParams.builder() .addStep(QueryExecuteParams.Step.builder() .type(QueryExecuteParams.Step.Type.OVERPASS) .build()) .build(); QueryExecuteResponse response = client.query().execute(params); } } ``` #### Response ```json { "steps": [ { "foo": "bar" } ] } ``` ## Execute an Overpass QL query `FeatureCollection query().overpass(QueryOverpassParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **post** `/api/v1/overpass` Execute an Overpass QL query ### Parameters - `QueryOverpassParams params` - `OverpassQuery overpassQuery` Overpass QL query request. The query is executed against Plaza's OSM database and results are returned as GeoJSON. ### 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.query.OverpassQuery; import com.plazafyi.models.query.QueryOverpassParams; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); OverpassQuery params = OverpassQuery.builder() .data("[out:json];node[amenity=cafe](around:500,48.8566,2.3522);out body;") .build(); FeatureCollection featureCollection = client.query().overpass(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" } ``` ## Execute a SPARQL query `SparqlResult query().sparql(QuerySparqlParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **post** `/api/v1/sparql` Execute a SPARQL query ### Parameters - `QuerySparqlParams params` - `SparqlQuery sparqlQuery` SPARQL query request. Queries OSM data using SPARQL syntax. Results are returned as a JSON object with a `results` array. ### Returns - `class SparqlResult:` SPARQL query result. Contains a `results` array of GeoJSON Feature objects. Unlike REST feature endpoints, SPARQL results may omit `@type`, `@id`, and compound `id` fields depending on the query shape. - `List results` Array of GeoJSON Features matching the SPARQL query. Features include `@type` and `@id` metadata when the source element type is known, but may contain only tags as properties for untyped results. - `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 as key-value pairs, optionally with `@type` and `@id` metadata - `Type type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format (present when element type is known) ### Example ```java package com.plazafyi.example; import com.plazafyi.client.PlazaClient; import com.plazafyi.client.okhttp.PlazaOkHttpClient; import com.plazafyi.models.query.QuerySparqlParams; import com.plazafyi.models.query.SparqlQuery; import com.plazafyi.models.query.SparqlResult; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); SparqlQuery params = SparqlQuery.builder() .query("SELECT ?s ?name WHERE { ?s osm:name ?name . ?s osm:amenity \"cafe\" } LIMIT 10") .build(); SparqlResult sparqlResult = client.query().sparql(params); } } ``` #### Response ```json { "results": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "foo": "bar" }, "type": "Feature", "id": "id" } ] } ``` ## Domain Types ### Overpass Query - `class OverpassQuery:` Overpass QL query request. The query is executed against Plaza's OSM database and results are returned as GeoJSON. - `String data` Overpass QL query string ### Sparql Query - `class SparqlQuery:` SPARQL query request. Queries OSM data using SPARQL syntax. Results are returned as a JSON object with a `results` array. - `String query` SPARQL query string ### Sparql Result - `class SparqlResult:` SPARQL query result. Contains a `results` array of GeoJSON Feature objects. Unlike REST feature endpoints, SPARQL results may omit `@type`, `@id`, and compound `id` fields depending on the query shape. - `List results` Array of GeoJSON Features matching the SPARQL query. Features include `@type` and `@id` metadata when the source element type is known, but may contain only tags as properties for untyped results. - `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 as key-value pairs, optionally with `@type` and `@id` metadata - `Type type` Always `Feature` - `FEATURE("Feature")` - `Optional id` Compound identifier in `type/osm_id` format (present when element type is known)