Search API Cookbook
Recipes for various search scenarios using the PDS Search API.
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, …).
Search For Product Versions
Recipes for searching for the latest version of a product, or all versions of a product, including superseded versions.
Warning
Since our servers are not fully populated with all PDS data sets, the examples presented in this user guide may return empty results or 404 (Not Found) errors. If there is a data set you would like added, please submit a request to the PDS Help Desk for assistance.
Search the Latest Version of a Product
To retrieve the latest versions of product urn:nasa:pds:mars2020.spice, the request is:
The request:
https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:mars2020.spice
which is equivalent to:
https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:mars2020.spice/latest
Search for All Versions of a Product
To retrieve all the versions of product urn:nasa:pds:mars2020.spice, the request is:
https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:mars2020.spice/all
Search By Specific Metadata
The following recipes describe some example queries of the Search API using the q= query parameter showing some more complex use cases for querying PDS data.
Warning
Since our servers are not fully populated with all PDS data sets, the examples presented in this user guide may return empty results or 404 (Not Found) errors. If there is a data set you would like added, please contact the PDS Help Desk for assistance.
Search by Processing Level
Search for the 10 latest collections which processing level is “Raw”:
Query: (pds:Primary_Result_Summary.pds:processing_level eq "Raw")
curl -L --get 'https://pds.nasa.gov/api/search/1/products' \
--data-urlencode 'limit=10' \
--data-urlencode 'q=(pds:Primary_Result_Summary.pds:processing_level eq "Raw")'
Search Observational Products by Target
Search for all Observational Products targeting Bennu:
Query: (ref_lid_target eq "urn:nasa:pds:context:target:asteroid.101955_bennu")
curl -L --get 'https://pds.nasa.gov/api/search/1/products' \
--data-urlencode 'q=(ref_lid_target eq "urn:nasa:pds:context:target:asteroid.101955_bennu")'
Search by Reference
Search all products which are referring to a given LID:
curl -L --get 'https://pds.nasa.gov/api/search/1/products' \
--data-urlencode 'limit=200' \
--data-urlencode 'q=((pds:Internal_Reference.pds:lid_reference eq "urn:nasa:pds:context:investigation:mission.orex") or (pds:Internal_Reference.pds:lid_reference like "urn:nasa:pds:context:investigation:mission.orex::*"))' | json_pp
Search for DOIs
Digital Object Identifiers are useful to cite the data you are using in your research. DOIs for PDS data are minted for PDS4 Bundles, PDS4 Collections, PDS4 Documents, and PDS3 Data Sets. The level at which the DOI is minted differs from data set to data set.
The following recipes describe how to find a DOI for a particular product or data set in the Search API metadata.
See the [DOI Search](https://pds.nasa.gov/tools/doi/) for an online interface for searching this information.
See the documentation on Citing PDS Data for more information on how to use a DOI to cite your data.
Warning
Since our servers are not fully populated with all PDS data sets, the examples presented in this user guide may return empty results or 404 (Not Found) errors. If there is a data set you would like added, please contact the PDS Help Desk for assistance.
How to Find the DOI associated with an Observational Product
We assume you know the identifier of the product you are working with but a couple are provided in the examples below.
Search for a Product’s Collection DOI
Run the following request to get the DOI associated with the collection the observational product urn:nasa:pds:compil-comet:nuc_properties:description::1.0 belongs to:
curl -L --get 'https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:vg1-saturn-pos-hgcoords-96sec:data-spice:spice-hg::1.0/member-of' \
--data-urlencode 'fields=pds:Citation_Information.pds:doi' \
--header 'Accept: application/kvp+json'
You will get the following result:
{
"summary" : {
"q": "",
"hits": 1,
"took": 125,
"start": 0,
"limit": 100,
"sort": [],
"properties": ["pds:Citation_Information.pds:doi"]
},
"data": [
{
"pds:Citation_Information.pds:doi":"10.17189/1522962"
}
]
}
Note that you might not find any DOI at the collection level, in this case you can try to get the DOI from the bundle.
Search for a Product’s Bundle DOI
To get the DOI associated with the bundle the observational product urn:nasa:pds:insight.spice:document:spiceds::1.0 belongs to:
curl -L --get 'https://pds.nasa.gov/api/search/1/products/urn:nasa:pds:insight.spice:document:spiceds::1.0/member-of/member-of' \
--data-urlencode 'fields=pds:Citation_Information/pds:doi' \
--header 'Accept: application/kvp+json'
You will get the following result:
{
"summary" : {
"q": "",
"hits": 2,
"took": 135,
"start": 0,
"limit": 100,
"sort": [],
"properties": [
"pds:Citation_Information.pds:doi"
]
},
"data": [
{ },
{
"pds:Citation_Information.pds:doi": "10.17189/1517566"
}
]
}
How to Find the PDS Product Associated with a DOI
To get the PDS product metadata associated with a the DOI 10.17189/1517568:
curl -L --get 'https://pds.nasa.gov/api/search/1/products' \
--data-urlencode 'q=(pds:Citation_Information.pds:doi eq "10.17189/1522962")' \
--header 'Accept: application/json'
You will get a JSON response of the PDS products (any class of product, for example collections or bundles) which have referenced the given DOI.
You can get the result in different format using content negociation with the Accept header parameter.
Search by Time Range
For example, as a user I need to find the Voyager 1 PWS Spectrum Analyzer CDF files covering March of 1979 so I can make a plot.
Here is one of the XML files, rendered: https://search-pdsppi.igpp.ucla.edu/ditdos/viewFile?id=pds://PPI/voyager1.pws.sa/data/1979/vg1pws_lr_19790105_v5.20.xml .
To build this query, we can search by the instrument and time range:
((pds:Time_Coordinates.pds:start_date_time ge "1979-03-01T00:00:00.000Z") and
(pds:Time_Coordinates.pds:start_date_time lt "1979-04-01T00:00:00.000Z") and
(ref_lid_instrument eq "urn:nasa:pds:context:instrument:vg1.pws"))
Do query that using curl, it would look like this:
curl -L --get 'https://pds.nasa.gov/api/search/1/products' \
--data-urlencode 'q=((pds:Time_Coordinates.pds:start_date_time ge "1979-03-01T00:00:00.000Z") and ' \
--data-urlencode '(pds:Time_Coordinates.pds:start_date_time lt "1979-04-01T00:00:00.000Z") and ' \
--data-urlencode '(ref_lid_instrument eq "urn:nasa:pds:context:instrument:vg1.pws"))' \
--header 'Accept: application/json'
Looking for more recipes? Or have some useful recipes of your own? Checkout the PDS API Discussion Board or contact the PDS Help Desk