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 --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 --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 --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 --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 --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 --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 |
|||
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 |
|||
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/fredyou 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.