Adds Get Closest Image endpoint

hvpy/api_groups/official_clients/get_closest_image.py

@@ -0,0 +1,41 @@
+from typing import Optional
+from datetime import datetime
+
+from pydantic import validator
+
+from hvpy.io import HvpyParameters, OutputType
+from hvpy.utils import convert_date_to_isoformat
+
+
+class getClosestImageInputParameters(HvpyParameters):
+    """
+    Handles the input parameters of the getClosestImage API.
+
+    Attributes
+    ----------
+    {Shared}
+    date : datetime.datetime
+        Date and time of the image.
+    sourceId : int
+        Unique image datasource identifier.
+    callback : str, optional
+        Wrap the response object in a function call of your choosing.
+
+    References
+    ----------
+    * `<https://api.helioviewer.org/docs/v2/api/api_groups/official_clients.html#getclosestimage>`__
+    {Shared}
+    """
+
+    date: datetime
+    sourceId: int
+    callback: Optional[str] = None
+    _date_validator = validator("date", allow_reuse=True)(convert_date_to_isoformat)
+
+    def get_output_type(self) -> OutputType:
+        """
+        Returns the output type of the API call.
+        """
+        if self.callback is None:
+            return OutputType.JSON
+        return OutputType.STRING

hvpy/api_groups/official_clients/tests/test_get_closest_image.py

@@ -0,0 +1,29 @@
+from datetime import datetime
+
+import pytest
+
+from hvpy import getClosestImage
+from hvpy.api_groups.official_clients.get_closest_image import getClosestImageInputParameters
+
+
+def test_json_res():
+    response = getClosestImage(date=datetime(2014, 1, 1, 23, 59, 59), sourceId=14)
+    assert isinstance(response, dict)
+
+
+def test_str_res():
+    response = getClosestImage(date=datetime(2014, 1, 1, 23, 59, 59), sourceId=14, callback="callback")
+    assert isinstance(response, str)
+    assert response.startswith("callback")
+
+
+def test_error_handling():
+    with pytest.raises(TypeError, match="missing 1 required positional argument: 'date'"):
+        getClosestImage(sourceId=14)
+    with pytest.raises(TypeError, match="missing 1 required positional argument: 'sourceId'"):
+        getClosestImage(date=datetime(2014, 1, 1, 23, 59, 59))
+
+
+def test_url_property():
+    params = getClosestImageInputParameters(date=datetime(2014, 1, 1, 23, 59, 59), sourceId=14)
+    assert params.url == "https://api.helioviewer.org/v2/getClosestImage/"

hvpy/facade.py

@@ -5,7 +5,7 @@
 from hvpy.parameters import *
 from hvpy.utils import add_shared_docstring
 
-__all__ = ["getJP2Image", "getJP2Header", "getJPXClosestToMidPoint", "getJPX", "getStatus"]
+__all__ = ["getJP2Image", "getJP2Header", "getJPXClosestToMidPoint", "getJPX", "getStatus", "getClosestImage"]
 
 
 @add_shared_docstring(getJP2ImageInputParameters)
@@ -146,3 +146,31 @@ def getStatus() -> Union[bytes, str, Dict[str, Any]]:
     """
     params = getStatusInputParameters()
     return execute_api_call(input_parameters=params)
+
+
+@add_shared_docstring(getClosestImageInputParameters)
+def getClosestImage(
+    date: datetime,
+    sourceId: int,
+    callback: Optional[str] = None,
+) -> Union[bytes, str, Dict[str, Any]]:
+    """
+    Find the image data that is closest to the requested date/time. Return the
+    associated metadata from the helioviewer database and the XML header of the
+    JPEG2000 image file.
+
+    Parameters
+    ----------
+    {Insert}
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> from hvpy import getClosestImage
+    >>> getClosestImage(
+    ...     date=datetime(2014,1,1,23,59,59),
+    ...     sourceId=14,
+    ... )
+    {'id': '32271665', 'date': '2014-01-02 00:00:03', 'name': 'AIA 335', 'scale': 0.5899606831770233, 'width': 4096, 'height': 4096, 'refPixelX': 2048.5, 'refPixelY': 2048.5, 'sunCenterOffsetParams': [], 'layeringOrder': 1}
+    """
+    params = getClosestImageInputParameters(date=date, sourceId=sourceId, callback=callback)
+    return execute_api_call(input_parameters=params)

hvpy/parameters.py

@@ -3,11 +3,13 @@
 from hvpy.api_groups.jpeg2000.get_jpx import getJPXInputParameters
 from hvpy.api_groups.jpeg2000.get_jpx_closest_to_mid_point import getJPXClosestToMidPointInputParameters
 from hvpy.api_groups.jpeg2000.get_status import getStatusInputParameters
+from hvpy.api_groups.official_clients.get_closest_image import getClosestImageInputParameters
 
 __all__ = [
     "getJP2ImageInputParameters",
     "getJP2HeaderInputParameters",
     "getJPXClosestToMidPointInputParameters",
     "getJPXInputParameters",
     "getStatusInputParameters",
+    "getClosestImageInputParameters",
 ]