Home
Tools & Services
API-V2 OpenAPI Specifications

API-V2 OpenAPI Specifications

Endpoints in the API-V2 "content" namespace return content, or information about content, depending on the endpoint. archives responses are returned as HTML so they can be parsed by wget, all other responses are returned as JSON.

Scope

Current endpoints support requests for information about

directories and files in our archive
contact information
version information

In the future, we will support requests for more general page content.

Endpoint and Parameter Descriptions

The following table identifies each supported endpoint, and any parameters that the endpoint request supports. Requests are constructed by appending "/api/v2/content" with the endpoint and any query parameters. To see which query parameter values are accepted for a query parameter, click on the links in the Param Type column for that parameter. To see what endpoint responses look like, click on the links in the Examples column.

Endpoint

Operation

Description

Examples

GET

returns this OpenAPI specification as JSON

/api/v2/content

alerts

GET

returns all the alerts known to the system

Param Name	Param Description	Param Type
current	limit to the most recent alerts	boolean

/api/v2/content/alerts

alerts/{alertId}

GET

returns the specified alert.

Param Name	Param Description	Param Type
alert_id	name or ID of an Alert	integer

archives

GET

returns the content of the default archived resource (usually the root directory of the archive) if no Constraint query params, or an html list of all resources matching the Constraint params.

