Responses

Note

curl command line tool is used to request the API in this documentation. curl is available in many operating systems by default. If not, you can get curl from https://curl.se/ or using a package management tool specific to your operating system (brew, apt, …).

Content Negotiation, Formats

Principles

A simple style of content negotiation is used to match the format requested by the client and the capability of the server.

The client can specify the desired response format by including the HTTP header Accept. If no Accept header is present in the request, or if the requested content type is not available, the server will provide the response in JSON format by default.

The following table provides a list of the supported HTTP Accept header types:

Accept Header

Format

Note

application/json

JSON

Simplified JSON view of the PDS4 metadata label. Contains “flattened” PDS4 properties extracted from the metadata label

application/xml

XML

Same as application/json, but in an XML

application/ vnd.nasa.pds.pds4+json

JSON

JSON response containing the full PDS4 metadata translated to JSON, along with some additional supplemental

application/ vnd.nasa.pds.pds4+xml

XML

Same as application/vnd.nasa.pds.pds4+json, but in an XML format. This response format contains the original PDS4 labels.

application/kvp+json

JSON

JSON response containing key-value-pairs for the applicable metadata.

text/csv

CSV

Returns a CSV table containing values for the parameters in the request. If no parameters were specified in the request, a default set is returned. The first row of the CSV is a header that describes the values in each column.

text/html

HTML

JSON response embedded in an HTML body. This format is provided for requests coming from the browers (e.g. Google Chrome) URL bar.

application/vnd.nasa.pds.pds4+json and application/vnd.nasa.pds.pds4+xml have been chosen to comply with RFC6838

Examples

application/json

The request:

 curl -L --get 'https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:insight_rad::2.1' \
     --header 'Accept: application/json'

Returns

{
    "id": "urn:nasa:pds:insight_rad::2.1",
    "type": "Product_Bundle",
    "title": "Mars InSight Lander Radiometer Data Archive",
    "start_date_time": "2018-05-05T00:00:00Z",
    "stop_date_time": "3000-01-01T00:00:00.000Z",
    "investigations": [
        {
            "id": "urn:nasa:pds:context:investigation:mission.insight",
            "href": "http://localhost:8080/products/urn:nasa:pds:context:investigation:mission.insight"
        }
    ],
    "observing_system_components": [
        {
            "id": "urn:nasa:pds:context:instrument_host:spacecraft.insight",
            "href": "http://localhost:8080/products/urn:nasa:pds:context:instrument_host:spacecraft.insight"
        },
        {
            "id": "urn:nasa:pds:context:instrument:radiometer.insight",
            "href": "http://localhost:8080/products/urn:nasa:pds:context:instrument:radiometer.insight"
        }
    ],
    "targets": [
        {
            "id": "urn:nasa:pds:context:target:planet.mars",
            "href": "http://localhost:8080/products/urn:nasa:pds:context:target:planet.mars"
        }
    ],
    "metadata": {
        "label_url": "/data/bundle_insight_rad.xml",
        "update_date_time": "2018-02-01T00:00:00Z",
        "version": "2.1"
    },
    "properties": {
        "pds:Stream_Text.pds:name": [
            "Introduction to the Radiometer Data Bundle"
        ],
        "pds:Modification_Detail.pds:description": [
            "Pre-peer review version",
            "First release",
            "The collections urn:nasa:pds:insight_rad:data_calibrated and urn:nasa:pds:insight_rad:data_derived were added to this bundle with InSight Release 1b.",
            "Changed Observing_System_Component name in this label from RAD to RADIOMETER to match context product name. Expanded Citation_Information description."
        ],
        "..."
        "pds:Investigation_Area.pds:type": [
            "Mission"
        ]
    }
}

Properties follow the Fields Dot Notation.

application/xml

The request:

curl -L --get 'https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:insight_rad::2.1' \
   --header 'Accept: application/xml'

Returns:

<PdsProduct xmlns="http://pds.nasa.gov/api">
    <id>urn:nasa:pds:insight_rad::2.1</id>
    <type>Product_Bundle</type>
    <title>Mars InSight Lander Radiometer Data Archive</title>
    <description/>
    <start_date_time>2018-05-05T00:00:00Z</start_date_time>
    <stop_date_time>3000-01-01T00:00:00.000Z</stop_date_time>
    <investigations>
        <investigations>
            <title/>
            <id>urn:nasa:pds:context:investigation:mission.insight</id>
            <href>http://localhost:8080/products/urn:nasa:pds:context:investigation:mission.insight</href>
            <type/>
            <description/>
        </investigations>
    </investigations>
    <observing_system_components>
        <observing_system_components>
            <title/>
            <id>urn:nasa:pds:context:instrument_host:spacecraft.insight</id>
            <href>http://localhost:8080/products/urn:nasa:pds:context:instrument_host:spacecraft.insight</href>
            <type/>
            <description/>
        </observing_system_components>
        <observing_system_components>
            <title/>
            <id>urn:nasa:pds:context:instrument:radiometer.insight</id>
            <href>http://localhost:8080/products/urn:nasa:pds:context:instrument:radiometer.insight</href>
            <type/>
            <description/>
        </observing_system_components>
    </observing_system_components>
    <targets>
        <targets>
            <title/>
            <id>urn:nasa:pds:context:target:planet.mars</id>
            <href>http://localhost:8080/products/urn:nasa:pds:context:target:planet.mars</href>
            <type/>
            <description/>
        </targets>
    </targets>
    <metadata xmlns="">
        <archive_status xmlns="http://pds.nasa.gov/api"/>
        <creation_date_time xmlns="http://pds.nasa.gov/api"/>
        <label_url xmlns="http://pds.nasa.gov/api">/data/bundle_insight_rad.xml</label_url>
        <update_date_time xmlns="http://pds.nasa.gov/api">2018-02-01T00:00:00Z</update_date_time>
        <version xmlns="http://pds.nasa.gov/api">2.1</version>
    </metadata>
    <properties>
        <pds:Stream_Text.pds:name>Introduction to the Radiometer Data Bundle</pds:Stream_Text.pds:name>
        <pds:Modification_Detail.pds:description>Pre-peer review version</pds:Modification_Detail.pds:description>
        ...
        <pds:Investigation_Area.pds:type>Mission</pds:Investigation_Area.pds:type>
    </properties>
</PdsProduct>

Tag names under properties follow the Fields Dot Notation.

application/vnd.nasa.pds.pds4+json

The request:

curl -L --get 'https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:insight_rad::2.1' \
   --header 'Accept: application/vnd.nasa.pds.pds4+json'

Returns:

{
    "id": "urn:nasa:pds:insight_rad::2.1",
    "meta": {
        "node_name": "PDS_ENG",
        "ops:Label_File_Info": {
            "ops:file_name": "bundle_insight_rad.xml",
            "ops:file_ref": "/data/bundle_insight_rad.xml",
            "ops:creation_date": "2020-01-15T17:40:30Z",
            "ops:file_size": "6805",
            "ops:md5_checksum": "adfd86bbf2573c37d862e27e08f332db"
        },
        "ops:Data_Files": [
            {
                "ops:file_name": "readme.txt",
                "ops:file_ref": "/data/readme.txt",
                "ops:creation_date": "2020-01-03T17:58:09Z",
                "ops:file_size": "1114",
                "ops:md5_checksum": "192de32c12437c180a9e14d60fe4b89a",
                "ops:mime_type": "text/plain"
            }
        ],
        "ops:Tracking_Meta": [
            {
                "ops:archive_status": "archived"
            }
        ]
    },
    "pds4": {
        "Product_Bundle": {
            "Identification_Area": {
                "product_class": "Product_Bundle",
                "Modification_History": {
                    "Modification_Detail": [
                        {
                            "modification_date": "2018-02-01",
                            "description": "Pre-peer review version",
                            "version_id": 0.1
                        },
                        {
                            "modification_date": "2019-04-22",
                            "description": "First release",
                            "version_id": 1
                        },
                        "..."
                    ]
                },
                "information_model_version": "1.11.0.0",
                "logical_identifier": "urn:nasa:pds:insight_rad",
                "version_id": 2.1,
                "Citation_Information": {
                    "publication_year": 2018,
                    "description": "The InSight Radiometer data bundle consists of data in three collections:\r\n                data_raw, data_calibrated, and data_derived.\r\n                The bundle also includes the HP3/RAD Software Interface Specification in \r\n                the HP3/RAD document collection.",
                    "author_list": "InSight RAD Science Team",
                    "doi": "10.17189/1517568"
                },
                "title": "Mars InSight Lander Radiometer Data Archive"
            },
            "..."
        }
    }
}

