-
Notifications
You must be signed in to change notification settings - Fork 47
/
Copy pathopenapi.yaml
305 lines (282 loc) · 10.7 KB
/
openapi.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
openapi: 3.0.3
info:
title: STAC API - Item Search
version: v1.0.0
description: >-
This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Item Search
specification.
contact:
name: STAC Specification
url: "http://stacspec.org"
license:
name: Apache License 2.0
url: "http://www.apache.org/licenses/LICENSE-2.0"
tags:
- name: Item Search
description: essential characteristics of a STAC API
x-conformance-classes: ["https://api.stacspec.org/v1.0.0/item-search"]
paths:
/search:
get:
summary: Search STAC items with simple filtering.
operationId: getItemSearch
description: |-
Retrieve Items matching filters. Intended as a shorthand API for simple
queries.
This method is required to implement.
If this endpoint is implemented on a server, it is required to add a
link referring to this endpoint with `rel` set to `search` to the
`links` array in `GET /`. As `GET` is the default method, the `method`
may not be set explicitly in the link.
tags:
- Item Search
parameters:
- $ref: "#/components/parameters/bbox"
- $ref: "#/components/parameters/intersects"
- $ref: "#/components/parameters/datetime"
- $ref: "#/components/parameters/limit"
- $ref: "#/components/parameters/ids"
- $ref: "#/components/parameters/collectionsArray"
responses:
"200":
description: A feature collection.
content:
application/geo+json:
schema:
$ref: "../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection"
text/html:
schema:
type: string
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
post:
summary: Search STAC items with full-featured filtering.
operationId: postItemSearch
description: |-
Retrieve items matching filters. Intended as the standard, full-featured
query API.
This method is optional to implement, but recommended.
If this endpoint is implemented on a server, it is required to add a
link referring to this endpoint with `rel` set to `search` and `method`
set to `POST` to the `links` array in `GET /`.
tags:
- Item Search
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/searchBody"
responses:
"200":
description: A feature collection.
content:
application/geo+json:
schema:
$ref: "../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection"
text/html:
schema:
type: string
"4XX":
$ref: "../core/commons.yaml#/components/responses/Error"
"5XX":
$ref: "../core/commons.yaml#/components/responses/Error"
components:
parameters:
ids:
name: ids
in: query
description: |-
Array of Item ids to return.
required: false
schema:
$ref: "#/components/schemas/ids"
explode: false
collectionsArray:
name: collections
in: query
description: |
Array of Collection IDs to include in the search for items.
Only Item objects in one of the provided collections will be searched
required: false
schema:
$ref: "#/components/schemas/collectionsArray"
explode: false
datetime:
name: datetime
in: query
description: |-
Either a date-time or an interval, open or closed. Date and time expressions
adhere to RFC 3339. Open intervals are expressed using double-dots.
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
Only features that have a temporal property that intersects the value of
`datetime` are selected.
If a feature has multiple temporal properties, it is the decision of the
server whether only a single temporal property is used to determine
the extent or all relevant temporal properties.
required: false
schema:
type: string
style: form
explode: false
bbox:
name: bbox
in: query
description: |-
Only features that have a geometry that intersects the bounding box are selected.
The bounding box is provided as four or six numbers, depending on
whether the coordinate reference system includes a vertical axis (height
or depth):
* Lower left corner, coordinate axis 1
* Lower left corner, coordinate axis 2
* Minimum value, coordinate axis 3 (optional)
* Upper right corner, coordinate axis 1
* Upper right corner, coordinate axis 2
* Maximum value, coordinate axis 3 (optional)
The coordinate reference system of the values is WGS 84
longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
For WGS 84 longitude/latitude the values are in most cases the sequence
of minimum longitude, minimum latitude, maximum longitude and maximum
latitude. However, in cases where the box spans the antimeridian the
first value (west-most box edge) is larger than the third value
(east-most box edge).
If the vertical axis is included, the third and the sixth number are
the bottom and the top of the 3-dimensional bounding box.
If a feature has multiple spatial geometry properties, it is the
decision of the server whether only a single spatial geometry property
is used to determine the extent or all relevant geometries.
Example: The bounding box of the New Zealand Exclusive Economic Zone in
WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be
represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as
`bbox=160.6,-55.95,-170,-25.89`.
required: false
schema:
type: array
oneOf:
- minItems: 4
maxItems: 4
- minItems: 6
maxItems: 6
items:
type: number
style: form
explode: false
limit:
name: limit
in: query
description: |-
The optional limit parameter recommends the number of items that should be present in the response document.
Only items are counted that are on the first level of the collection in the response document.
Nested objects contained within the explicitly requested items must not be counted.
Minimum = 1. Maximum = 10000. Default = 10.
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 10
style: form
explode: false
intersects:
name: intersects
in: query
description: |-
The optional intersects parameter filters the result Items in the same was as bbox, only with
a GeoJSON Geometry rather than a bbox.
required: false
schema:
$ref: "../core/commons.yaml#/components/schemas/geometryGeoJSON"
style: form
explode: false
schemas:
searchBody:
description: The search criteria
type: object
allOf:
- $ref: "#/components/schemas/bboxFilter"
- $ref: "#/components/schemas/datetimeFilter"
- $ref: "#/components/schemas/intersectsFilter"
- $ref: "#/components/schemas/collectionsFilter"
- $ref: "#/components/schemas/idsFilter"
- $ref: "#/components/schemas/limitFilter"
limit:
type: integer
minimum: 1
example: 10
default: 10
maximum: 10000
description: |-
The optional limit parameter limits the number of items that are presented in the response document.
If the limit parameter value is greater than advertised limit maximum, the server must return the
maximum possible number of items, rather than responding with an error.
Only items are counted that are on the first level of the collection in the response document.
Nested objects contained within the explicitly requested items must not be counted.
Minimum = 1. Maximum = 10000. Default = 10.
bboxFilter:
type: object
description: Only return items that intersect the provided bounding box.
properties:
bbox:
$ref: "../core/commons.yaml#/components/schemas/bbox"
collectionsArray:
type: array
description: |-
Array of Collection IDs to include in the search for items.
Only Item objects in one of the provided collections will be searched.
items:
type: string
ids:
type: array
description: |-
Array of Item ids to return.
items:
type: string
datetimeFilter:
description: An object representing a date+time based filter.
type: object
properties:
datetime:
$ref: "#/components/schemas/datetime_interval"
intersectsFilter:
type: object
description: Only returns items that intersect with the provided polygon.
properties:
intersects:
$ref: "../core/commons.yaml#/components/schemas/geometryGeoJSON"
limitFilter:
type: object
description: Only returns maximum number of results (page size)
properties:
limit:
$ref: "#/components/schemas/limit"
idsFilter:
type: object
description: Only returns items that match the array of given ids
properties:
ids:
$ref: "#/components/schemas/ids"
collectionsFilter:
type: object
description: Only returns the collections specified
properties:
collections:
$ref: "#/components/schemas/collectionsArray"
datetime_interval:
type: string
description: |-
Either a date-time or an interval, open or closed. Date and time expressions
adhere to RFC 3339. Open intervals are expressed using double-dots.
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
Only features that have a temporal property that intersects the value of
`datetime` are selected.
If a feature has multiple temporal properties, it is the decision of the
server whether only a single temporal property is used to determine
the extent or all relevant temporal properties.
example: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"