Param Name	Param Description	Param Type
page	page number of multi-paged output, 1..N	integer
fields	names of information fields desired in the output	string matching /^[a-zA-Z0-9\.\,\s\?\*_:\|-]+$/
formats	format for desired output	one of [json, html, csv]
platforms	from the specified platforms	/api/v2/missions/platforms
instruments	from the specified instruments	/api/v2/missions/instruments
sensors	from the specified sensors	/api/v2/missions/sensors
collections	from the specified collections	/api/v2/measurements/collections
archiveSets	from the specified archiveSets	/api/v2/measurements/archiveSets
products	from the specified products	/api/v2/measurements/products
analysisConstraints	from the specified analysis constraints	/api/v2/measurements/analysisConstraints
availability	from the specified date:time ranges	/api/v2/measurements/availability
temporalRanges	temporal ranges (date and optionally, time) are specified as follows: dates can have either of the two following formats: YYYY-MM-DD where YYYY is year, MM is month number (01..12), and DD is day of month (01..number of days in month). YYYY-DDD where YYYY is the 4 digit year and DDD is the day-of-year (1..365 or 1..366 for leap years) if a date is NOT specified, then the current date is assumed. the date is separated from the time by either a space or a "T" character. times must be specified as HH:MM, where HH is the hour (0..23) counting from midnight, and MM is the minute (0..59). all times are interpreted as Coordinated Universal Time (UTC). Currently time zone specifications are not supported. date time ranges are specified as two dates or date times separated by two period (dot) characters ".." date..date : the start time is assumed to be 00:00 and the end time is assumed to be 23:59 YYYY-MM-DD..YYYY-MM-DD YYYY-DDD..YYYY-MM-DD YYYY-MM-DD..YYYY-DDD YYYY-DDD..YYYY-DDD date time..date : the end time is assumed to be 23:59 YYYY-MM-DD HH:MM..YYYY-MM-DD YYYY-DDD HH:MM..YYYY-MM-DD YYYY-MM-DD HH:MM..YYYY-DDD YYYY-DDD HH:MM..YYYY-DDD date..date time : the start time is assumed to be 00:00 YYYY-MM-DD..YYYY-MM-DD HH:MM YYYY-DDD..YYYY-MM-DD HH:MM YYYY-MM-DD..YYYY-DDD HH:MM YYYY-DDD..YYYY-DDD HH:MM date time..date time YYYY-MM-DD HH:MM..YYYY-MM-DD HH:MM YYYY-DDD HH:MM..YYYY-MM-DD HH:MM YYYY-MM-DD HH:MM..YYYY-DDD HH:MM YYYY-DDD HH:MM..YYYY-DDD HH:MM	/api/v2/measurements/temporalRanges
illuminations	measured during Day, at Night, or at polar day/night Boundary	/api/v2/measurements/illuminations
regions	All Regions are specified using a region type and either a text field or a set of decimal cartesian coordinates. Region types must be one of [BBOX] or [ENVELOPE] or [MBR] : minimum bounding rectangle [WKT] : a "Well Known Text" (WKT) geometry string [POLY] : a closed polygon [PA] : a protected area [AA] : an administrative area (currently, only countries are supported, using ISO country name or abbreviation) [TILE] : a MODAPS sinusoidal tile identifier North and South coordinates are relative to the equator, East and West coordinates are relative to the Prime (Greenwich) Meridian. Regions can have the following forms: Bounding box ordinates can be in any order. The edge that the ordinate (N=north, S=south, W=west, E=east) applies to starts the coordinate: [BBOX]N21.5 S20.5 E12 W-15 [ENVELOPE]W-140 N-30 E-134.159 S-45.6 [MBR]E-134.159 W-140 S-45.6 N-30 in (WKT) strings, coordinates are always x y pairs [WKT]POINT (30 10) as an alternative to WKT, simple closed, convex polygons can be specified using x y cartesian coordinate pairs [POLY][30 10 40 40 20 40 10 20 30 10] protected areas are specified by name [PA]Acid Shale-Pine Forest administrative areas are specified by name (currently, only countries are supported, using ISO country name or abbreviation) [AA]USA [AA]United States tile identifiers are of the form HxxVyy, where xx is the horizontal tile number, and yy is the vertical tile number. Currently, only MODAPS Sinusoidal tiles are supported (see https://modis-land.gsfc.nasa.gov/MODLAND_grid.html)	/api/v2/measurements/regions
pges	from specified PGEs	/api/v2/measurements/pges
scienceDomains	from specified science domains	/api/v2/measurements/scienceDomains
layers	containing specified layers	/api/v2/measurements/layers
images	source of specified images	/api/v2/measurements/images

html list of the root archive directory
- /api/v2/content/archives
html links to all the files that match the query parameters
- /api/v2/content/archives?products=VNP14&temporalRanges=2019-10-23..2019-11-06&regions=[BBOX]W-125 N40 E-119.6 S36.5

archives/{resourceId}

GET

for directories, returns html table of directory contents
for files, streams the file contents

Param Name	Param Description	Param Type
resourceId	path to resource	string matching /^[a-zA-Z0-9\.\s\#\*/_,&:+-]+$/

html list of the "/MAS_eMAS/Spokane_1996/96_160/MASL1B/" directory
- /api/v2/content/archives/MAS_eMAS/Spokane_1996/96_160/MASL1B/
stream the README file (you must be logged in for a valid response)
- /api/v2/content/archives/README
stream the file named "VJ102IMG.A2020332.0106.002.2020332060828.nc" (you must be logged in for a valid response)
- /api/v2/content/archives/VJ102IMG.A2020332.0106.002.2020332060828.nc
stream the file at "allData/61/MYD07_L2/2016/043/MYD07_L2.A2016043.0000.061.2018055112748.hdf" (you must be logged in for a valid response)
- /api/v2/content/archives/allData/61/MYD07_L2/2016/043/MYD07_L2.A2016043.0000.061.2018055112748.hdf

contacts

GET

returns all the contacts known to the system.

Param Name	Param Description	Param Type
fields	names of information fields desired in the output	string matching /^[a-zA-Z0-9\.\,\s\?\*_:\|-]+$/
formats	format for desired output	one of [json, html, csv]

/api/v2/content/contacts

contacts/{contactId}

GET

returns the specified contact.

Param Name	Param Description	Param Type
contactId	name or ID of a Contact	string matching /^[a-zA-Z0-9\.\,\s\?\*_:\|-]+$/

/api/v2/content/contacts/wwwContactName

details

GET

Returns details about a resource or set of resources. The resource is either the default resource (usually the root of the archive directory) if no constraint query parameters, or those resources that result from the query parameters.

Param Name	Param Description	Param Type
page	page number of multi-paged output, 1..N	integer
fields	names of information fields desired in the output	string matching /^[a-zA-Z0-9\.\,\s\?\*_:\|-]+$/
formats	format for desired output	one of [json, html, csv]
fileIds	with the specified fileId	/api/v2/content/fileIds
fileNames	with the specified fileName, can include wildcards after the YEARDAY field, for example: MOD03.A2020123.*	/api/v2/content/fileNames
platforms	from the specified platforms	/api/v2/missions/platforms
instruments	from the specified instruments	/api/v2/missions/instruments
sensors	from the specified sensors	/api/v2/missions/sensors
collections	from the specified collections	/api/v2/measurements/collections
archiveSets	from the specified archiveSets	/api/v2/measurements/archiveSets
products	from the specified products	/api/v2/measurements/products
analysisConstraints	from the specified analysis constraints	/api/v2/measurements/analysisConstraints
availability	from the specified date:time ranges	/api/v2/measurements/availability
temporalRanges	temporal ranges (date and optionally, time) are specified as follows: dates can have either of the two following formats: YYYY-MM-DD where YYYY is year, MM is month number (01..12), and DD is day of month (01..number of days in month). YYYY-DDD where YYYY is the 4 digit year and DDD is the day-of-year (1..365 or 1..366 for leap years) if a date is NOT specified, then the current date is assumed. the date is separated from the time by either a space or a "T" character. times must be specified as HH:MM, where HH is the hour (0..23) counting from midnight, and MM is the minute (0..59). all times are interpreted as Coordinated Universal Time (UTC). Currently time zone specifications are not supported. date time ranges are specified as two dates or date times separated by two period (dot) characters ".." date..date : the start time is assumed to be 00:00 and the end time is assumed to be 23:59 YYYY-MM-DD..YYYY-MM-DD YYYY-DDD..YYYY-MM-DD YYYY-MM-DD..YYYY-DDD YYYY-DDD..YYYY-DDD date time..date : the end time is assumed to be 23:59 YYYY-MM-DD HH:MM..YYYY-MM-DD YYYY-DDD HH:MM..YYYY-MM-DD YYYY-MM-DD HH:MM..YYYY-DDD YYYY-DDD HH:MM..YYYY-DDD date..date time : the start time is assumed to be 00:00 YYYY-MM-DD..YYYY-MM-DD HH:MM YYYY-DDD..YYYY-MM-DD HH:MM YYYY-MM-DD..YYYY-DDD HH:MM YYYY-DDD..YYYY-DDD HH:MM date time..date time YYYY-MM-DD HH:MM..YYYY-MM-DD HH:MM YYYY-DDD HH:MM..YYYY-MM-DD HH:MM YYYY-MM-DD HH:MM..YYYY-DDD HH:MM YYYY-DDD HH:MM..YYYY-DDD HH:MM	/api/v2/measurements/temporalRanges
illuminations	measured during Day, at Night, or at polar day/night Boundary	/api/v2/measurements/illuminations
regions	All Regions are specified using a region type and either a text field or a set of decimal cartesian coordinates. Region types must be one of [BBOX] or [ENVELOPE] or [MBR] : minimum bounding rectangle [WKT] : a "Well Known Text" (WKT) geometry string [POLY] : a closed polygon [PA] : a protected area [AA] : an administrative area (currently, only countries are supported, using ISO country name or abbreviation) [TILE] : a MODAPS sinusoidal tile identifier North and South coordinates are relative to the equator, East and West coordinates are relative to the Prime (Greenwich) Meridian. Regions can have the following forms: Bounding box ordinates can be in any order. The edge that the ordinate (N=north, S=south, W=west, E=east) applies to starts the coordinate: [BBOX]N21.5 S20.5 E12 W-15 [ENVELOPE]W-140 N-30 E-134.159 S-45.6 [MBR]E-134.159 W-140 S-45.6 N-30 in (WKT) strings, coordinates are always x y pairs [WKT]POINT (30 10) as an alternative to WKT, simple closed, convex polygons can be specified using x y cartesian coordinate pairs [POLY][30 10 40 40 20 40 10 20 30 10] protected areas are specified by name [PA]Acid Shale-Pine Forest administrative areas are specified by name (currently, only countries are supported, using ISO country name or abbreviation) [AA]USA [AA]United States tile identifiers are of the form HxxVyy, where xx is the horizontal tile number, and yy is the vertical tile number. Currently, only MODAPS Sinusoidal tiles are supported (see https://modis-land.gsfc.nasa.gov/MODLAND_grid.html)	/api/v2/measurements/regions
pges	from specified PGEs	/api/v2/measurements/pges
scienceDomains	from specified science domains	/api/v2/measurements/scienceDomains
layers	containing specified layers	/api/v2/measurements/layers
images	source of specified images	/api/v2/measurements/images

details about the root archive directory
- /api/v2/content/details
details about all the files that match the query parameters
- /api/v2/content/details?products=VNP14&temporalRanges=2019-10-23..2019-11-06&regions=[BBOX]W-125 N40 E-119.6 S36.5

POST

Returns details about a resource or set of resources. The resource is specified by fileName or fileId POST parameter. This can handle longer request lists than a GET.

Param Name	Param Description	Param Type
fileIds	with the specified fileId	/api/v2/content/fileIds
fileNames	with the specified fileName, can include wildcards after the YEARDAY field, for example: MOD03.A2020123.*	/api/v2/content/fileNames

details about all the files that match the query parameters
- /api/v2/content/details with POST parameter fileIds=12345,67891
- /api/v2/content/details with POST parameter fileNames=MOD123.A2001123.h24v13.061.872387398412308.hdf,MYD123.A2001123.h24v13.061.99878276350394.hdf

details/{resourceId}

GET

for directories, returns a JSON list of directory contents
for files, returns information about the file

Param Name	Param Description	Param Type
resourceId	path to resource	string matching /^[a-zA-Z0-9\.\s\#\*/_,&:+-]+$/
fields	names of information fields desired in the output	string matching /^[a-zA-Z0-9\.\,\s\?\*_:\|-]+$/
formats	format for desired output	one of [json, html, csv]

JSON list of the "/MAS_eMAS/Spokane_1996/96_160/MASL1B/" directory
- /api/v2/content/details/MAS_eMAS/Spokane_1996/96_160/MASL1B/
information about the file named "VJ102IMG.A2020332.0106.002.2020332060828.nc"
- /api/v2/content/details/VJ102IMG.A2020332.0106.002.2020332060828.nc
information about the file at "allData/61/MYD07_L2/2016/043/MYD07_L2.A2016043.0000.061.2018055112748.hdf"
- /api/v2/content/details/allData/61/MYD07_L2/2016/043/MYD07_L2.A2016043.0000.061.2018055112748.hdf

version

GET

returns the GitLab Tag of this installed namespace.

/api/v2/content/version