pds4 property contains a translation in JSON of the PDS4 XML Label.

In addition a meta object contains fields related to the managed of the record in the PDS Registry, see ops Namespace for details.

application/vnd.nasa.pds.pds4+xml

The request:

curl -L --get 'https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:insight_rad::2.1' \
   --header 'Accept: application/vnd.nasa.pds.pds4+xml'

Returns:

<pds_api:product xmlns:pds_api="http://pds.nasa.gov/api" xmlns:ops="https://pds.nasa.gov/pds4/ops/v1">
    <pds_api:id>urn:nasa:pds:insight_rad::2.1</pds_api:id>
    <pds_api:meta>
        <node_name>PDS_ENG</node_name>
        <ops:Label_File_Info>
            <ops:file_name>bundle_insight_rad.xml</ops:file_name>
            <ops:file_ref>/data/bundle_insight_rad.xml</ops:file_ref>
            <ops:creation_date>2020-01-15T17:40:30Z</ops:creation_date>
            <ops:file_size>6805</ops:file_size>
            <ops:md5_checksum>adfd86bbf2573c37d862e27e08f332db</ops:md5_checksum>
        </ops:Label_File_Info>
        <ops:Data_Files>
            <ops:Data_Files>
                <ops:file_name>readme.txt</ops:file_name>
                <ops:file_ref>/data/readme.txt</ops:file_ref>
                <ops:creation_date>2020-01-03T17:58:09Z</ops:creation_date>
                <ops:file_size>1114</ops:file_size>
                <ops:md5_checksum>192de32c12437c180a9e14d60fe4b89a</ops:md5_checksum>
                <ops:mime_type>text/plain</ops:mime_type>
            </ops:Data_Files>
        </ops:Data_Files>
        <ops:Tracking_Meta>
            <ops:Tracking_Meta>
                <ops:archive_status>archived</ops:archive_status>
            </ops:Tracking_Meta>
        </ops:Tracking_Meta>
    </pds_api:meta>
    <pds_api:pds4>
        <Product_Bundle
    xmlns="http://pds.nasa.gov/pds4/pds/v1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://pds.nasa.gov/pds4/pds/v1 https://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_1B00.xsd">
            <Identification_Area>
                <logical_identifier>urn:nasa:pds:insight_rad</logical_identifier>
                <version_id>2.1</version_id>
                <title>Mars InSight Lander Radiometer Data Archive</title>
                <information_model_version>1.11.0.0</information_model_version>
                <product_class>Product_Bundle</product_class>
                <Citation_Information>
                    <author_list>InSight RAD Science Team</author_list>
                    <publication_year>2018</publication_year>
                    <doi>10.17189/1517568</doi>
                    <description>
                The InSight Radiometer data bundle consists of data in three collections:
                data_raw, data_calibrated, and data_derived.
                The bundle also includes the HP3/RAD Software Interface Specification in
                the HP3/RAD document collection.
            </description>
                </Citation_Information>
               ...
            </Identification_Area>
           ...
        </Product_Bundle>
    </pds_api:pds4>
