Skip to content

Commit fc93a61

Browse files
cholmescholmes
committed
2 parents a9f39dc + f246bb2 commit fc93a61

File tree

4 files changed

+66
-71
lines changed

4 files changed

+66
-71
lines changed

‎api-spec/STAC-fragment.yaml‎

Lines changed: 9 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -125,17 +125,18 @@ components:
125125
name: time
126126
in: query
127127
description: >-
128-
A time range search that accepts a JSON search object.
129-
128+
Either a date-time or a period string that adheres to RFC3339. Examples:
129+
* A date-time: "2018-02-12T23:20:50Z"
130+
* A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
130131
Only features that have a temporal property that intersects the value of
131132
`time` are selected.
132-
133133
If a feature has multiple temporal properties, it is the decision of the
134-
server whether only a single temporal property is used to determine the
135-
extent or all relevant temporal properties.
134+
server whether only a single temporal property is used to determine
135+
the extent or all relevant temporal properties.
136136
required: false
137137
schema:
138-
$ref: '#/components/schemas/timeRange'
138+
type: string
139+
style: form
139140
explode: false
140141
schemas:
141142
searchBody:
@@ -151,9 +152,7 @@ components:
151152
- 39
152153
- -105
153154
- 41
154-
time:
155-
gt: "2018-03-15T00:00:00.000Z"
156-
lt: "2018-06-01T00:00:00.000Z"
155+
time: "2018-03-15T00:00:00.000Z"
157156
bboxFilter:
158157
type: object
159158
description: Only return items that intersect the provided bounding box.
@@ -165,7 +164,7 @@ components:
165164
type: object
166165
properties:
167166
time:
168-
$ref: '#/components/schemas/timeRange'
167+
$ref: '#/components/parameters/time'
169168
intersectsFilter:
170169
type: object
171170
description: Only returns items that intersect with the provided polygon.
@@ -221,17 +220,6 @@ components:
221220
description: >-
222221
A single date-time string that adheres to RFC3339, for example
223222
1985-04-12T23:20:50.52Z
224-
timeRange:
225-
type: object
226-
properties:
227-
gt:
228-
$ref: '#/components/schemas/time'
229-
lt:
230-
$ref: '#/components/schemas/time'
231-
gte:
232-
$ref: '#/components/schemas/time'
233-
lte:
234-
$ref: '#/components/schemas/time'
235223
itemCollection:
236224
type: object
237225
required:

‎api-spec/STAC-standalone.yaml‎

Lines changed: 8 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -150,27 +150,19 @@ components:
150150
time:
151151
name: time
152152
in: query
153-
description: >-
154-
A time range search that accepts a JSON search object.
155-
153+
description: |
154+
Either a date-time or a period string that adheres to RFC3339. Examples:
155+
* A date-time: "2018-02-12T23:20:50Z"
156+
* A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
156157
Only features that have a temporal property that intersects the value of
157158
`time` are selected.
158-
159159
If a feature has multiple temporal properties, it is the decision of the
160-
server whether only a single temporal property is used to determine the
161-
extent or all relevant temporal properties.
160+
server whether only a single temporal property is used to determine
161+
the extent or all relevant temporal properties.
162162
required: false
163163
schema:
164-
type: object
165-
properties:
166-
gt:
167-
$ref: '#/components/schemas/time'
168-
lt:
169-
$ref: '#/components/schemas/time'
170-
gte:
171-
$ref: '#/components/schemas/time'
172-
lte:
173-
$ref: '#/components/schemas/time'
164+
type: string
165+
style: form
174166
explode: false
175167
collectionId:
176168
name: collectionId

‎api-spec/WFS3core+STAC.yaml‎

Lines changed: 7 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -308,26 +308,18 @@ components:
308308
name: time
309309
in: query
310310
description: >-
311-
A time range search that accepts a JSON search object.
312-
311+
Either a date-time or a period string that adheres to RFC3339. Examples:
312+
* A date-time: "2018-02-12T23:20:50Z"
313+
* A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
313314
Only features that have a temporal property that intersects the value of
314315
`time` are selected.
315-
316316
If a feature has multiple temporal properties, it is the decision of the
317-
server whether only a single temporal property is used to determine the
318-
extent or all relevant temporal properties.
317+
server whether only a single temporal property is used to determine
318+
the extent or all relevant temporal properties.
319319
required: false
320320
schema:
321-
type: object
322-
properties:
323-
gt:
324-
$ref: '#/components/schemas/time'
325-
lt:
326-
$ref: '#/components/schemas/time'
327-
gte:
328-
$ref: '#/components/schemas/time'
329-
lte:
330-
$ref: '#/components/schemas/time'
321+
type: string
322+
style: form
331323
explode: false
332324
collectionId:
333325
name: collectionId

