diff --git a/docs/source/data-access/index.rst b/docs/source/data-access/index.rst index c923d163f..b36b9cf7f 100644 --- a/docs/source/data-access/index.rst +++ b/docs/source/data-access/index.rst @@ -11,6 +11,7 @@ interacting with the API programmatically. It is the preferred way to use the AP :maxdepth: 1 imap-data-access + spice-files Users may also download, upload, and query via the REST API directly through the browser, or via `curl` commands. The `REST API Specification`_ section describes the various endpoints that are supported, and how to use them. @@ -18,7 +19,7 @@ The `REST API Specification`_ section describes the various endpoints that are s *Note: Several sections and links begin with* [WIP]. *As development on the API is ongoing, this indicates that the full implementation of the functionality is yet to be completed.* -The API can be accessed from the following URL [WIP]: https://api.dev.imap-mission.com +The API can be accessed from the following URL [WIP]: https://api.imap-mission.com Command Line Utility -------------------- @@ -162,7 +163,7 @@ for example, with ``IMAP_DATA_DIR=/data:`` Data Access URL ^^^^^^^^^^^^^^^ -To change the default URL that the package accesses, you can set the environment variable ``IMAP_DATA_ACCESS_URL`` or within the package ``imap_data_access.config["DATA_ACCESS_URL"]``. The default is the development server (``https://api.dev.imap-mission.com``). +To change the default URL that the package accesses, you can set the environment variable ``IMAP_DATA_ACCESS_URL`` or within the package ``imap_data_access.config["DATA_ACCESS_URL"]``. The default is the production server (``https://api.imap-mission.com``). File Validation --------------- @@ -227,7 +228,7 @@ REST API Specification .. code-block:: bash - curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/upload/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts + curl -X GET -H "Accept: application/json" https://api.imap-mission.com/upload/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts **Possible Responses:** @@ -252,7 +253,7 @@ REST API Specification .. code-block:: bash - curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/download/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts + curl -X GET -H "Accept: application/json" https://api.imap-mission.com/download/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts **Possible Responses:** @@ -270,7 +271,7 @@ REST API Specification .. code-block:: bash - curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/query?instrument=swe&data_level=l0&descriptor=sci&start_date=20240105&end_date=20240105&extension=pkts + curl -X GET -H "Accept: application/json" https://api.imap-mission.com/query?instrument=swe&data_level=l0&descriptor=sci&start_date=20240105&end_date=20240105&extension=pkts **Possible Responses:** diff --git a/docs/source/data-access/openapi.yml b/docs/source/data-access/openapi.yml index a59a19140..459855054 100644 --- a/docs/source/data-access/openapi.yml +++ b/docs/source/data-access/openapi.yml @@ -1,7 +1,7 @@ openapi: 3.0.0 servers: - - description: Development IMAP SDC Server -host: https://api.dev.imap-mission.com/ + - description: Production IMAP SDC Server +host: https://api.imap-mission.com/ info: version: "0.1.0" title: IMAP SDC API @@ -229,4 +229,181 @@ paths: type: array items: type: string - format: uri \ No newline at end of file + format: uri + + '/spice-query': + get: + tags: + - SPICE Query + summary: Query for SPICE kernel metadata + operationId: spice-query + parameters: + - in: query + name: file_name + description: | + The name of a specific SPICE kernel file (e.g. ``naif0012.tls``). + required: false + schema: + type: string + - in: query + name: start_time + description: | + Coverage start time in TDB seconds since J2000. Returns kernels whose + coverage ends on or after this time. + required: false + schema: + type: string + - in: query + name: end_time + description: | + Coverage end time in TDB seconds since J2000. Returns kernels whose + coverage begins on or before this time. + required: false + schema: + type: string + - in: query + name: type + description: | + The SPICE kernel type to filter by. Accepted values are: + ``leapseconds``, ``planetary_constants``, ``imap_frames``, + ``science_frames``, ``spacecraft_clock``, ``earth_attitude``, + ``planetary_ephemeris``, ``ephemeris_reconstructed``, + ``ephemeris_nominal``, ``ephemeris_predicted``, ``ephemeris_90days``, + ``ephemeris_long``, ``ephemeris_launch``, ``attitude_history``, + ``attitude_predict``, ``pointing_attitude``. + required: false + schema: + type: string + - in: query + name: latest + description: | + If ``True``, only return the latest version of each kernel matching + the other query parameters. + required: false + schema: + type: string + - in: query + name: start_ingest_date + description: | + Filter results to kernels ingested on or after this date, in the + format ``YYYYMMDD``. + required: false + schema: + type: string + - in: query + name: end_ingest_date + description: | + Filter results to kernels ingested on or before this date, in the + format ``YYYYMMDD``. + required: false + schema: + type: string + responses: + '200': + description: Successful query — returns a list of SPICE kernel metadata objects + content: + application/json: + schema: + type: array + items: + type: object + '400': + description: Invalid query parameter or parameter value + content: + application/json: + schema: + type: string + + '/metakernel': + get: + tags: + - SPICE Query + summary: Retrieve a metakernel or list of SPICE kernel filenames for a time range + operationId: metakernel + parameters: + - in: query + name: start_time + description: | + Coverage start time. Accepts either TDB seconds since J2000 or a date + string in the format ``YYYYMMDD``. + required: true + schema: + type: string + - in: query + name: end_time + description: | + Coverage end time. Accepts either TDB seconds since J2000 or a date + string in the format ``YYYYMMDD``. + required: true + schema: + type: string + - in: query + name: spice_path + description: | + Root path for the SPICE directory. This path is prepended to all kernel file + locations in the returned metakernel. If omitted the paths are left + relative. Only applicable if ``list_files``` is ``False``. + required: false + schema: + type: string + - in: query + name: list_files + description: | + If ``True``, return only a list of kernel filenames instead of a full + metakernel file. + required: false + schema: + type: string + - in: query + name: require_coverage + description: | + If ``True``, the request will fail with a HTTP ``422`` status if there + are any gaps in coverage for the requested time range. + required: false + schema: + type: string + - in: query + name: file_types + description: | + Comma-separated list of kernel types to include. If omitted, all + available kernel types are included. Accepted values are: + ``leapseconds``, ``planetary_constants``, ``imap_frames``, + ``science_frames``, ``spacecraft_clock``, ``earth_attitude``, + ``planetary_ephemeris``, ``ephemeris_reconstructed``, + ``ephemeris_nominal``, ``ephemeris_predicted``, ``ephemeris_90days``, + ``ephemeris_long``, ``ephemeris_launch``, ``attitude_history``, + ``attitude_predict``, ``pointing_attitude``. + required: false + schema: + type: string + responses: + '200': + description: | + Successful response. Returns a metakernel file (text/plain) when + ``list_files`` is ``False`` (default), or a JSON array of kernel + filenames when ``list_files`` is ``True``. + content: + text/plain: + schema: + type: string + application/json: + schema: + type: array + items: + type: string + '404': + description: No kernel files found for the requested time range + content: + application/json: + schema: + type: string + '422': + description: | + Coverage gaps detected when ``require_coverage=True``. The response + body contains a list of the gap intervals. + content: + application/json: + schema: + type: array + items: + type: object \ No newline at end of file diff --git a/docs/source/data-access/spice-files.rst b/docs/source/data-access/spice-files.rst new file mode 100644 index 000000000..2a840ddb6 --- /dev/null +++ b/docs/source/data-access/spice-files.rst @@ -0,0 +1,220 @@ +SPICE Files +=========== + +The IMAP SDC provides two REST API endpoints for accessing SPICE kernel data: +``/spice-query`` for querying kernel metadata and ``/metakernel`` for retrieving +a ready-to-use metakernel (or a list of kernel filenames) that covers a +requested time range. + +Both endpoints are accessible from the base URL: ``https://api.imap-mission.com`` + +.. _spice-query-endpoint: + +SPICE Query +----------- + +The ``/spice-query`` endpoint returns metadata for SPICE kernels stored in the +SDC database. Results can be filtered by kernel type, time range, ingestion +date, or filename. + +.. openapi:: openapi.yml + :group: + :include: /spice-query + +**Example Usage:** + +.. code-block:: bash + + # Query for all attitude_history kernels covering a time range + curl -X GET -H "Accept: application/json" \ + "https://api.imap-mission.com/spice-query?start_time=315576066&end_time=4575787269&type=attitude_history" + + # Query for a specific kernel by filename + curl -X GET -H "Accept: application/json" \ + "https://api.imap-mission.com/spice-query?file_name=naif0012.tls" + + # Query for the latest version of the spacecraft_clock kernel + curl -X GET -H "Accept: application/json" \ + "https://api.imap-mission.com/spice-query?type=spacecraft_clock&latest=True" + +**Possible Responses:** + +.. code-block:: json + + [ + { + "file_name": "ck/imap_2025_274_2025_276_001.ah.bc", + "file_root": "imap_2025_274_2025_276_.ah.bc", + "kernel_type": "attitude_history", + "version": 1, + "min_date_j2000": 812631669.2765242, + "max_date_j2000": 812725268.1910387, + "file_intervals_j2000": [ + [ + 812631669.2765242, + 812725268.1910387 + ] + ], + "min_date_datetime": "2025-10-01, 23:00:00", + "max_date_datetime": "2025-10-03, 00:59:59", + "file_intervals_datetime": [ + [ + "2025-10-01T23:00:00.094178+00:00", + "2025-10-03T00:59:59.008694+00:00" + ] + ], + "min_date_sclk": "1/0497055600:00000", + "max_date_sclk": "1/0497149199:00000", + "file_intervals_sclk": [ + [ + "1/0497055600:00000", + "1/0497149199:00000" + ] + ], + "sclk_kernel": "/tmp/naif0012.tls", + "lsk_kernel": "/tmp/imap_sclk_0147.tsc", + "ingestion_date": "2026-04-06, 23:57:54", + "timestamp": 1775519874 + }, + ] + +.. code-block:: json + + {"statusCode": 400, "body": " is not a valid query parameter. Valid query parameters are: ['file_name', 'start_time', 'end_time', 'type', 'latest', 'start_ingest_date', 'end_ingest_date']"} + +.. _metakernel-endpoint: + +Metakernel +---------- + +The ``/metakernel`` endpoint builds and returns a SPICE metakernel covering a +requested time range. By default the response is a ``.tm`` metakernel file that +can be loaded directly with ``spiceypy.furnsh()``. Passing ``list_files=True`` +returns a JSON list of kernel filenames instead. + +.. openapi:: openapi.yml + :group: + :include: /metakernel + +**Example Usage:** + +.. code-block:: bash + + # Retrieve a metakernel covering a time range for selected kernel types + curl -X GET -H "Accept: application/json" \ + "https://api.imap-mission.com/metakernel?start_time=797949057&end_time=798035454&file_types=leapseconds,attitude_history" + + # Get only a list of kernel filenames (no metakernel wrapper) + curl -X GET -H "Accept: application/json" \ + "https://api.imap-mission.com/metakernel?start_time=797949057&end_time=798035454&file_types=leapseconds,spacecraft_clock&list_files=True" + + # Retrieve a metakernel with a custom spice_path prefix in the output + curl -X GET -H "Accept: application/json" \ + "https://api.imap-mission.com/metakernel?start_time=797949057&end_time=798035454&spice_path=/my/path/imap" + +**Possible Responses:** + +Metakernel file (default, ``list_files`` omitted or ``False``): + +.. code-block:: text + + \begintext + + This is the most up to date Metakernel as of + 2026-04-13 18:19:21.912444+00:00. + + This attempts to cover data from + 797949057 to 798035454 + seconds since J2000. + + \begindata + + KERNELS_TO_LOAD = ( 'lsk/naif0012.tls', + 'fk/imap_130.tf', + 'fk/imap_science_120.tf', + 'sclk/imap_sclk_0147.tsc', + 'spk/de440.bsp' + ) + + \begintext + +List of filenames (``list_files=True``): + +.. code-block:: json + + ["naif0012.tls", "imap_130.tf", "imap_science_120.tf", "imap_sclk_0147.tsc", "de440.bsp"] + +Coverage gap error (``require_coverage=True`` and gaps exist): + +.. code-block:: json + + { + "statusCode": 422, + "body": { + "leapseconds_category": [], + "planetary_constants_category": [], + "imap_frames_category": [], + "science_frames_category": [], + "spacecraft_clock_category": [], + "earth_attitude_category": [], + "planetary_ephemeris_category": [], + "spacecraft_ephemeris_category": [[797990001, 798035454]], + "spacecraft_attitude_category": [[797949057, 797990000]], + "pointing_attitude_category": [] + } + } + +Each key is a SPICE kernel category. Empty lists indicate full coverage; non-empty +lists contain one or more ``[start_time, end_time]`` intervals (in TDB seconds +since J2000) where no kernel was found. + +No files found: + +.. code-block:: json + + {"statusCode": 404, "body": "No files found."} + +Kernel Types +------------ + +The following kernel type values are accepted by both the ``type`` parameter of +``/spice-query`` and the ``file_types`` parameter of ``/metakernel``: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Kernel Type + - Description + * - ``leapseconds`` + - Leapseconds kernel (LSK) + * - ``planetary_constants`` + - Planetary constants kernel (PCK) + * - ``imap_frames`` + - IMAP spacecraft frames kernel (FK) + * - ``science_frames`` + - Science instrument frames kernel (FK) + * - ``spacecraft_clock`` + - Spacecraft clock kernel (SCLK) + * - ``earth_attitude`` + - Earth attitude kernel + * - ``planetary_ephemeris`` + - Planetary ephemeris kernel (SPK) + * - ``ephemeris_reconstructed`` + - Reconstructed spacecraft ephemeris (SPK) + * - ``ephemeris_nominal`` + - Nominal spacecraft ephemeris (SPK) + * - ``ephemeris_predicted`` + - Predicted spacecraft ephemeris (SPK) + * - ``ephemeris_90days`` + - 90-day spacecraft ephemeris (SPK) + * - ``ephemeris_long`` + - Long-term spacecraft ephemeris (SPK) + * - ``ephemeris_launch`` + - Launch ephemeris (SPK) + * - ``attitude_history`` + - Historical spacecraft attitude kernel (CK) + * - ``attitude_predict`` + - Predicted spacecraft attitude kernel (CK) + * - ``pointing_attitude`` + - Pointing attitude kernel (CK)