# Query ## Execute a multi-step query pipeline `client.Query.Execute(ctx, body) (*QueryExecuteResponse, error)` **post** `/api/v1/query` Execute a multi-step query pipeline ### Parameters - `body QueryExecuteParams` - `Steps param.Field[[]QueryExecuteParamsStep]` Ordered list of query steps to execute - `Type QueryExecuteParamsStepsType` Step type: `overpass`, `sparql`, `filter`, or `transform` - `const QueryExecuteParamsStepsTypeOverpass QueryExecuteParamsStepsType = "overpass"` - `const QueryExecuteParamsStepsTypeSparql QueryExecuteParamsStepsType = "sparql"` - `const QueryExecuteParamsStepsTypeFilter QueryExecuteParamsStepsType = "filter"` - `const QueryExecuteParamsStepsTypeTransform QueryExecuteParamsStepsType = "transform"` - `Query string` Query string for this step (required for overpass/sparql steps) ### Returns - `type QueryExecuteResponse struct{…}` Pipeline execution result containing the output of each step. - `Steps []map[string, unknown]` Results from each pipeline step in execution order ### Example ```go package main import ( "context" "fmt" "github.com/plazafyi/plaza-go" "github.com/plazafyi/plaza-go/option" ) func main() { client := githubcomplazafyiplazago.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Query.Execute(context.TODO(), githubcomplazafyiplazago.QueryExecuteParams{ Steps: githubcomplazafyiplazago.F([]githubcomplazafyiplazago.QueryExecuteParamsStep{githubcomplazafyiplazago.QueryExecuteParamsStep{ Type: githubcomplazafyiplazago.F(githubcomplazafyiplazago.QueryExecuteParamsStepsTypeOverpass), }}), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.Steps) } ``` #### Response ```json { "steps": [ { "foo": "bar" } ] } ``` ## Execute an Overpass QL query `client.Query.Overpass(ctx, body) (*FeatureCollection, error)` **post** `/api/v1/overpass` Execute an Overpass QL query ### Parameters - `body QueryOverpassParams` - `OverpassQuery param.Field[OverpassQuery]` Overpass QL query request. The query is executed against Plaza's OSM database and results are returned as GeoJSON. ### Returns - `type FeatureCollection struct{…}` 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 []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 GeoJsonGeometryCoordinatesUnion` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `type GeoJsonGeometryCoordinatesPoint []float64` [longitude, latitude] or [longitude, latitude, elevation] - `type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64` Array of [lng, lat] positions - `type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64` Array of linear rings / line strings - `type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64` Array of polygons - `Type GeoJsonGeometryType` Geometry type - `const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"` - `const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"` - `const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"` - `const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"` - `const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"` - `const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"` - `Properties map[string, 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 GeoJsonFeatureType` Always `Feature` - `const GeoJsonFeatureTypeFeature GeoJsonFeatureType = "Feature"` - `ID string` Compound identifier in `type/osm_id` format - `Type FeatureCollectionType` Always `FeatureCollection` - `const FeatureCollectionTypeFeatureCollection FeatureCollectionType = "FeatureCollection"` ### Example ```go package main import ( "context" "fmt" "github.com/plazafyi/plaza-go" "github.com/plazafyi/plaza-go/option" ) func main() { client := githubcomplazafyiplazago.NewClient( option.WithAPIKey("My API Key"), ) featureCollection, err := client.Query.Overpass(context.TODO(), githubcomplazafyiplazago.QueryOverpassParams{ OverpassQuery: githubcomplazafyiplazago.OverpassQueryParam{ Data: githubcomplazafyiplazago.F("[out:json];node[amenity=cafe](around:500,48.8566,2.3522);out body;"), }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", featureCollection.Features) } ``` #### 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 `client.Query.Sparql(ctx, body) (*SparqlResult, error)` **post** `/api/v1/sparql` Execute a SPARQL query ### Parameters - `body QuerySparqlParams` - `SparqlQuery param.Field[SparqlQuery]` SPARQL query request. Queries OSM data using SPARQL syntax. Results are returned as a JSON object with a `results` array. ### Returns - `type SparqlResult struct{…}` 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. - `Results []SparqlResultResult` 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. - `Geometry GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates GeoJsonGeometryCoordinatesUnion` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `type GeoJsonGeometryCoordinatesPoint []float64` [longitude, latitude] or [longitude, latitude, elevation] - `type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64` Array of [lng, lat] positions - `type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64` Array of linear rings / line strings - `type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64` Array of polygons - `Type GeoJsonGeometryType` Geometry type - `const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"` - `const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"` - `const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"` - `const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"` - `const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"` - `const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"` - `Properties map[string, unknown]` OSM tags as key-value pairs, optionally with `@type` and `@id` metadata - `Type SparqlResultResultsType` Always `Feature` - `const SparqlResultResultsTypeFeature SparqlResultResultsType = "Feature"` - `ID string` Compound identifier in `type/osm_id` format (present when element type is known) ### Example ```go package main import ( "context" "fmt" "github.com/plazafyi/plaza-go" "github.com/plazafyi/plaza-go/option" ) func main() { client := githubcomplazafyiplazago.NewClient( option.WithAPIKey("My API Key"), ) sparqlResult, err := client.Query.Sparql(context.TODO(), githubcomplazafyiplazago.QuerySparqlParams{ SparqlQuery: githubcomplazafyiplazago.SparqlQueryParam{ Query: githubcomplazafyiplazago.F(`SELECT ?s ?name WHERE { ?s osm:name ?name . ?s osm:amenity "cafe" } LIMIT 10`), }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", sparqlResult.Results) } ``` #### Response ```json { "results": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "foo": "bar" }, "type": "Feature", "id": "id" } ] } ``` ## Domain Types ### Overpass Query - `type OverpassQuery struct{…}` Overpass QL query request. The query is executed against Plaza's OSM database and results are returned as GeoJSON. - `Data string` Overpass QL query string ### Sparql Query - `type SparqlQuery struct{…}` SPARQL query request. Queries OSM data using SPARQL syntax. Results are returned as a JSON object with a `results` array. - `Query string` SPARQL query string ### Sparql Result - `type SparqlResult struct{…}` 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. - `Results []SparqlResultResult` 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. - `Geometry GeoJsonGeometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `Coordinates GeoJsonGeometryCoordinatesUnion` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `type GeoJsonGeometryCoordinatesPoint []float64` [longitude, latitude] or [longitude, latitude, elevation] - `type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64` Array of [lng, lat] positions - `type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64` Array of linear rings / line strings - `type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64` Array of polygons - `Type GeoJsonGeometryType` Geometry type - `const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"` - `const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"` - `const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"` - `const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"` - `const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"` - `const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"` - `Properties map[string, unknown]` OSM tags as key-value pairs, optionally with `@type` and `@id` metadata - `Type SparqlResultResultsType` Always `Feature` - `const SparqlResultResultsTypeFeature SparqlResultResultsType = "Feature"` - `ID string` Compound identifier in `type/osm_id` format (present when element type is known)