‎api-spec/filters.md‎

Lines changed: 42 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ and are required to be supported.
66

77
The filters are designed to be simple as possible for a client to construct. To match the default JSON responses the
88
encoding of filters is done by default in JSON. This allows clients to support filtering without additional tools. The
9-
search enpoint will accept application/json format queries, and GET on the collection will support URL encoded JSON. POST
9+
search endpoint will accept application/json format queries, and GET on the collection will support URL encoded JSON. POST
1010
search the is recommended way to filter results to avoid the URL encoding issues that can happen with GET.
1111

1212
Searching using POST will accept a JSON object where the top level keys are specifying which type of filter
@@ -20,33 +20,60 @@ This query will perform an intersects operation on the geometry values of the it
2020
objects may provide a bbox property in addition to geometry, but it should not be used for the bbox filter since
2121
it is an optional field in GeoJSON.
2222

23-
example
23+
###### examples: ######
24+
POST:
2425
```
2526
{
2627
"bbox": [-180,-90,180,90]
2728
}
2829
```
2930

30-
The temporal query will be based on [RFC 3339](https://tools.ietf.org/html/rfc3339) and should support time ranges as well as equality. To support range
31-
queries, we are using a simple JSON based language. Ranges will be specified as an object with keys indicating the comparison to use.
31+
GET:
32+
```
33+
?bbox=[-180,-90,180,90]
34+
```
35+
36+
The temporal query will be based on [RFC 3339](https://tools.ietf.org/html/rfc3339) and should support time ranges as well as equality. It will compare against the datetime property of the STAC Item.
37+
38+
###### To find items with an exact date ######
39+
40+
POST:
41+
```
42+
{
43+
"time": "2007-03-01T13:00:00Z"
44+
}
45+
```
3246

33-
Equality is specified as `{"time": "2018-03-20T16:11:44.353Z"}`
34-
Before is `{"time":{"lt":"2018-03-20T16:11:44.353Z"}}`
35-
After is `{"time":{"gt":"2018-03-20T16:11:44.353Z"}}`
36-
Before with Equality is `{"time":{"lte":"2018-03-20T16:11:44.353Z"}}`
37-
After with Equality is `{"time":{"gte":"2018-03-20T16:11:44.353Z"}}`
47+
GET:
48+
```
49+
?time=2007-03-01T13:00:00Z
50+
```
3851

39-
These queries can be combined to specify a search range:
52+
###### To specify a time range, use the interval syntax: ######
4053

54+
POST:
4155
```
4256
{
43-
"time": {
44-
"gt":"2018-03-15T00:00:00.000Z",
45-
"lt":"2018-06-01T00:00:00.000Z",
46-
}
47-
}
57+
"time": "2007-03-01T13:00:00Z/2008-05-11T15:30:00Z"
58+
}
4859
```
4960

61+
GET:
62+
```
63+
?time=2007-03-01T13:00:00Z/2008-05-11T15:30:00Z
64+
```
65+
66+
###### Specify intervals using durations: ######
67+
68+
`2007-03-01T13:00:00Z/P1Y2M10DT2H30M`
69+
70+
If time is a period with out a start or end date, the end date is assigned to now:
71+
72+
`P1Y2M10DT2H30M` is the same as `"P1Y2M10DT2H30M/" + new Date().toISOString()`
73+
74+
75+
76+
5077
Filter Extensions
5178
-----------------
5279

@@ -124,10 +151,6 @@ Some additional extensions that have been discussed:
124151
CQL support for generic queries:
125152
`{"CQL": "CQL Select String"}`
126153

127-
Time intervals:
128-
`{"time": "P1Y"}` Assume Duration/now if no time specified?
129-
`{"time": "2018/P1M"}` Any time in january of 2018
130-
131154

132155
Adding filters to search
133156
------------------------

0 commit comments

Comments
 (0)