Add meteor_summary HAVING clause support to rest_api module

rickybassom · Jan 4, 2024 · fdfa9e4 · fdfa9e4
1 parent 726554e
commit fdfa9e4
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 9 deletions.
diff --git a/docs/rest_api.md b/docs/rest_api.md
@@ -40,6 +40,7 @@ The Meteor Summary REST API endpoint is available at:
 
 The API supports the following query parameters:
 - `where`: A SQL SELECT WHERE clause to filter the results. Default is no filter. E.g. `iau_code = 'PER'`.
+- `having`: A SQL HAVING clause to filter the results. Default is no filter. E.g. `participating_stations LIKE '%US0001%'`.
 - `order_by`: A SQL ORDER BY clause to order the results. Default is no order. E.g. `meteor.unique_trajectory_identifier DESC`.
 - `data_shape`: The [shape](https://docs.datasette.io/en/0.64.6/json_api.html#different-shapes) of the data to return. Default is `objects`.
 - `data_format`: The format of the data to return. Default is `json`. `csv` is also supported.
@@ -130,6 +131,30 @@ GET https://explore.globalmeteornetwork.org/gmn_rest_api/meteor_summary?where=da
 }
 ```
 
+#### Get all recorded meteors on the 2nd of January 2019 recorded by station US0001
+
+```sh
+GET https://explore.globalmeteornetwork.org/gmn_rest_api/meteor_summary?where=date(beginning_utc_time)='2019-01-02'&having=participating_stations LIKE '%US0001%'
+{
+    "ok": true,
+    "rows": [
+        {
+            "unique_trajectory_identifier": "20190102091919_1KtJa",
+            ...
+        },
+        {
+            "unique_trajectory_identifier": "20190102092322_UkbbD",
+            ...
+        },
+        {
+            "unique_trajectory_identifier": "20190102101547_tcvE4",
+            ...
+        },
+        ...
+    ],
+    "truncated": false
+}
+```
 
 ## Python API
 
@@ -140,14 +165,15 @@ Data returned from the Meteor Summary endpoint can be loaded into a [Pandas](htt
 from gmn_python_api import gmn_rest_api
 from gmn_python_api import meteor_trajectory_reader
 
-data = gmn_rest_api.get_meteor_summary_data_all(where="iau_code = 'SCC' and beginning_utc_time > '2019-01-01' and beginning_utc_time < '2019-04-05'")
-df = meteor_trajectory_reader.read_data(data, input_camel_case=True)
+data = gmn_rest_api.get_meteor_summary_data_all(where="iau_code = 'SCC' and beginning_utc_time > '2019-01-01' and beginning_utc_time < '2019-04-05'", 
+                                                having="participating_stations LIKE '%US0003%'", 
+                                                order_by="sol_lon_deg DESC")
+df = meteor_trajectory_reader.read_data(data, input_camel_case=True)  # input_camel_case=True is required for the Meteor Summary endpoint
 #                                 Beginning (Julian date)  ... Participating (stations)
 # Unique trajectory (identifier)                           ...                         
-# 20190105074710_89UEE                       2.458489e+06  ...         [US0003, US0009]
-# 20190127130446_CEjBA                       2.458511e+06  ...         [US0001, US0009]
 # 20190128121133_bmAQL                       2.458512e+06  ...         [US0002, US0003]
-# [3 rows x 85 columns]
+# 20190105074710_89UEE                       2.458489e+06  ...         [US0003, US0009]
+# [2 rows x 85 columns]
 ```
 
 See the [gmn_rest_api API Reference section](autoapi/gmn_python_api/gmn_rest_api/index) for more information.
diff --git a/src/gmn_python_api/gmn_rest_api.py b/src/gmn_python_api/gmn_rest_api.py
@@ -24,6 +24,7 @@ class LastModifiedError(Exception):
 
 def get_meteor_summary_data_all(
         where: Optional[str] = None,
+        having: Optional[str] = None,
         order_by: Optional[str] = None,
         last_modified_error_retries: int = 3,
 ) -> List[Dict[str, Any]]:
@@ -32,6 +33,8 @@ def get_meteor_summary_data_all(
 
     :param where: Optional parameter to filter data via a SQL WHERE clause e.g.
      meteor.unique_trajectory_identifier = '20190103131723_6dnE3'.
+    :param having: Optional parameter to filter data via a SQL HAVING clause e.g.
+     participating_stations LIKE '%US0003%'.
     :param order_by: Optional parameter to specify the order of results via a SQL ORDER
      BY clause e.g. meteor.unique_trajectory_identifier DESC.
     :param last_modified_error_retries: Number of times to retry if the data has
@@ -47,7 +50,7 @@ def get_meteor_summary_data_all(
         try_num += 1
         try:
             data = []
-            for data_iter in get_meteor_summary_data_iter(where, order_by):
+            for data_iter in get_meteor_summary_data_iter(where, having, order_by):
                 data.extend(data_iter)
         except LastModifiedError:
             # Data has modified since last request, so we need to start from the
@@ -61,6 +64,7 @@ def get_meteor_summary_data_all(
 
 def get_meteor_summary_data_iter(
         where: Optional[str] = None,
+        having: Optional[str] = None,
         order_by: Optional[str] = None,
 ) -> Iterable[List[Dict[str, Any]]]:
     """
@@ -70,6 +74,8 @@ def get_meteor_summary_data_iter(
 
     :param where: Optional parameter to filter data via a SQL WHERE clause e.g.
      meteor.unique_trajectory_identifier = '20190103131723_6dnE3'.
+    :param having: Optional parameter to filter data via a SQL HAVING clause e.g.
+     participating_stations LIKE '%US0003%'.
     :param order_by: Optional parameter to specify the order of results via a SQL ORDER
      BY clause e.g. meteor.unique_trajectory_identifier DESC.
     :raises: requests.exceptions.HTTPError: If the HTTP response status code is not 200
@@ -79,7 +85,7 @@ def get_meteor_summary_data_iter(
      OK.
     :return: An iterable of json data.
     """
-    data, next_url, initial_last_modified = get_meteor_summary_data(where, order_by)
+    data, next_url, initial_last_modified = get_meteor_summary_data(where, having, order_by)
     yield data
 
     while data and next_url:
@@ -91,6 +97,7 @@ def get_meteor_summary_data_iter(
 
 def get_meteor_summary_data(
         where: Optional[str] = None,
+        having: Optional[str] = None,
         order_by: Optional[str] = None,
 ) -> Tuple[List[Dict[str, Any]], Optional[str], Optional[str]]:
     """
@@ -99,6 +106,8 @@ def get_meteor_summary_data(
 
     :param where: Optional parameter to filter data via a SQL WHERE clause e.g.
      meteor.unique_trajectory_identifier = '20190103131723_6dnE3'.
+    :param having: Optional parameter to filter data via a SQL HAVING clause e.g.
+     participating_stations LIKE '%US0003%'.
     :param order_by: Optional parameter to specify the order of results via a SQL ORDER
      BY clause e.g. meteor.unique_trajectory_identifier DESC.
     :raises: requests.exceptions.HTTPError: If the HTTP response status code is not 200
@@ -114,10 +123,12 @@ def get_meteor_summary_data(
         "data_shape": "objects",
     }
 
-    if order_by:
-        args["order_by"] = order_by
     if where:
         args["where"] = where
+    if having:
+        args["having"] = having
+    if order_by:
+        args["order_by"] = order_by
 
     query_url = METEOR_SUMMARY_QUERY_URL.format(args=urlencode(args))
     return get_data_from_url(query_url)