|
MODAPS Web Services API
This Application Programming Interface (API) encompasses a library of
functions that provides programmatic data access and processing services
to MODIS Level 1 and Atmosphere data products. These routines enable both
SOAP and REST based web service calls against the data archives maintained
by MODAPS.
These routines mirror existing
LAADS Web services.
Sample implementation using this API are provided in the
Quick Start Guide. Issues and bugs are listed
at Known Issues.
Information about the production, archive and distribution of the data
products in LAADS can be found at the
MODAPS Services
web site.
API Methods
-
Product Information
-
Searching
-
Processing Information
-
Ordering
-
Status
-
Data Structures
Product Information
listSatelliteInstruments
Returns a list of available satellite/instruments.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| None |
|
|
|
|
|
| Return |
Type |
Description |
| instruments |
List of NameValuePair |
A list of satellite/instrument names, along with their descriptions.
|
listCollections
Returns a list of available collections. Deprecated because collections can vary between products. Use getCollections instead.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| None |
|
|
|
|
|
| Return |
Type |
Description |
| collections |
List of NameValuePair |
A list of collections, along with their descriptions.
|
getCollections
Returns a list of available collections for the given product.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| product |
string |
Product/ESDT shortname |
Yes |
Any product |
N/A |
| Return |
Type |
Description |
| collections |
List of NameValuePair |
A list of collections, along with their descriptions.
|
listProducts
Returns a list of available products.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| None |
|
|
|
|
|
| Return |
Type |
Description |
| products |
List of NameValuePair |
A list of products, along with their descriptions.
|
listProductGroups
Returns a list of available product groups for the given instrument.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| instrument |
String |
The satellite/instrument name.
|
yes |
A valid satellite/instrument name, see
listSatelliteInstruments.
|
N/A |
| Return |
Type |
Description |
| groups |
List of NameValuePair |
A list of product groups, along with their descriptions.
|
listProductsByInstrument
Returns a list of products available for the given satellite/instrument.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| instrument |
String |
The satellite/instrument name.
|
yes |
A valid satellite/instrument name, see
listSatelliteInstruments.
|
N/A |
| group |
String |
The product group name
|
no |
A valid group name, see
listProductGroups.
|
N/A |
| Return |
Type |
Description |
| products |
List of Strings |
A list of product names for this satellite/instrument.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getFileProperties
Returns the data file properties for the given file IDs.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| fileIds |
String |
The file IDs for the data files, in a comma-delimited string. |
yes |
Any valid file ID, see searchForFiles or
searchForFilesByName.
|
N/A |
| Return |
Type |
Description |
| properties |
List of FileProperties |
A list of data file properties, including name, id, size, format, ingest time, data start
time, and online status.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getFileOnlineStatuses
Returns the data file online statuses for the given file IDs.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| fileIds |
String |
The file IDs for the data files, in a comma-delimited string. |
yes |
Any valid file ID, see searchForFiles or
searchForFilesByName.
|
N/A |
| Return |
Type |
Description |
| statuses |
List of FileOnlineStatus |
A list of data files statues, including the date until the data file
is required online.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getFileUrls
Returns the data file FTP URLs for the given file IDs.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| fileIds |
String |
The file IDs for the data files, in a comma-delimited string. |
yes |
Any valid file ID, see searchForFiles or
searchForFilesByName.
|
N/A |
| Return |
Type |
Description |
| urls |
List of Strings |
A list of data file FTP URLs. If a data file is not online,
a NULL is returned.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getBrowse
Returns browse fileIds for the given fileId.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| fileId |
String |
The fileId for which you want browse files |
yes |
Any valid file ID, see searchForFiles or
searchForFilesByName.
|
N/A |
| Return |
Type |
Description |
| browseFiles |
List of BrowseFiles |
A structure containing info for each available browse file: fileId, product name, description.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getDateCoverage
Returns the range of dates covered by the given product in the given
collection. This range marks the extreme first and last dates and
does NOT account for gaps in the data coverage between those points.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| collection |
Integer |
The collection number. |
yes |
A valid collection number, see
listCollections.
|
N/A |
| product |
String |
The product name. |
yes |
A valid product name, see listProducts.
|
N/A |
| Return |
Type |
Description |
| dateRange |
DateRange |
A start date and an end date. |
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getMaxSearchResults
Returns maximum number of file IDs that will be returned from a search.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| None |
|
|
|
|
|
| Return |
Type |
Description |
| maxResults |
Integer |
The maximum number of file IDs that will be returned from a search,
see searchForFiles and
searchForFilesByName.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
Searching
searchForFiles
Returns a list of file IDs matching the given search criteria.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| products |
String |
The product names in a comma-delimited string. |
yes |
Any valid product name, see listProducts.
|
N/A |
| collection |
Integer |
The collection number. |
no |
A valid collection number, see
getCollections.
|
Default collection for product,see getCollections |
| startTime |
String |
The start date (and optional time) of the temporal window.
|
yes |
YYYY-MM-DD or YYYY-MM-DD hh:mm:ss |
N/A |
| endTime |
String |
The end date (and optional time) of the temporal window.
|
yes |
YYYY-MM-DD or YYYY-MM-DD hh:mm:ss |
N/A |
| north |
Float |
North boundary of the spatial window. |
yes |
-90 to 90 for coords or 0 to 17 for tiles. |
N/A |
| south |
Float |
South boundary of the spatial window. |
yes |
-90 to 90 for coords or 0 to 17 for tiles. |
N/A |
| east |
Float |
East boundary of the spatial window. |
yes |
-180 to 180 for coords or 0 to 35 for tiles. |
N/A |
| west |
Float |
West boundary of the spatial window. |
yes |
-180 to 180 for coords or 0 to 35 for tiles. |
N/A |
| coordsOrTiles |
String |
Specifies whether the north/south/west/east parameters are coords
or tiles. The north/south/west/east parameters are ignored if
global.
|
yes |
coords, tiles, or global |
N/A |
| dayNightBoth |
String |
Specifies whether to include data files which only have day data (D),
only have night data (N), or only have both day and night data (B).
|
no |
D,N,B,DN,DB,NB,DNB |
DNB |
| Return |
Type |
Description |
| fileIds |
List of Integers |
A list of file IDs, which uniquely identify the data files.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
searchForFilesByName
Returns a list of fileIDs matching the given file name.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| collection |
Integer |
The collection number. |
yes |
A valid collection number, see
getCollections.
|
N/A |
| pattern |
String |
A file name pattern. |
yes |
A string of at least 15 characters that may contain wildcards (*, ?, [])
after the first 15 characters.
|
N/A |
| Return |
Type |
Description |
| fileIds |
List of Integers |
A list of file IDs, which uniquely identify the data files.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
searchDatasets
Returns a list of products matching the supplied keywords. The keywords are OR'd, and will match product shortname, longname, and name of any SDS's contained in the product.
This OpenSearch Description Document describes this dataset-level search.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| pattern |
String |
Whitespace delimited list of keywords |
yes |
Any string
|
N/A |
| Return |
Type |
Description |
| products |
atom+xml |
A list of data products, in an opensearch-compatible atom format.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getOSDD
Returns an OpenSearch Description Document for a granule-level search of a product
| Parameter |
Type |
Description |
Required |
Values |
Default |
| product |
String |
A product name |
yes |
A valid product, see
searchDatasets, or listProducts
|
N/A |
| Return |
Type |
Description |
| OpenSearch Description |
atom+xml |
An OpenSearch Description Document
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getOpenSearch
Returns the data files matching the given search criteria in an
OpenSearch compatible
atom format.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| products |
String |
The product names in a comma-delimited string. |
yes |
Any valid product name, see listProducts.
|
N/A |
| collection |
Integer |
The collection number |
No |
A valid collection number, see
getCollections.
|
Default collections for product, see getCollections |
| start |
String |
The start date (and optional time) of the temporal window.
|
yes |
YYYY-MM-DD or YYYY-MM-DD hh:mm:ss |
N/A |
| stop |
String |
The end date (and optional time) of the temporal window.
|
yes |
YYYY-MM-DD or YYYY-MM-DD hh:mm:ss |
N/A |
| bbox |
String |
Boundary of the spatial window. |
yes |
west,south,east,north where south and north are -90 to 90 for coords
or 0 to 17 for tiles and west and east are -180 to 180 for coords or
0 to 35 for tiles.
|
N/A |
| coordsOrTiles |
String |
Specifies whether the bbox parameter are coords or tiles. The bbox
parameter is ignored if global.
|
no |
coords, tiles, or global |
coords |
| dayNightBoth |
String |
Specifies whether to include data files which only have day data (D),
only have night data (N), or only have both day and night data (B).
|
no |
D,N,B,DN,DB,NB,DNB |
DNB |
| Return |
Type |
Description |
| files |
atom+xml |
The data files are returned in an
OpenSearch
compatible atom format.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
Processing Information
getPostProcessingTypes
Returns a list of available post-processing operations for the given
products.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| products |
List of Strings |
The product names. |
yes |
Any valid product name, see listProducts.
|
N/A |
| Return |
Type |
Description |
| postProcessingTypes |
List of Strings |
A list of post-processing operations.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getBands
Returns a list of available bands for the given product.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| product |
String |
The product name. |
yes |
A valid product name, see listProducts.
|
N/A |
| Return |
Type |
Description |
| bands |
List of NameValuePair |
A list of band names, along with their descriptions.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getDataLayers
Returns a list of available data layers for the given product.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| product |
String |
The product name. |
yes |
A valid product name, see listProducts.
|
N/A |
| Return |
Type |
Description |
| dataLayers |
List of NameValuePair |
A list of data layer names, along with their descriptions.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
listMapProjections
Returns a list of available map projections.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| None |
|
|
|
|
|
| Return |
Type |
Description |
| projections |
List of NameValuePair |
A list of map projection names, along with their descriptions.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
listReprojectionParameters
Returns a list of reprojection parameters available for the given
map projection.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| reprojectionName |
String |
The map projection name. |
yes |
A valid map projection, see
listMapProjections.
|
N/A |
| Return |
Type |
Description |
| parameters |
List of ReprojectionParameter |
A list of reprojection parameters, including the name,
description, and unit of measurement.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
Ordering
orderFiles
Creates one or more orders for the given user and file IDs. The requested
file IDs are first separated by file type, e.g., online or processing on
demand. If any of these orders is too large, they will be broken up into
several smaller orders. Several post-processing options are available,
depending on the product.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| email |
String |
User's email address. A notification email will be sent to this address
when the order is complete.
|
yes |
Any valid email address. |
N/A |
| fileIds |
List of Integers |
The file IDs that identify the data files to order, in a comma-delimited string. |
yes |
Any valid file ID, see searchForFiles or
searchForFilesByName.
|
N/A |
| reformatType |
String |
Specifies the format you would like the data files. Data files are in
HDF format by default.
|
no |
geotiff, jpeg |
N/A |
| doMosiac |
Boolean |
Specifies whether you would like to create a mosaic of the data files.
|
no |
true, false |
N/A |
| geoSubsetNorth |
Float |
North boundary for geographic subsetting. |
no |
-90 to 90 |
N/A |
| geoSubsetSouth |
Float |
South boundary for geographic subsetting. |
no |
-90 to 90 |
N/A |
| geoSubsetWest |
Float |
West boundary for geographic subsetting. |
no |
-180 to 180 |
N/A |
| geoSubsetEast |
Float |
East boundary for geographic subsetting. |
no |
-180 to 180 |
N/A |
| reprojectionName |
String |
Specifies the map projection you would like the data files.
|
no |
A valid map projection name, see
listMapProjections.
|
N/A |
| reprojectionOuputPixelSize |
String |
The output pixel size parameter for the reprojection, see
listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The output pixel size value in meters. |
N/A |
| reprojectionFalseEasting |
String |
The false easting parameter for the reprojection, see
listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The false easting value in meters. |
N/A |
| reprojectionFalseNorthing |
String |
The false northing parameter for the reprojection, see
listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The false northing value in meters. |
N/A |
| reprojectionStandardParallel1 |
String |
The latitude of first standard parallel parameter for the reprojection,
see listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The latitude of first standard parallel value in degrees.
|
N/A |
| reprojectionStandardParallel2 |
String |
The latitude of second standard parallel parameter for the reprojection,
see listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The latitude of second standard parallel value in degrees.
|
N/A |
| reprojectionCentralMeridian |
String |
The longitude of central meridian parameter for the reprojection,
see listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The longitude of central meridian value in degrees.
|
N/A |
| reprojectionOriginLat |
String |
The latitude of projection origin parameter for the reprojection,
see listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The latitude of projection origin value in degrees.
|
N/A |
| reprojectionCenterLon |
String |
The longitude of center of projection parameter for the reprojection,
see listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The longitude of center of projection value in degrees.
|
N/A |
| reprojectionCenterLat |
String |
The latitude of center of projection parameter for the reprojection,
see listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The latitude of center of projection value in degrees.
|
N/A |
| reprojectionTrueScaleLat |
String |
The latitude of true scale parameter for the reprojection, see
listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The latitude of true scale value in degrees.
|
N/A |
| reprojectionLongitudePole |
String |
The longitude below pole parameter for the reprojection, see
listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The longitude below pole value in degrees.
|
N/A |
| reprojectionScaleFactor |
String |
The scale factor at central meridian parameter for a reprojection,
see listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
The scale factor at central meridian value in meters.
|
N/A |
| reprojectionResampleType |
String |
The resample type parameter for the reprojection, see
listReprojectionParameters
to determine if this parameter may be used with the specified
reprojectionName.
|
no |
Nearest, Bilinear |
N/A |
| subsetDataLayer |
List of Strings |
Specifies the data layers to extract from the data files.
|
no |
Any valid data layer, see getDataLayers.
|
N/A |
| subsetBand |
List of Strings |
Specifies the bands to extract from the data files.
|
no |
Any valid band, see getBands.
|
N/A |
| Return |
Type |
Description |
| orderIds |
List of Integers |
A list of order IDs which are used to uniquely identify the order.
The order IDs will also be referenced in the notification email.
|
| Error |
Exception Class |
|
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
orderFilesProcessed (deprecated)
orderFiles now accepts post processing options as
optional parameters. See orderFiles for a
description of functionality. This method will remain active for now, but
it is essentially an alias for orderFiles.
Status
getAllOrders
Returns a list of order IDs associated with the user's email address.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| email |
String |
User's email address. |
yes |
A valid email address. |
N/A |
| Return |
Type |
Description |
| orderIds |
List of Integers |
A list of order IDs which are used to uniquely identify the order.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getOrderStatus
Returns the order status of the given order ID.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| orderId |
Integer |
The order ID for the order. |
yes |
A valid order ID, see getAllOrders.
|
N/A |
| Return |
Type |
Description |
| status |
String |
A status description. |
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
getOrderUrl
Returns the order FTP URL for the given order ID.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| orderId |
Integer |
The order ID for the order. |
yes |
A valid order ID, see getAllOrders.
|
N/A |
| Return |
Type |
Description |
| url |
String |
An order FTP URL. |
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
releaseOrder
Releases an order so that it can be removed from the FTP site to
free up space.
| Parameter |
Type |
Description |
Required |
Values |
Default |
| orderId |
Integer |
The order ID for the order. |
yes |
A valid order ID, see getAllOrders.
|
N/A |
| email |
String |
User's email address. |
yes |
A valid email address. |
N/A |
| Return |
Type |
Description |
| success |
Integer |
1 if the order was successfully released, 0 otherwise.
|
| Error |
Exception Class |
Description |
| Invalid Parameters |
InvalidParameterException |
One or more of the required parameters are missing, or a supplied
parameter is invalid.
|
Data Structures
FileProperties
A set of file properties
| Field |
Notes |
| checksum |
|
| fileId |
|
| fileName |
|
| fileSizeBytes |
|
| fileType |
|
| ingestTime |
|
| online |
|
| startTime |
|
FileOnlineStatus
A file's online status and related information
| Field |
Notes |
| archiveAutoDelete |
|
| fileId |
|
| requireUntil |
|
NameValuePair
A pair that maps a modaps identifier such as an SDS or satellite instrument name to a human readable description.
| Field |
Notes |
| Name |
The identifier to be used in web service calls |
| Value |
A human readable description of the identifier |
DateRange
A date range.
| Field |
Notes |
| endDate |
YYYY-MM-DD |
| StartDate |
YYYY-MM-DD |
|
|
