doc_en.html 14.2 KB
Newer Older
Jerome Touvier's avatar
Jerome Touvier committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>RESIF: RESIFWS: PH5-availability Docs: v1</title>
  <style>
    code{white-space: pre-wrap;}
    span.smallcaps{font-variant: small-caps;}
    span.underline{text-decoration: underline;}
    div.column{display: inline-block; vertical-align: top; width: 50%;}
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    ul.task-list{list-style: none;}
  </style>
<link rel="stylesheet" href="./static/resifws.css"/>
<a href="./local=fr"> <img src="./static/images/fr.png" alt="Anglais - Français"> </a>
</head>
<body>
<p style="text-align:center;"> <img src="./static/images/logoresif.png" alt="logoresif" width="341" height="95"></p>
Jerome Touvier's avatar
Jerome Touvier committed
21
<h1 id="webservice-ph5-availability">Webservice ph5-availability</h1>
Jerome Touvier's avatar
Jerome Touvier committed
22
<h2 id="description">Description</h2>
Jerome Touvier's avatar
Jerome Touvier committed
23
<p>The ph5-availability web service returns detailed timespan information of what time series is available in the PH5 database.</p>
Jerome Touvier's avatar
Jerome Touvier committed
24
25
<p>There are two service query methods:</p>
<p>/extent</p>
Jerome Touvier's avatar
Jerome Touvier committed
26
<p>Produce a list of available time extents (earliest to latest) for selected channels (network, station, location, channel and quality) and time ranges.</p>
Jerome Touvier's avatar
Jerome Touvier committed
27
<p>/query</p>
Jerome Touvier's avatar
Jerome Touvier committed
28
<p>Produce a list of contiguous timespans for selected channels (network, station, location, channel and quality) and time ranges.</p>
Jerome Touvier's avatar
Jerome Touvier committed
29
30
31
32
33
34
35
36
<h2 id="output-format-options">Output format options:</h2>
<ul>
<li>text</li>
<li>json</li>
<li>geocsv</li>
</ul>
<h2 id="query-usage">Query usage</h2>
<p>Query parameters are joined by ampersands “&amp;”, without blank space (see the sample queries). Default values are uppercase. At least one station or one network must be specified.</p>
Jerome Touvier's avatar
Jerome Touvier committed
37
<h3 id="extent-usage">/extent usage</h3>
Jerome Touvier's avatar
Jerome Touvier committed
38
<pre><code>/extent? [channel-options] [date-range-options] [merge-options] [sort-options] [display-options] [format-options] [nodata=404]
Jerome Touvier's avatar
Jerome Touvier committed
39
40
41

where :

Jerome Touvier's avatar
Jerome Touvier committed
42
43
channel-options      ::  [net=&lt;network&gt;] [sta=&lt;station&gt;] [loc=&lt;location&gt;] [cha=&lt;channel&gt;] [quality=&lt;quality&gt;]
date-range-options   ::  [starttime=&lt;date|duration&gt;] [endtime=&lt;date|duration&gt;]
Jerome Touvier's avatar
Jerome Touvier committed
44
45
merge-options        ::  [merge=&lt;quality|samplerate|overlap&gt;]
sort-options         ::  [orderby=&lt;NSLC_TIME_QUALITY_SAMPLERATE|timespancount|timespancount_desc|latestupdate|latestupdate_desc&gt;]
Jerome Touvier's avatar
Jerome Touvier committed
46
47
48
49
display-options      ::  [includerestricted=&lt;true|FALSE&gt;] [limit=&lt;number&gt;]
format-options       ::  [format=&lt;TEXT|geocsv|json|request|zip&gt;]

default values are uppercase</code></pre>
Jerome Touvier's avatar
Jerome Touvier committed
50
<h3 id="query-usage-1">/query usage</h3>
Jerome Touvier's avatar
Jerome Touvier committed
51
<pre><code>/query? [channel-options] [date-range-options] [merge-options] [sort-options] [display-options] [format-options] [nodata=404]
Jerome Touvier's avatar
Jerome Touvier committed
52
53
54

where :

