LAADS Web Service Classic 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 the LAADS DAAC. These routines mirror existing LAADS DAAC Search and Order 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
- listSatelliteInstruments
- listProducts
- listProductsByInstrument
- listProductGroups
- listCollections (deprecated)
- getCollections
- getFileProperties
- getFileOnlineStatuses
- getFileUrls
- getBrowse
- getDateCoverage
- getMaxSearchResults
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 download 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 download 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 globa 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 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 Description 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 download 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 download 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 download 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