MODAPS Web Services API for LANCE-MODIS

This Application Programming Interface (API) encompasses a library of functions that provides programmatic data access to MODIS near-real-time data products. These routines enable both SOAP and REST based web service calls against the LANCE-MODIS near-real-time data archives. These routines mirror existing LAADS Web services.

The LANCE-MODIS instance of the MODAPS Web Services has limited functionality. It includes the methods necessary for querying and downloading granules, but lacks ordering and post-processing functions.

The Web service description language (WSDL) document:

http://lance.modaps.eosdis.nasa.gov/axis2/services/MWSLance?wsdl

API Methods

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.

Parameter Type Description Required Values Default
None

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.


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

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.


getFileUrls

Returns the data file HTTPS 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 HTTPS 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.


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. yes A valid collection number, see listCollections. N/A
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 listCollections. 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. yes A valid collection number, see listCollections. N/A
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.


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.


Data Structures

FileProperties

A set of file properties

Field Notes
checksum
fileId
fileName
fileSizeBytes
fileType
ingestTime
online
startTime


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


REST Examples

Get a list of file IDs for the specified product, collection, time period, and geographic coordinates:

http://lance.modaps.eosdis.nasa.gov/axis2/services/MWSLance/searchForFiles?products=MOD04_L2&collection=1&startTime=2013-04-28&endTime=2013-04-28&north=40&south=30&east=-70&west=-80&coordsOrTiles=coords

Get a list of HTTPS URLs for the specified file IDs

http://lance.modaps.eosdis.nasa.gov/axis2/services/MWSLance/getFileUrls?fileIds=206688338,206688383,206701233,206700924

Get an OpenSearch compatible format for the specified product, collection, time period, and geographic coordinates:

http://lance.modaps.eosdis.nasa.gov/axis2/services/MWSLance/getOpenSearch?products=MOD04_L2&collection=1&start=2013-04-28&stop=2013-04-28&bbox=-80,30,-70,40


Version: RELEASE_VERSION + Privacy Policy and Important Notices NASA Webmaster:
NASA Official: