API-V2 User Guide
This guide describes the structure of API-V2 REST (Representational State Transfer) API (Application Programming Interface), which supports querying our system for information about resources available to users.
API-V2 is mostly intended for users writing scripts to automatically search for and download data from our archive, but it also provides a wealth of related information about data resources.
Searching for a set of files
Our MODAPS production system receives data samples from instruments, groups the data into manageable sized chunks (5 minute samples, 6 minute samples, orbit sized samples, or samples bounded by geographic coordinates), and places those samples in files. When requesting data, you will be downloading files that contain these chunks of data. So out of our archive of millions (and counting) of files, how to find the files that contain your data of interest?
When searching for data, it is important to constrain, or narrow down, the search so that you get only the files and data that interest you. We support the following types of constraints:
- PRODUCTS In addition to being grouped into manageable sized samples, the data are processed by different algorithms to create different categories of data (also called "Products" or "Earth Science Data Types" or "ESDT"s) and sets of data (also called "Science Data Sets" or "SDS"s). A file always contains just one category of data (for example, Aerosol data, or Top of Atmosphere Reflectance data), but might contain many data sets that belong in that category (for example, the MOD06_L2 Cloud Properties product contains 127 different data sets in each file).
Products can be specified in a number of different ways, as follows.
- by product name
- by product description
- by Science Domain name
- by keywords
- by SDS or Dataset Name
by PGE
- COLLECTIONS Another way of grouping data is by "collections". Science doesn't stand still, it evolves. To keep track of its evolution, we have grouped files by the science thinking that drove the algorithm development in that group. Each collection represents a step in the evolution of the processing or presentation of the data.
Collections can be specified in several ways.
- by collection name. Collection name usually identifies a platform, an instrument, and a version.
by ArchiveSet. ArchiveSet can be a way of subdividing collections into other pieces, for example, for use by Science Teams when testing new algorithms, to keep the test data from being confused with validated data.
- LOCATIONS Another way of grouping data is by space and time. Data were sampled at a particular moment in time over a particular location on the earth. We support several ways to specify locations, including
GEOGRAPHIC LOCATION
- by Administrative boundary (country or protected area name)
- by bounding coordinates (we support several different formats)
TEMPORAL LOCATION
- we support searching multiple ranges of dates and times
Examples
See Quick Start Guide : Searching.
Downloading files
Once you have found a set of files, the next step is to download them (transfer them from our archive to your platform of choice). Usually in a web browser, you click on a filename, and your browser downloads it for you to your local machine. There are many times when clicking on selection boxes and file links in your browser can become tedious. By writing an application or script, you can automate these search and download "clicks" using tools that perform the same steps as your web browser, but do it repeatedly and automatically, and have the files transferred to your platform of choice (which might not be your local computer).
When writing an application to download files, keep in mind the following:
- In 2019, NASA decided to no longer support the File Transfer Protocol (FTP) due to security issues. Since that time, we have been required to use the Secure HyperText Transfer Protocol (HTTPS) for transferring files.
- In addition, we are required to collect metrics about the amount of data we distribute. To support this effort, users are also now required to use a token to identify where the data requests are coming from. These requirements influence how you design applications that can help you download data.
NOTE: we do not monitor or limit users' downloads based on this token.
Examples
See Quick Start Guide : Downloading.
Finding Other Information
There is much more information available about our data resources. For example, you can find the source code that created a particular version of a data file. You can find product metadata, information about different regions of interest, information about platforms and instruments that sample the data that we archive, detailed product descriptions, what time ranges a particular product covers, etc.