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.