Jerome Touvier's avatar
Jerome Touvier committed
55
56
57
channel-options      ::  [net=&lt;network&gt;] [sta=&lt;station&gt;] [loc=&lt;location&gt;] [cha=&lt;channel&gt;] [quality=&lt;quality&gt;]
date-range-options   ::  [starttime=&lt;date|duration&gt;] [endtime=&lt;date|duration&gt;]
merge-options        ::  [merge=&lt;quality|samplerate|overlap&gt;] [mergegaps=&lt;number&gt;]
Jerome Touvier's avatar
Jerome Touvier committed
58
sort-options         ::  [orderby=&lt;NSLC_TIME_QUALITY_SAMPLERATE|latestupdate|latestupdate_desc&gt;]
Jerome Touvier's avatar
Jerome Touvier committed
59
60
61
62
63
display-options      ::  [includerestricted=&lt;true|FALSE&gt;] [limit=&lt;number&gt;] [show=&lt;latestupdate&gt;]
format-options       ::  [format=&lt;TEXT|geocsv|json|request|zip&gt;]

default values are uppercase</code></pre>
<h2 id="sample-queries">Sample queries</h2>
Jerome Touvier's avatar
Jerome Touvier committed
64
<h3 id="with-extent">with /extent</h3>
Jerome Touvier's avatar
Jerome Touvier committed
65
66
<p><a href="http://ph5ws.resif.fr/fdsnws/availability/1/extent?net=3C&sta=N02,N08&start=2019-01-01&end=2020-01-01">http://ph5ws.resif.fr/fdsnws/availability/1/extent?net=3C&amp;sta=N02,N08&amp;start=2019-01-01&amp;end=2020-01-01</a></p>
<p><a href="http://ph5ws.resif.fr/fdsnws/availability/1/extent?net=3C&sta=N02,N08&start=2019-01-01&end=2020-01-01&show=latestupdate&orderby=timespancount">http://ph5ws.resif.fr/fdsnws/availability/1/extent?net=3C&amp;sta=N02,N08&amp;start=2019-01-01&amp;end=2020-01-01&amp;show=latestupdate&amp;orderby=timespancount</a></p>
Jerome Touvier's avatar
Jerome Touvier committed
67
<h3 id="with-query">with /query</h3>
Jerome Touvier's avatar
Jerome Touvier committed
68
69
<p><a href="http://ph5ws.resif.fr/fdsnws/availability/1/query?net=3C&sta=N02,N08&start=2019-01-01&end=2020-01-01">http://ph5ws.resif.fr/fdsnws/availability/1/query?net=3C&amp;sta=N02,N08&amp;start=2019-01-01&amp;end=2020-01-01</a></p>
<p><a href="http://ph5ws.resif.fr/fdsnws/availability/1/query?net=3C&sta=N02,N08&start=2019-01-01&end=2020-01-01&merge=samplerate&mergegaps=36000">http://ph5ws.resif.fr/fdsnws/availability/1/query?net=3C&amp;sta=N02,N08&amp;start=2019-01-01&amp;end=2020-01-01&amp;merge=samplerate&amp;mergegaps=36000</a></p>
Jerome Touvier's avatar
Jerome Touvier committed
70
<h2 id="detailed-descriptions-of-each-query-parameter">Detailed descriptions of each query parameter</h2>
Jerome Touvier's avatar
Jerome Touvier committed
71
<h3 id="channel-options">Channel options</h3>
Jerome Touvier's avatar
Jerome Touvier committed
72
<table>
Jerome Touvier's avatar
Jerome Touvier committed
73
74
75
76
77
<colgroup>
<col style="width: 10%" />
<col style="width: 8%" />
<col style="width: 81%" />
</colgroup>
Jerome Touvier's avatar
Jerome Touvier committed
78
79
<thead>
<tr class="header">
Jerome Touvier's avatar
Jerome Touvier committed
80
81
<th style="text-align: left;">Parameter</th>
<th style="text-align: left;">Example</th>
Jerome Touvier's avatar
Jerome Touvier committed
82
83
84
85
86
87
88
<th style="text-align: left;">Discussion</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">net[work]</td>
<td style="text-align: left;">FR</td>
Jerome Touvier's avatar
Jerome Touvier committed
89
<td style="text-align: left;">Seismic network name. Accepts wildcards and lists.</td>
Jerome Touvier's avatar
Jerome Touvier committed
90
91
92
93
</tr>
<tr class="even">
<td style="text-align: left;">sta[tion]</td>
<td style="text-align: left;">CIEL</td>
Jerome Touvier's avatar
Jerome Touvier committed
94
<td style="text-align: left;">Station name. Accepts wildcards and lists.</td>
Jerome Touvier's avatar
Jerome Touvier committed
95
96
97
98
</tr>
<tr class="odd">
<td style="text-align: left;">loc[ation]</td>
<td style="text-align: left;">00</td>
Jerome Touvier's avatar
Jerome Touvier committed
99
<td style="text-align: left;">Location code. Use loc=-- for empty location codes. Accepts wildcards and lists.</td>
Jerome Touvier's avatar
Jerome Touvier committed
100
101
102
103
</tr>
<tr class="even">
<td style="text-align: left;">cha[nnel]</td>
<td style="text-align: left;">HHZ</td>
Jerome Touvier's avatar
Jerome Touvier committed
104
<td style="text-align: left;">Channel Code. Accepts wildcards and lists.</td>
Jerome Touvier's avatar
Jerome Touvier committed
105
106
107
</tr>
</tbody>
</table>
Jerome Touvier's avatar
Jerome Touvier committed
108
<h4 id="wildcards-and-lists">Wildcards and lists</h4>
Jerome Touvier's avatar
Jerome Touvier committed
109
110
<ul>
<li><p>Wildcards: the question mark <strong>?</strong> represents any single character, while the asterisk <strong>*</strong> represents zero or more characters.</p></li>
Jerome Touvier's avatar
Jerome Touvier committed
111
<li><p>List: multiple items may be retrieved using a comma-separated list. Wildcards may be included in the list.</p></li>
Jerome Touvier's avatar
Jerome Touvier committed
112
113
114
115
</ul>
<p>For example, with channel codes: channel=EH?,BHZ</p>
<h3 id="date-range-options">Date-range options</h3>
<table>
Jerome Touvier's avatar
Jerome Touvier committed
116
117
118
119
120
<colgroup>
<col style="width: 11%" />
<col style="width: 19%" />
<col style="width: 69%" />
</colgroup>
Jerome Touvier's avatar
Jerome Touvier committed
121
122
<thead>
<tr class="header">
Jerome Touvier's avatar
Jerome Touvier committed
123
124
<th style="text-align: left;">Parameter</th>
<th style="text-align: left;">Example</th>
Jerome Touvier's avatar
Jerome Touvier committed
125
126
127
128
129
130
<th style="text-align: left;">Discussion</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">start[time]</td>
Jerome Touvier's avatar
Jerome Touvier committed
131
132
<td style="text-align: left;">2010-01-10T00:00:00</td>
<td style="text-align: left;">Selects timespan information on or after the specified start time.</td>
Jerome Touvier's avatar
Jerome Touvier committed
133
134
135
</tr>
<tr class="even">
<td style="text-align: left;">end[time]</td>
Jerome Touvier's avatar
Jerome Touvier committed
136
137
<td style="text-align: left;">2011-02-11T01:00:00</td>
<td style="text-align: left;">Selects timespan information on or before the specified end time.</td>
Jerome Touvier's avatar
Jerome Touvier committed
138
139
140
</tr>
</tbody>
</table>
Jerome Touvier's avatar
Jerome Touvier committed
141
142
143
144
145
146
<p>The definition of the time interval may take different forms:</p>
<ul>
<li>a calendar dates, for example starttime=2015-08-12T01:00:00</li>
<li>duration in seconds, for example endtime=7200</li>
<li>the key word “currentutcday” which means midnight of today’s date (UTC time), for example starttime=currentutcday</li>
</ul>
Jerome Touvier's avatar
Jerome Touvier committed
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
<h3 id="merge-options">Merge options</h3>
<table>
<colgroup>
<col style="width: 15%" />
<col style="width: 10%" />
<col style="width: 73%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Parameters</th>
<th style="text-align: left;">Examples</th>
<th style="text-align: left;">Discussion</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">merge</td>
<td style="text-align: left;"></td>
<td style="text-align: left;">Comma separated list (example merge=quality,samplerate).</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">quality</td>
Jerome Touvier's avatar
Jerome Touvier committed
170
<td style="text-align: left;">The timespans of data with differing quality are grouped together.</td>
Jerome Touvier's avatar
Jerome Touvier committed
171
172
173
174
</tr>
<tr class="odd">
<td style="text-align: left;"></td>
<td style="text-align: left;">samplerate</td>
Jerome Touvier's avatar
Jerome Touvier committed
175
<td style="text-align: left;">The timespans of data with differing sample rates are grouped together.</td>
Jerome Touvier's avatar
Jerome Touvier committed
176
177
178
179
180
181
182
183
184
185
186
187
188
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">overlap</td>
<td style="text-align: left;">Not applicable.</td>
</tr>
</tbody>
</table>
<h3 id="output-options">Output options</h3>
<table>
<colgroup>
<col style="width: 10%" />
<col style="width: 7%" />
Jerome Touvier's avatar
Jerome Touvier committed
189
<col style="width: 81%" />
Jerome Touvier's avatar
Jerome Touvier committed
190
191
192
193
194
195
196
197
198
199
200
201
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Parameters</th>
<th style="text-align: left;">Examples</th>
<th style="text-align: left;">Discussion</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">format</td>
<td style="text-align: left;">json</td>
Jerome Touvier's avatar
Jerome Touvier committed
202
<td style="text-align: left;">Specify the output format. Accepted values are text (the default), json, request and zip.</td>
Jerome Touvier's avatar
Jerome Touvier committed
203
204
205
206
207
208
209
210
211
212
213
</tr>
<tr class="even">
<td style="text-align: left;">includerestricted</td>
<td style="text-align: left;">false</td>
<td style="text-align: left;">Display or not restricted data.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">limit</td>
<td style="text-align: left;">integer</td>
<td style="text-align: left;">Limits output to this many rows.</td>
</tr>
Jerome Touvier's avatar
Jerome Touvier committed
214
215
216
217
218
<tr class="even">
<td style="text-align: left;">nodata</td>
<td style="text-align: left;">404</td>
<td style="text-align: left;">Specify which HTTP status code is returned when no data is found (204 or 404)</td>
</tr>
Jerome Touvier's avatar
Jerome Touvier committed
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
</tbody>
</table>
<h3 id="sort-options">Sort options</h3>
<table>
<colgroup>
<col style="width: 8%" />
<col style="width: 23%" />
<col style="width: 67%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Parameters</th>
<th style="text-align: left;">Examples</th>
<th style="text-align: left;">Discussion</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">orderby</td>
<td style="text-align: left;"></td>
<td style="text-align: left;">Sort rows by:</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">nslc_time_quality_samplerate</td>
<td style="text-align: left;">network, station, location, channel, time-range, quality, sample-rate (default)</td>
</tr>
<tr class="odd">
<td style="text-align: left;"></td>
<td style="text-align: left;">latestupdate</td>
<td style="text-align: left;">update-date (past to present), network, station, location, channel, time-range, quality, sample-rate</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">latestupdate_desc</td>
<td style="text-align: left;">update-date (present to past), network, station, location, channel, time-range, quality, sample-rate</td>
</tr>
</tbody>
</table>
Jerome Touvier's avatar
Jerome Touvier committed
258
<h3 id="additional-parameters-for-the-extent-method">Additional parameters for the extent method</h3>
Jerome Touvier's avatar
Jerome Touvier committed
259
260
<table>
<colgroup>
Jerome Touvier's avatar
Jerome Touvier committed
261
<col style="width: 9%" />
Jerome Touvier's avatar
Jerome Touvier committed
262
<col style="width: 16%" />
Jerome Touvier's avatar
Jerome Touvier committed
263
<col style="width: 73%" />
Jerome Touvier's avatar
Jerome Touvier committed
264
265
266
267
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Parameters</th>
Jerome Touvier's avatar
Jerome Touvier committed
268
<th style="text-align: left;">Examples</th>
Jerome Touvier's avatar
Jerome Touvier committed
269
270
271
272
273
<th style="text-align: left;">Discussion</th>
</tr>
</thead>
<tbody>
<tr class="odd">
Jerome Touvier's avatar
Jerome Touvier committed
274
275
276
277
278
279
280
281
282
283
284
285
286
<td style="text-align: left;">orderby</td>
<td style="text-align: left;"></td>
<td style="text-align: left;">Sort rows by:</td>
</tr>
<tr class="even">
<td style="text-align: left;"></td>
<td style="text-align: left;">timespancount</td>
<td style="text-align: left;">number of timespans (small to large), network, station, location, channel, time-range, quality, sample-rate</td>
</tr>
<tr class="odd">
<td style="text-align: left;"></td>
<td style="text-align: left;">timespancount_desc</td>
<td style="text-align: left;">number of timespans (large to small), network, station, location, channel, time-range, quality, sample-rate</td>
Jerome Touvier's avatar
Jerome Touvier committed
287
288
289
</tr>
</tbody>
</table>
Jerome Touvier's avatar
Jerome Touvier committed
290
<h3 id="additional-parameters-the-query-method">Additional parameters the query method</h3>
Jerome Touvier's avatar
Jerome Touvier committed
291
<table>
Jerome Touvier's avatar
Jerome Touvier committed
292
293
294
295
296
<colgroup>
<col style="width: 16%" />
<col style="width: 8%" />
<col style="width: 75%" />
</colgroup>
Jerome Touvier's avatar
Jerome Touvier committed
297
298
299
300
301
302
303
304
305
<thead>
<tr class="header">
<th style="text-align: left;">Parameters</th>
<th style="text-align: left;">Example</th>
<th style="text-align: left;">Discussion</th>
</tr>
</thead>
<tbody>
<tr class="odd">
Jerome Touvier's avatar
Jerome Touvier committed
306
307
308
<td style="text-align: left;">mergegaps</td>
<td style="text-align: left;">3600</td>
<td style="text-align: left;">The timespans which are separated by gaps smaller or equal than the given value (in seconds) are merged together.</td>
Jerome Touvier's avatar
Jerome Touvier committed
309
310
</tr>
<tr class="even">
Jerome Touvier's avatar
Jerome Touvier committed
311
<td style="text-align: left;">show</td>
Jerome Touvier's avatar
Jerome Touvier committed
312
313
314
315
316
<td style="text-align: left;">latestupdate</td>
<td style="text-align: left;">Display the last date of data update.</td>
</tr>
</tbody>
</table>
Jerome Touvier's avatar
Jerome Touvier committed
317
<h2 id="http-post-queries">HTTP POST queries</h2>
Jerome Touvier's avatar
Jerome Touvier committed
318
<p>The general form of a POST is parameter=value pairs, one per line, followed by an arbitrary number of channels and, optionally, time window selection lines:</p>
Jerome Touvier's avatar
Jerome Touvier committed
319
320
321
322
323
324
<p>parameter=&lt;value&gt;<br />
parameter=&lt;value&gt;<br />
parameter=&lt;value&gt;<br />
Net Sta Loc Chan [StartTime EndTime]<br />
Net Sta Loc Chan [StartTime EndTime]<br />
</p>
Jerome Touvier's avatar
Jerome Touvier committed
325
<p>Start time and end times can be specified globally, such as</p>
Jerome Touvier's avatar
Jerome Touvier committed
326
327
328
329
330
331
332
333
334
335
336
337
<p><br />
start=2020-10-01T00:00:00<br />
end=2020-10-01T00:01:00<br />
Net1 Sta1 Loc1 Chan1<br />
Net2 Sta2 Loc2 Chan2<br />
</p>
<p>or per line:</p>
<p><br />
Net1 Sta1 Loc1 Chan1 2020-10-01T00:00:00 2020-10-01T00:01:00<br />
Net2 Sta2 Loc2 Chan2 2020-10-02T00:00:00 2020-10-02T00:02:00<br />
</p>
<p>If not given, the start and end times default to the fully available time range. Additionally, global time ranges can be mixed with individual time ranges.</p>
Jerome Touvier's avatar
Jerome Touvier committed
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
<h2 id="date-and-time-formats">Date and time formats</h2>
<pre><code>YYYY-MM-DDThh:mm:ss[.ssssss] ex. 1997-01-31T12:04:32.123
YYYY-MM-DD ex. 1997-01-31 (a time of 00:00:00 is assumed)

where:

YYYY    :: four-digit year
MM      :: two-digit month (01=January, etc.)
DD      :: two-digit day (01 through 31)
T       :: date-time separator
hh      :: two-digit hour (00 through 23)
mm      :: two-digit number of minutes (00 through 59)
ss      :: two-digit number of seconds (00 through 59)
ssssss  :: one to six-digit number of microseconds (0 through 999999)</code></pre>
</body>
</html>