From a3ea24a4a5435b50e732abee0df2282a2b9783d6 Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Fri, 24 May 2024 14:14:54 -0400 Subject: [PATCH 1/9] Provide introduction to timeseries endpoint --- docs/timeseries.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/timeseries.md b/docs/timeseries.md index def3ed3..4cceb21 100644 --- a/docs/timeseries.md +++ b/docs/timeseries.md @@ -1,6 +1,10 @@ # timeseries -Retrieve time series data from SWOT observations for reaches and nodes. +This page serves to document the timeseries request endpoint for the Hydrocron API. The timeseries endpoint retrieves time series data from SWOT observations for reaches and nodes based on a user request which can include the headers and query parameters documented below under "Request Headers" and "Request Parameteres". + +The timeseries endpoint returns a CSV or GeoJSON response depending on the user request, see "Response Format" below. If something goes wrong the timeseries endpoint returns different response codes to indicate to the user what might have caused an error, see "Response Codes" below. + +For more information on content negotiation via request headers here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation ## Request Headers @@ -219,7 +223,7 @@ Hydrocron includes additional fields beyond the source data shapefile attributes 'crid', 'sword_version', 'collection_shortname','geometry' ``` -## Returns +## Response Format ### Default From 2847f3a79fc6c7bcca272143214da982b0507d9c Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Fri, 24 May 2024 14:27:44 -0400 Subject: [PATCH 2/9] Remove _units in fields list --- docs/timeseries.md | 122 +++++++++++++++++---------------------------- 1 file changed, 47 insertions(+), 75 deletions(-) diff --git a/docs/timeseries.md b/docs/timeseries.md index 4cceb21..ab09197 100644 --- a/docs/timeseries.md +++ b/docs/timeseries.md @@ -133,94 +133,66 @@ The SWOT data fields to return in the request. This is specified in the form of a comma separated list (without any spaces): `fields=reach_id,time_str,wse,slope` +**NOTE: Units are always returned for fields that have corresponding units stored in Hydrocron.** + Hydrocron includes additional fields beyond the source data shapefile attributes, including units fields on measurements, cycle and pass information, and SWORD and collection versions. The complete list of fields that are available through Hydrocron are below: **Reach data fields** ```bash -'reach_id', 'time', 'time_units', 'time_tai', 'time_tai_units', 'time_str', -'p_lat', 'p_lat_units', 'p_lon', 'p_lon_units', 'river_name', -'wse', 'wse_units', 'wse_u', 'wse_u_units', 'wse_r_u', 'wse_r_u_units', -'wse_c', 'wse_c_units', 'wse_c_u', 'wse_c_u_units', -'slope', 'slope_units', 'slope_u_units', 'slope_u', 'slope_r_u', 'slope_r_u_units', -'slope2', 'slope2_units', 'slope2_u', 'slope2_u_units', 'slope2_r_u', 'slope2_r_u_units', -'width', 'width_units', 'width_u', 'width_u_units', -'width_c', 'width_c_units', 'width_c_u', 'width_c_u_units', -'area_total', 'area_tot_u', 'area_det_u_units', 'area_detct', 'area_det_u_units', -'area_det_u', 'area_det_u_units', 'area_wse', 'area_det_u_units', -'d_x_area', 'd_x_area_u', 'area_det_u_units' -'layovr_val', 'layovr_val_units', 'node_dist', 'node_dist_units', -'loc_offset', 'loc_offset_units', 'xtrk_dist', 'xtrk_dist_units' -'dschg_c', 'dschg_c_units', 'dschg_c_u', 'dschg_c_u_units', -'dschg_csf', 'dschg_csf_units', 'dschg_c_q', -'dschg_gc', 'dschg_gc_units', 'dschg_gc_u', 'dschg_gc_u_units', -'dschg_gcsf', 'dschg_gcsf_units', 'dschg_gc_q', -'dschg_m', 'dschg_m_units', 'dschg_m_u', 'dschg_m_u_units', -'dschg_msf', 'dschg_msf_units', 'dschg_m_q', -'dschg_gm', 'dschg_gm_units', 'dschg_gm_u', 'dschg_gm_u_units', -'dschg_gmsf', 'dschg_gmsf_units', 'dschg_gm_q', -'dschg_b', 'dschg_b_units', 'dschg_b_u', 'dschg_b_u_units', -'dschg_bsf', 'dschg_bsf_units', 'dschg_b_q', -'dschg_gb', 'dschg_gb_units', 'dschg_gb_u', 'dschg_gb_u_units', -'dschg_gbsf', 'dschg_gbsf_units', 'dschg_gb_q', -'dschg_h', 'dschg_h_units', 'dschg_h_u', 'dschg_h_u_units', -'dschg_hsf', 'dschg_hsf_units', 'dschg_h_q', -'dschg_gh', 'dschg_gh_units', 'dschg_gh_u', 'dschg_gh_u_units', -'dschg_ghsf', 'dschg_ghsf_units', 'dschg_gh_q', -'dschg_o', 'dschg_o_units', 'dschg_o_u', 'dschg_o_u_units', -'dschg_osf', 'dschg_osf_units', 'dschg_o_q', -'dschg_go', 'dschg_go_units', 'dschg_go_u', 'dschg_go_u_units', -'dschg_gosf', 'dschg_gosf_units', 'dschg_go_q', -'dschg_s', 'dschg_s_units', 'dschg_s_u', 'dschg_s_u_units', -'dschg_ssf', 'dschg_ssf_units', 'dschg_s_q', -'dschg_gs', 'dschg_gs_units', 'dschg_gs_u', 'dschg_gs_u_units', -'dschg_gssf', 'dschg_gssf_units', 'dschg_gs_q', -'dschg_i', 'dschg_i_units', 'dschg_i_u', 'dschg_i_u_units', -'dschg_isf', 'dschg_isf_units', 'dschg_i_q', -'dschg_gi', 'dschg_gi_units', 'dschg_gi_u', 'dschg_gi_u_units', -'dschg_gisf', 'dschg_gisf_units', 'dschg_gi_q','dschg_q_b', 'dschg_gq_b', +'reach_id', 'time', 'time_tai', 'time_str', 'p_lat', 'p_lon', 'river_name', +'wse', 'wse_u', 'wse_r_u', 'wse_c', 'wse_c_u', +'slope', 'slope_u', 'slope_r_u', 'slope2', 'slope2_u', 'slope2_r_u', +'width', 'width_u', 'width_c', 'width_c_u', +'area_total', 'area_tot_u', 'area_detct', 'area_det_u', 'area_wse', +'d_x_area', 'd_x_area_u', +'layovr_val', 'node_dist', 'loc_offset', 'xtrk_dist', +'dschg_c', 'dschg_c_u', 'dschg_csf', 'dschg_c_q', +'dschg_gc', 'dschg_gc_u', 'dschg_gcsf', 'dschg_gc_q', +'dschg_m', 'dschg_m_u', 'dschg_msf', 'dschg_m_q', +'dschg_gm', 'dschg_gm_u', 'dschg_gmsf', 'dschg_gm_q', +'dschg_b', 'dschg_b_u', 'dschg_bsf', 'dschg_b_q', +'dschg_gb', 'dschg_gb_u', 'dschg_gbsf', 'dschg_gb_q', +'dschg_h', 'dschg_h_u', 'dschg_hsf', 'dschg_h_q', +'dschg_gh', 'dschg_gh_u', 'dschg_ghsf', 'dschg_gh_q', +'dschg_o', 'dschg_o_u', 'dschg_osf', 'dschg_o_q', +'dschg_go', 'dschg_go_u', 'dschg_gosf', 'dschg_go_q', +'dschg_s', 'dschg_s_u', 'dschg_ssf', 'dschg_s_q', +'dschg_gs', 'dschg_gs_u', 'dschg_gssf', 'dschg_gs_q', +'dschg_i', 'dschg_i_u', 'dschg_isf', 'dschg_i_q', +'dschg_gi', 'dschg_gi_u', 'dschg_gisf', 'dschg_gi_q', +'dschg_q_b', 'dschg_gq_b', 'reach_q', 'reach_q_b', -'dark_frac', 'dark_frac_units', 'ice_clim_f', 'ice_dyn_f', 'partial_f', -'n_good_nod', 'n_good_nod_units', 'obs_frac_n', 'obs_frac_n_units', -'xovr_cal_q', 'geoid_hght', 'geoid_hght_units', 'geoid_slop', 'geoid_slop_units', -'solid_tide', 'solid_tide_units', 'load_tidef', 'load_tidef_units', -'load_tideg', 'load_tideg_units', 'pole_tide', 'pole_tide_units', -'dry_trop_c', 'dry_trop_c_units', 'wet_trop_c', 'wet_trop_c_units', -'iono_c', 'iono_c_units', 'xovr_cal_c', 'xovr_cal_c_units', -'n_reach_up', 'n_reach_up_units', 'n_reach_dn', 'n_reach_dn_units', -'rch_id_up', 'rch_id_up_units', 'rch_id_dn', 'rch_id_dn_units', -'p_wse', 'p_wse_units', 'p_wse_var', 'p_wse_var_units', -'p_width', 'p_width_units', 'p_wid_var', 'p_wid_var_units', -'p_n_nodes', 'p_n_nodes_units', 'p_dist_out', 'p_dist_out_units', -'p_length', 'p_length_units', 'p_maf', 'p_maf_units', 'p_dam_id', 'p_dam_id_units', -'p_n_ch_max', 'p_n_ch_max_units', 'p_n_ch_mod', 'p_n_ch_mod_units', 'p_low_slp', +'dark_frac', 'ice_clim_f', 'ice_dyn_f', 'partial_f', 'n_good_nod', +'obs_frac_n', 'xovr_cal_q', 'geoid_hght', 'geoid_slop', +'solid_tide', 'load_tidef', 'load_tideg', 'pole_tide', +'dry_trop_c', 'wet_trop_c', 'iono_c', 'xovr_cal_c', +'n_reach_up', 'n_reach_dn', 'rch_id_up', 'rch_id_dn', +'p_wse', 'p_wse_var', 'p_width', 'p_wid_var', 'p_n_nodes', 'p_dist_out', +'p_length', 'p_maf', 'p_dam_id', 'p_n_ch_max', 'p_n_ch_mod', 'p_low_slp', 'cycle_id', 'pass_id', 'continent_id', 'range_start_time', 'range_end_time', -'crid', 'geometry', 'sword_version', 'collection_shortname', 'crid' +'crid', 'geometry', 'sword_version', 'collection_shortname', 'collection_version', +'granuleUR', 'ingest_time' ``` **Node data fields** ```bash -'reach_id', 'node_id', 'time', 'time_units', 'time_tai', 'time_tai_units', 'time_str', -'lat', 'lat_units', 'lon', 'lon_units', 'lat_u', 'lat_u_units', 'lon_u', 'lon_u_units', -'river_name', 'wse', 'wse_units', 'wse_u', 'wse_u_units', 'wse_r_u', 'wse_r_u_units', -'width', 'width_units', 'width_u', 'width_u_units', -'area_total', 'area_total_units', 'area_tot_u', 'area_tot_u_units', -'area_detct', 'area_detct_units', 'area_det_u', 'area_det_u_units', 'area_wse', 'area_wse_units', -'layovr_val', 'layovr_val_units', 'node_dist', 'node_dist_units', 'xtrk_dist', 'xtrk_dist_units', -'flow_angle', 'flow_angle_units', 'node_q', 'node_q_b', -'dark_frac', 'dark_frac_units', 'ice_clim_f', 'ice_dyn_f', 'partial_f', -'n_good_pix', 'n_good_pix_units', 'xovr_cal_q', -'rdr_sig0', 'rdr_sig0_units', 'rdr_sig0_u', 'rdr_sig0_u_units', 'rdr_pol', -'geoid_hght', 'geoid_hght_units', 'solid_tide', 'solid_tide_units', 'load_tidef', 'load_tidef_units', -'load_tideg', 'load_tideg_units', 'pole_tide', 'pole_tide_units', -'dry_trop_c', 'dry_trop_c_units', 'wet_trop_c', 'iono_c', 'iono_c_units', -'xovr_cal_c', 'xovr_cal_c_units', 'p_wse', 'p_wse_units', 'p_wse_var', 'p_wse_var_units', -'p_width', 'p_width_units', 'p_wid_var', 'p_wid_var_units', -'p_dist_out', 'p_dist_out_units', 'p_length', 'p_length_units', -'p_dam_id', 'p_dam_id_units', 'p_n_ch_max', 'p_n_ch_max_units', 'p_n_ch_mod', 'p_n_ch_mod_units', +'reach_id', 'node_id', 'time', 'time_tai', 'time_str', +'lat', 'lon', 'lat_u', 'lon_u', 'river_name', +'wse', 'wse_u', 'wse_r_u', +'width', 'width_u', +'area_total', 'area_tot_u', 'area_detct', 'area_det_u', 'area_wse', +'layovr_val', 'node_dist', 'xtrk_dist', +'flow_angle', 'node_q', 'node_q_b', +'dark_frac', 'ice_clim_f', 'ice_dyn_f', 'partial_f', 'n_good_pix', +'xovr_cal_q', 'rdr_sig0', 'rdr_sig0_u', 'rdr_pol', +'geoid_hght', 'solid_tide', 'load_tidef', 'load_tideg', 'pole_tide', +'dry_trop_c', 'wet_trop_c', 'iono_c', 'xovr_cal_c', +'p_wse', 'p_wse_var', 'p_width', 'p_wid_var', 'p_dist_out', 'p_length', +'p_dam_id', 'p_n_ch_max', 'p_n_ch_mod', 'cycle_id', 'pass_id', 'continent_id', 'range_start_time', 'range_end_time', -'crid', 'sword_version', 'collection_shortname','geometry' +'crid', 'geometry', 'sword_version', 'collection_shortname' ``` ## Response Format From daa73ce3b14696428b5aa33056445123319d1dd2 Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Fri, 24 May 2024 14:40:05 -0400 Subject: [PATCH 3/9] Fix typo --- docs/timeseries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/timeseries.md b/docs/timeseries.md index ab09197..09e273f 100644 --- a/docs/timeseries.md +++ b/docs/timeseries.md @@ -14,7 +14,7 @@ Accept headers: `application/json`, `text/csv`, `application/geo+json` Possible header and request parameter combinations: -- If the Accept header is `text/csv` or `applicatin/geo+json`, the raw CSV or GeoJSON response is returned. +- If the Accept header is `text/csv` or `application/geo+json`, the raw CSV or GeoJSON response is returned. - If the Accept header is `application/json` with an output field of `geojson`, the entire JSON object with metadata including GeoJSON response is returned. - If the Accept header is `application/json` with an output field of `csv`, the entire JSON object with metadata including CSV response is returned. - If the Accept header is `application/json` without an output field, the entire JSON object with metadata including GeoJSON response is returned. From 043fc3cbef5a4b925f135e9aa381041155da3bc9 Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Fri, 24 May 2024 14:51:40 -0400 Subject: [PATCH 4/9] Update examples with Accept headers and compact query parameter --- docs/examples.md | 731 +++++++++++++++++++++++++++++++---------------- 1 file changed, 491 insertions(+), 240 deletions(-) diff --git a/docs/examples.md b/docs/examples.md index c966979..888bc37 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -8,24 +8,43 @@ Search for a single river reach by reach ID. Will return GeoJSON: - { - "status":"200 OK", - "time":844.614, - "hits":10, - "results":{ - "csv":"", - "geojson":{ - "type":"FeatureCollection", - "features":[ - { - "id":"0", - "type":"Feature", - "properties":{ - "reach_id":"78340600051", - "time_str":"2024-01-30T09:38:22Z", - "wse":"3089.5784", - "slope":"-0.0177291808" - }, +```json +{ + "status":"200 OK", + "time":844.614, + "hits":10, + "results":{ + "csv":"", + "geojson":{ + "type":"FeatureCollection", + "features":[ + { + "id":"0", + "type":"Feature", + "properties":{ + "reach_id":"78340600051", + "time_str":"2024-01-30T09:38:22Z", + "wse":"3089.5784", + "slope":"-0.0177291808" + }, + "geometry":{ + "type":"LineString", + "coordinates":[ + [-127.285739,54.942484], + [-127.286202,54.942598], + [-127.286664,54.942767], + [-127.287029,54.942988], + [-127.330039,54.99239] + ] + } + }, + { + "id":"1", + "type":"Feature", + "properties":{ + "reach_id":"78340600051", + "time_str":"2024-02-03T18:33:48Z", + "wse":"1545.616","slope":"-0.0084122704"}, "geometry":{ "type":"LineString", "coordinates":[ @@ -38,50 +57,219 @@ Will return GeoJSON: } }, { - "id":"1", + "id":"5", "type":"Feature", "properties":{ "reach_id":"78340600051", - "time_str":"2024-02-03T18:33:48Z", - "wse":"1545.616","slope":"-0.0084122704"}, - "geometry":{ - "type":"LineString", - "coordinates":[ - [-127.285739,54.942484], - [-127.286202,54.942598], - [-127.286664,54.942767], - [-127.287029,54.942988], - [-127.330039,54.99239] - ] - } + "time_str":"2024-02-24T15:18:54Z", + "wse":"2315.8056", + "slope":"-0.010764612" }, - { - "id":"5", - "type":"Feature", - "properties":{ - "reach_id":"78340600051", - "time_str":"2024-02-24T15:18:54Z", - "wse":"2315.8056", - "slope":"-0.010764612" - }, - "geometry":{ - "type":"LineString", - "coordinates":[ - [-127.285739,54.942484], - [-127.286202,54.942598], - [-127.286664,54.942767], - [-127.287029,54.942988], - [-127.330039,54.99239] - ] - } + "geometry":{ + "type":"LineString", + "coordinates":[ + [-127.285739,54.942484], + [-127.286202,54.942598], + [-127.286664,54.942767], + [-127.287029,54.942988], + [-127.330039,54.99239] + ] } - ] - } + } + ] } - } + } +} +``` ** geometry simplified for example +## Get time series GeoJSON for river node + +Search for a single river node by ID. + +[https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Node&feature_id=12228200110861&start_time=2024-01-25T00:00:00Z&end_time=2024-03-30T00:00:00Z&output=geojson&fields=reach_id,node_id,time_str,wse](https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Node&feature_id=12228200110861&start_time=2024-01-25T00:00:00Z&end_time=2024-03-30T00:00:00Z&output=geojson&fields=reach_id,node_id,time_str,wse) + +Will return GeoJSON: + +```json +{ +"status": "200 OK", +"time": 604.705, +"hits": 9, +"results": { + "csv": "", + "geojson": { + "type": "FeatureCollection", + "features": [ + { + "id": "0", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "2024-01-30T21:19:19Z", + "wse": "677.9232", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + }, + { + "id": "1", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "2024-02-06T08:37:09Z", + "wse": "673.46918", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + }, + { + "id": "2", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "no_data", + "wse": "-999999999999.0", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + }, + { + "id": "3", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "2024-02-20T18:04:24Z", + "wse": "673.69799", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + }, + { + "id": "4", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "2024-02-27T05:22:15Z", + "wse": "674.66235", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + }, + { + "id": "5", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "no_data", + "wse": "-999999999999.0", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + }, + { + "id": "6", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "2024-03-12T14:49:26Z", + "wse": "673.47788", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + }, + { + "id": "7", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "2024-03-19T02:07:17Z", + "wse": "675.23219", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + }, + { + "id": "8", + "type": "Feature", + "properties": { + "reach_id": "12228200111", + "node_id": "12228200110861", + "time_str": "no_data", + "wse": "-999999999999.0", + "wse_units": "m" + }, + "geometry": { + "type": "Point", + "coordinates": [ + 35.149314, + -10.256285 + ] + } + } + ] + } + } +} +``` + ## Get time series CSV for river reach Search for a single river reach by ID. @@ -90,214 +278,277 @@ Search for a single river reach by ID. Will return CSV: - { - "status": "200 OK", - "time": 850.25, - "hits": 12, - "results": { - "csv": "reach_id,time_str,wse,slope,wse_units,slope_units\n78340600051,2024-01-30T09:38:22Z,386.1973,-0.0022161476,m,m/m\n78340600051,2024-02-03T18:33:48Z,386.404,-0.0021030676,m,m/m\n78340600051,no_data,-999999999999.0,-999999999999.0,m,m/m\n78340600051,2024-02-13T16:56:05Z,386.4593,-0.0024754944,m,m/m\n78340600051,2024-02-20T06:23:27Z,407.3638,-0.0021535548,m,m/m\n78340600051,2024-02-24T15:18:54Z,385.9676,-0.001794102,m,m/m\n78340600051,no_data,-999999999999.0,-999999999999.0,m,m/m\n78340600051,2024-03-05T13:41:09Z,385.6664,-0.0024497335,m,m/m\n78340600051,2024-03-12T03:08:30Z,408.4634,-0.0021388862,m,m/m\n78340600051,2024-03-16T12:03:56Z,386.5635,-0.0021972558,m,m/m\n78340600051,no_data,-999999999999.0,-999999999999.0,m,m/m\n78340600051,2024-03-26T10:26:13Z,386.2493,-0.0021548483,m,m/m\n", - "geojson": {} - } +```json +{ + "status": "200 OK", + "time": 850.25, + "hits": 12, + "results": { + "csv": "reach_id,time_str,wse,slope,wse_units,slope_units\n78340600051,2024-01-30T09:38:22Z,386.1973,-0.0022161476,m,m/m\n78340600051,2024-02-03T18:33:48Z,386.404,-0.0021030676,m,m/m\n78340600051,no_data,-999999999999.0,-999999999999.0,m,m/m\n78340600051,2024-02-13T16:56:05Z,386.4593,-0.0024754944,m,m/m\n78340600051,2024-02-20T06:23:27Z,407.3638,-0.0021535548,m,m/m\n78340600051,2024-02-24T15:18:54Z,385.9676,-0.001794102,m,m/m\n78340600051,no_data,-999999999999.0,-999999999999.0,m,m/m\n78340600051,2024-03-05T13:41:09Z,385.6664,-0.0024497335,m,m/m\n78340600051,2024-03-12T03:08:30Z,408.4634,-0.0021388862,m,m/m\n78340600051,2024-03-16T12:03:56Z,386.5635,-0.0021972558,m,m/m\n78340600051,no_data,-999999999999.0,-999999999999.0,m,m/m\n78340600051,2024-03-26T10:26:13Z,386.2493,-0.0021548483,m,m/m\n", + "geojson": {} } +} +``` -## Get time series GeoJSON for river node +## Get time series CSV for river node Search for a single river node by ID. -[https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Node&feature_id=12228200110861&start_time=2024-01-25T00:00:00Z&end_time=2024-03-30T00:00:00Z&output=geojson&fields=reach_id,node_id,time_str,wse](https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Node&feature_id=12228200110861&start_time=2024-01-25T00:00:00Z&end_time=2024-03-30T00:00:00Z&output=geojson&fields=reach_id,node_id,time_str,wse) +[https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Node&feature_id=28311800020621&start_time=2024-01-25T00:00:00Z&end_time=2024-03-27T00:00:00Z&output=csv&fields=node_id,reach_id,time_str,wse,geometry](https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Node&feature_id=28311800020621&start_time=2024-01-25T00:00:00Z&end_time=2024-03-27T00:00:00Z&output=csv&fields=node_id,reach_id,time_str,wse,geometry) -Will return GeoJSON: +Will return CSV: - { +```json +{ "status": "200 OK", - "time": 604.705, - "hits": 9, + "time": 500.644, + "hits": 11, + "results": { + "csv": "node_id,reach_id,time_str,wse,geometry,wse_units\n28311800020621,28311800021,2024-01-28T08:15:21Z,-15.54433,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-01-31T21:37:09Z,-15.63838,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-07T06:37:36Z,-999999999999.0,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-10T19:59:24Z,-14.46997,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-18T05:00:26Z,-15.99808,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-21T18:22:14Z,-999999999999.0,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-28T03:22:42Z,-999999999999.0,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-03-02T16:44:30Z,-16.80069,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-03-10T01:45:29Z,-15.65594,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-03-13T15:07:16Z,-999999999999.0,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-03-23T13:29:33Z,-16.73133,POINT (45.949474 48.354881),m\n", + "geojson": {} + } +} +``` + +## Accept headers + +### Get time series for application/geo+json Accept Header + +```bash +curl --header "Accept: application/geo+json" --location 'https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Reach&feature_id=63470800171&start_time=2024-02-01T00:00:00%2b00:00&end_time=2024-10-30T00:00:00%2b00:00&fields=reach_id,time_str,wse' +``` + +** Note the output query parameter is not specified in the request. + +Will return GeoJSON response: + +```json +{ + "type": "FeatureCollection", + "features": [ + { + "id": "0", + "type": "Feature", + "properties": { + "reach_id": [ + "63470800171", + "63470800171" + ], + "time_str": [ + "2024-02-01T02:26:50Z", + "2024-02-08T13:48:41Z" + ], + "wse": [ + "3386.9332", + "1453.4136" + ], + "width": [ + "383.19271200000003", + "501.616464" + ], + "wse_units": [ + "m", + "m" + ], + "width_units": [ + "m", + "m" + ] + }, + "geometry": { + "type": "LineString", + "coordinates": [ + [ + -45.845445, + -16.166559 + ] + ] + } + } + ] +} +``` + +** geometry simplified for example + +### Get time series for text/csv Accept Header + +```bash +curl --header "Accept: text/csv" --location 'https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Reach&feature_id=63470800171&start_time=2024-02-01T00:00:00%2b00:00&end_time=2024-10-30T00:00:00%2b00:00&fields=reach_id,time_str,wse' +``` + +** Note the output query parameter is not specified in the request. + +Will return a CSV response: + +```json +"reach_id,time_str,wse,width,wse_units,width_units\n63470800171,2024-02-01T02:26:50Z,3386.9332,383.19271200000003,m,m\n63470800171,2024-02-08T13:48:41Z,1453.4136,501.616464,m,m\n" +``` + +## Compact request + +### Get time series for application/json with compact=True + +```bash +curl --location 'https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Reach&feature_id=63470800171&start_time=2024-02-01T00:00:00%2b00:00&end_time=2024-10-30T00:00:00%2b00:00&fields=reach_id,time_str,wse&compact=true' +``` + +Will return a compacted JSON response with metadata: + +```json +{ + "status": "200 OK", + "time": 737.056, + "hits": 2, "results": { "csv": "", "geojson": { "type": "FeatureCollection", "features": [ { - "id": "0", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "2024-01-30T21:19:19Z", - "wse": "677.9232", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } - }, - { - "id": "1", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "2024-02-06T08:37:09Z", - "wse": "673.46918", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } - }, - { - "id": "2", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "no_data", - "wse": "-999999999999.0", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } - }, - { - "id": "3", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "2024-02-20T18:04:24Z", - "wse": "673.69799", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } - }, - { - "id": "4", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "2024-02-27T05:22:15Z", - "wse": "674.66235", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } - }, - { - "id": "5", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "no_data", - "wse": "-999999999999.0", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } - }, - { - "id": "6", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "2024-03-12T14:49:26Z", - "wse": "673.47788", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } - }, - { - "id": "7", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "2024-03-19T02:07:17Z", - "wse": "675.23219", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } - }, - { - "id": "8", - "type": "Feature", - "properties": { - "reach_id": "12228200111", - "node_id": "12228200110861", - "time_str": "no_data", - "wse": "-999999999999.0", - "wse_units": "m" - }, - "geometry": { - "type": "Point", - "coordinates": [ - 35.149314, - -10.256285 - ] - } + "id": "0", + "type": "Feature", + "properties": { + "reach_id": [ + "63470800171", + "63470800171" + ], + "time_str": [ + "2024-02-01T02:26:50Z", + "2024-02-08T13:48:41Z" + ], + "wse": [ + "3386.9332", + "1453.4136" + ], + "wse_units": [ + "m", + "m" + ] + }, + "geometry": { + "type": "LineString", + "coordinates": [ + [ + -45.845445, + -16.166559 + ] + ] + } } ] - } } } +} +``` -## Get time series CSV for river node +** geometry simplified for example -Search for a single river node by ID. +### Get time series for application/geo+json -[https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Node&feature_id=28311800020621&start_time=2024-01-25T00:00:00Z&end_time=2024-03-27T00:00:00Z&output=csv&fields=node_id,reach_id,time_str,wse,geometry](https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Node&feature_id=28311800020621&start_time=2024-01-25T00:00:00Z&end_time=2024-03-27T00:00:00Z&output=csv&fields=node_id,reach_id,time_str,wse,geometry) +```bash +curl -v --header "Accept: application/geo+json" --location 'https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Reach&feature_id=63470800171&start_time=2024-02-01T00:00:00%2b00:00&end_time=2024-10-30T00:00:00%2b00:00&fields=reach_id,time_str,wse' +``` -Will return CSV: +** Note compacted response returned by default as no compact query parameter is specified. - { - "status": "200 OK", - "time": 500.644, - "hits": 11, - "results": { - "csv": "node_id,reach_id,time_str,wse,geometry,wse_units\n28311800020621,28311800021,2024-01-28T08:15:21Z,-15.54433,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-01-31T21:37:09Z,-15.63838,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-07T06:37:36Z,-999999999999.0,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-10T19:59:24Z,-14.46997,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-18T05:00:26Z,-15.99808,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-21T18:22:14Z,-999999999999.0,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-02-28T03:22:42Z,-999999999999.0,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-03-02T16:44:30Z,-16.80069,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-03-10T01:45:29Z,-15.65594,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-03-13T15:07:16Z,-999999999999.0,POINT (45.949474 48.354881),m\n28311800020621,28311800021,2024-03-23T13:29:33Z,-16.73133,POINT (45.949474 48.354881),m\n", - "geojson": {} +Will return compacted GeoJSON response: + +```json +{ + "type": "FeatureCollection", + "features": [ + { + "id": "0", + "type": "Feature", + "properties": { + "reach_id": [ + "63470800171", + "63470800171" + ], + "time_str": [ + "2024-02-01T02:26:50Z", + "2024-02-08T13:48:41Z" + ], + "wse": [ + "3386.9332", + "1453.4136" + ], + "wse_units": [ + "m", + "m" + ] + }, + "geometry": { + "type": "LineString", + "coordinates": [ + [ + -45.845445, + -16.166559 + ] + ] + } } - } + ] +} +``` + +** geometry simplified for example + +### Get time series for application/geo+json with compact=False + +```bash +curl --header "Accept: application/geo+json" --location 'https://soto.podaac.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=Reach&feature_id=63470800171&start_time=2024-02-01T00:00:00%2b00:00&end_time=2024-10-30T00:00:00%2b00:00&fields=reach_id,time_str,wse&compact=false' +``` + +** Note compact query parameter is specified. + +Will return a GeoJSON response that is not compacted: + +```json +{ + "type": "FeatureCollection", + "features": [ + { + "id": "0", + "type": "Feature", + "properties": { + "reach_id": "63470800171", + "time_str": "2024-02-01T02:26:50Z", + "wse": "3386.9332", + "wse_units": "m" + }, + "geometry": { + "type": "LineString", + "coordinates": [ + [ + -45.845445, + -16.166559 + ] + ] + } + }, + { + "id": "1", + "type": "Feature", + "properties": { + "reach_id": "63470800171", + "time_str": "2024-02-08T13:48:41Z", + "wse": "1453.4136", + "wse_units": "m" + }, + "geometry": { + "type": "LineString", + "coordinates": [ + [ + -45.845445, + -16.166559 + ] + ] + } + } + ] +} +``` + +** geometry simplified for example From 621426b81cc04c71889fedb814f91305f54cb73e Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Fri, 24 May 2024 15:05:17 -0400 Subject: [PATCH 5/9] Add issue to changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index aef03f1..a2e0484 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added + - Issue 183 - Update documentation examples and provide a brief intro to the timeseries endpoint - Issue 100 - Add option to 'compact' GeoJSON result into single feature - Issue 101 - Add support for HTTP Accept header - Issue 102 - Enable compression for API Responses From 7e8c57341b54a58f2bc565772cfde3e54e429457 Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Fri, 24 May 2024 15:11:26 -0400 Subject: [PATCH 6/9] Fix typo in timeseries documentation --- docs/timeseries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/timeseries.md b/docs/timeseries.md index 09e273f..45aa606 100644 --- a/docs/timeseries.md +++ b/docs/timeseries.md @@ -1,6 +1,6 @@ # timeseries -This page serves to document the timeseries request endpoint for the Hydrocron API. The timeseries endpoint retrieves time series data from SWOT observations for reaches and nodes based on a user request which can include the headers and query parameters documented below under "Request Headers" and "Request Parameteres". +This page serves to document the timeseries request endpoint for the Hydrocron API. The timeseries endpoint retrieves time series data from SWOT observations for reaches and nodes based on a user request which can include the headers and query parameters documented below under "Request Headers" and "Request Parameters". The timeseries endpoint returns a CSV or GeoJSON response depending on the user request, see "Response Format" below. If something goes wrong the timeseries endpoint returns different response codes to indicate to the user what might have caused an error, see "Response Codes" below. From 4c3dd6e0ee7a542f8df4e5b5ec221b2a20fd51f7 Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Fri, 24 May 2024 15:20:35 -0400 Subject: [PATCH 7/9] Update pymysql --- poetry.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/poetry.lock b/poetry.lock index f6ca35e..6becf77 100644 --- a/poetry.lock +++ b/poetry.lock @@ -3189,13 +3189,13 @@ testutils = ["gitpython (>3)"] [[package]] name = "pymysql" -version = "1.1.0" +version = "1.1.1" description = "Pure Python MySQL Driver" optional = false python-versions = ">=3.7" files = [ - {file = "PyMySQL-1.1.0-py3-none-any.whl", hash = "sha256:8969ec6d763c856f7073c4c64662882675702efcb114b4bcbb955aea3a069fa7"}, - {file = "PyMySQL-1.1.0.tar.gz", hash = "sha256:4f13a7df8bf36a51e81dd9f3605fede45a4878fe02f9236349fd82a3f0612f96"}, + {file = "PyMySQL-1.1.1-py3-none-any.whl", hash = "sha256:4de15da4c61dc132f4fb9ab763063e693d521a80fd0e87943b9a453dd4c19d6c"}, + {file = "pymysql-1.1.1.tar.gz", hash = "sha256:e127611aaf2b417403c60bf4dc570124aeb4a57f5f37b8e95ae399a42f904cd0"}, ] [package.extras] From 086ec7ad6e63c5a69f9c7534efa439b8d286fd28 Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Fri, 24 May 2024 15:28:42 -0400 Subject: [PATCH 8/9] Update pymysql --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index d128938..aa7e23b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,7 +18,7 @@ packages = [ python = "^3.10" six = "^1.16.0" boto3 = "^1.28.2" -pymysql = "^1.1.0" +pymysql = "^1.1.1" geopandas = "^0.13.2" earthaccess = "^0.5.3" shapely = "^2.0.1" From 297ae7a1d6cf18618bb732d39b55e6683a0b4989 Mon Sep 17 00:00:00 2001 From: Nikki <17799906+nikki-t@users.noreply.github.com> Date: Thu, 30 May 2024 16:27:53 -0400 Subject: [PATCH 9/9] Provide clarity on accept headers and request parameter fields --- docs/examples.md | 2 ++ docs/timeseries.md | 9 +++++---- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/examples.md b/docs/examples.md index 888bc37..32897f9 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -312,6 +312,8 @@ Will return CSV: ## Accept headers +See the [documentation on the timeseries endpoint](timeseries.md) for an explanation of Accept headers. + ### Get time series for application/geo+json Accept Header ```bash diff --git a/docs/timeseries.md b/docs/timeseries.md index 45aa606..ca6e8ef 100644 --- a/docs/timeseries.md +++ b/docs/timeseries.md @@ -4,12 +4,14 @@ This page serves to document the timeseries request endpoint for the Hydrocron A The timeseries endpoint returns a CSV or GeoJSON response depending on the user request, see "Response Format" below. If something goes wrong the timeseries endpoint returns different response codes to indicate to the user what might have caused an error, see "Response Codes" below. -For more information on content negotiation via request headers here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation +For more information on using request headers when working with an API like Hydrocron programatically, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation ## Request Headers ### Accept +Accept headers provide more control over the output that is returned by Hydrocron. You can pass the `Accept` header in your request to return a specific response format. + Accept headers: `application/json`, `text/csv`, `application/geo+json` Possible header and request parameter combinations: @@ -19,6 +21,7 @@ Possible header and request parameter combinations: - If the Accept header is `application/json` with an output field of `csv`, the entire JSON object with metadata including CSV response is returned. - If the Accept header is `application/json` without an output field, the entire JSON object with metadata including GeoJSON response is returned. - If the Accept header is none of the accepted types then a 415 Unsupported is returned. +- If no Accept header is passed in the request then the default is to return `application/json` with metadata. The `output` field is used to determine whether a GeoJSON or CSV response is returned in the `results` field of the response. Example GeoJSON request and response: @@ -133,9 +136,7 @@ The SWOT data fields to return in the request. This is specified in the form of a comma separated list (without any spaces): `fields=reach_id,time_str,wse,slope` -**NOTE: Units are always returned for fields that have corresponding units stored in Hydrocron.** - -Hydrocron includes additional fields beyond the source data shapefile attributes, including units fields on measurements, cycle and pass information, and SWORD and collection versions. The complete list of fields that are available through Hydrocron are below: +Hydrocron includes additional fields beyond the source data shapefile attributes, including units fields on measurements, cycle and pass information, and SWORD and collection versions. **NOTE: Units are always returned for fields that have corresponding units stored in Hydrocron, they do not need to be requested.** The complete list of input fields that are available through Hydrocron are below: **Reach data fields**