</pds_api:product>

The tag pds_api:pds4 contains the XML PDS4 label.

In addition a meta object contains fields related to the managed of the record in the PDS Registry, see ops Namespace for details.

application/kvp+json


This format is useful when one only need a few fields from the metadata.

The request:

curl -L --get 'https://pds.nasa.gov/api/search/1/products?limit=10&fields=lidvid&fields=title' \
   --header 'Accept: application/kvp+json'

Returns:

{
 "summary": {
     "q": "",
     "hits": 17,
     "took": 55,
     "start": 0,
     "limit": 10,
     "sort": [],
     "properties": [
         "lidvid",
         "title"
     ]
 },
 "data": [
     {
         "lidvid": "urn:nasa:pds:insight_rad:data_derived::7.0",
         "title": "InSight RAD Derived Data Collection"
     },
     {
         "lidvid": "urn:nasa:pds:insight_rad:data_raw::8.0",
         "title": "InSight RAD Raw Data Collection"
     },
     "..."
 ]
}

Properties follow the Fields Dot Notation when they are coming from the PDS4 standard or the ops Namespace.

text/csv

This format is useful when one only need a few fields from the metadata.

The request:

curl -L --get 'https://pds.nasa.gov/api/search/1/products?limit=10&fields=lidvid&fields=title' \
   --header 'Accept: text/csv'

Returns:

lidvid,title
"urn:nasa:pds:insight_rad:data_derived::7.0","InSight RAD Derived Data Collection"
"urn:nasa:pds:insight_rad:data_raw::8.0","InSight RAD Raw Data Collection"
"urn:nasa:pds:insight_rad:data_derived:hp3_rad_der_00014_20181211_073042::1.0","InSight HP3 Radiometer Experiment Derived Product:hp3_rad_der_00014_20181211_073042"
...

Open Data

NOT IMPLEMENTED

See <https://project-open-data.cio.gov/>_ and example of application at <https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#open-data>_

ops Namespace

The response content, in addition to the information found in the PDS4 label contains some attributes related to the management of the datasets in the registry.

A dedicated namespace ops is used to manage these attributes in the API, for example: ops:Label_File_Info.ops:file_name in Fields Dot Notation used in JSON or in XML tag <ops:Label_File_Info><ops:file_name>.

The list of ops attributes is given in the following table:

Class

Attributes

Description

Example

Data_File_Info

creation_date_time

2021-09-10T15:58:03Z

file_name

collection_document_hp3rad.csv

file_ref

link

file_size

in bytes

137

md5_checksum

cd24cbc46c45ed023f039b3e2beb6606

mime_type

text/plain

Label_File_Info

creation_date_time

2021-09-10T15:58:03Z

file_name

collection_document_hp3rad.xml

file_ref

link

file_size

in bytes

8655

md5_checksum

aa584be2cd34d1899f19d39c23cccba1

Harvest_Info

harvest_date_time

2021-11-16T06:03:30.952311900Z

node_name

PDS_GEO

Tracking_Meta

archive_status

archived

No Results Found

2 cases are considered:

  • When there are not results to a search query, applying parameters to the URL (e.g. ?q='lid eq fred', keyword…), you will get an empty array (for example [] in JSON) as a result.

  • When the URL itself cannot be resolved, as in /products/fred you will get a 404 error (not found).

Missing Values

Properties with empty or null values should be dropped from the JSON response unless the user asked specifically for the field (through field API parameter). In this case the value must be null, without quotes.

Rationale

If a property is optional or has an empty or null value, consider dropping the property from the JSON, unless there’s a strong semantic reason for its existence (taken from this discussion)

Following interactions with OGC/EDR specification group: see ticket

We choose null without quotes for missing values of fields explicitly requested by the user.

We conform to EDR specification for this aspect, see EDR parameter response

This should not be mistaken for an actual PDS4 value since missing values in PDS4 labels. are detailed with a nil:reason attribute.