Query the NASA/OB.DAAC Oceancolor file search API
Source:R/oceandata_api.R
bb_oceandata_filesearch.RdPreviously it was possible to search based on filename pattern alone, e.g. "S*L3m_MO_CHL_chlor_a_9km.nc" would match monthly level-3 mapped chlorophyll data from the SeaWiFS satellite at 9km resolution, in netcdf format. However, as of June 2026 the OB.DAAC search API requires other parameters to be set, in order to reduce the search load on the server, see https://www.earthdata.nasa.gov/data/alerts-outages/ob.daac-file-search-utility-now-requires-more-specificity. It is not obvious which or how many parameters are required for a given search. If you are constructing an oceandata bowerbird source you are advised to use the file search web page https://oceandata.sci.gsfc.nasa.gov/api/file_search and its help page https://oceandata.sci.gsfc.nasa.gov/file_search/file_search_help/ to help find the correct parameters.
Usage
bb_oceandata_filesearch(
search = NULL,
sensor = NULL,
dtype = NULL,
dtid = NULL,
period = NULL,
resolution_id = NULL,
prod_id = NULL,
suite_id = NULL,
sdate = NULL,
edate = NULL
)
bb_oceandata_dtid_table()Arguments
- search
character: the search string (file name pattern). Note that relying on the search string tends to yield slower searches: specify the target files as tightly as possible using the other search parameters. But you might still need the search string to impose additional filtering on the results
- sensor
character: the sensor, e.g. "SeaWiFS", "MODISA", "MODIST", "VIIRS", "CZCS", "MERIS", etc: see https://oceandata.sci.gsfc.nasa.gov/file_search/file_search_help/
- dtype
character: the data type (e.g. "L3m") to pass to the oceancolor file searcher. Valid options at the time of writing are L0, L1, L2, L3b (for binned data), L3m (for mapped data), MET (for ancillary data), misc (for sundry products)
- dtid
integer: data type ID, see https://oceandata.sci.gsfc.nasa.gov/file_search/file_search_help/. Note that providing the
dtidtypically gives a much faster search. Thebb_oceandata_dtid_table()function will (with luck) dynamically scrape the full table ofdtidvalues that can be used here- period
character: the time period, one of "DAY", (daily) "8D" (8-day), "MO", (monthly) "MC" (monthly climatology), "YR" (yearly), "SN" (seasonal), "SC" (seasonal climatology), etc: see https://oceandata.sci.gsfc.nasa.gov/file_search/file_search_help/
- resolution_id
character: "9km" or "4km"
- prod_id
character: product, e.g. "par", "chlor_a", etc: see https://oceandata.sci.gsfc.nasa.gov/file_search/file_search_help/
- suite_id
character: product suite, e.g. "RRS", etc: see https://oceandata.sci.gsfc.nasa.gov/file_search/file_search_help/
- sdate
Date or character: start date (in "YYYY-MM-DD" format, if provided as a string)
- edate
Date or character: end date (in "YYYY-MM-DD" format, if provided as a string). If not specified it will default to the current date
Details
It is possible to provide multiple values for one or more search parameters: the POST request to the file search API will be repeated for all possible combinations of parameters (constructed via expand.grid). This might be helpful, for example, by allowing dtid to be specified as a two-element vector with one value for refined data and the second for NRT data. Specifying two dtid values will yield a much faster search than omitting dtid and relying on the search parameter to achieve the same refined/NRT file inclusions.