PMM Publisher API Documentation
Friday, November 18, 2016
Overview
The PMM Publisher API can be used to automatically retrieve precipitation and related applications datasets and associated metadata for further processing by your tool of choice. Here we will outline the basic structure of requesting data from the API and interpretting the API response.
Initial Request
The initial request will return a collection of datasets (in the form of a structured JSON object) that match to the parameters you specify, including associated metadata about each dataset. You can then use the actions specified within the object returned to download the actual data you require or perform additional related actions.
Make a GET or POST request to https://pmmpublisher.pps.eosdis.nasa.gov/opensearch and include parameters that define the type of data you'd like to receive. You can use this tool to generate example requests: https://pmmpublisher.pps.eosdis.nasa.gov/swagger/index.html#/opensearch
Request Parameters
- q= The PMM dataset you are attempting to retrieve. The current possible values are:
- precip_30mn - GPM IMERG "Early Run" 30 Minute Precip. Accumulation
- precip_30mn_3hr - GPM IMERG "Early Run" 3 Hour Precip. Accumulation Updated Every 30 minutes
- precip_30mn_1d - GPM IMERG "Early Run" 1 Day Precip. Accumulation Updated Every 30 minutes
- precip_1d - GPM IMERG "Late Run" 1-Day Precip. Accumulation
- precip_3d - GPM IMERG "Late Run" 3-Day Precip. Accumulation
- precip_7d - GPM IMERG "Late Run" 7-Day Precip. Accumulation (learn more about GPM IMERG datasets)
- flood_nowcast - Floods Nowcast (learn more about the UMD Floods Nowcast)
- global_landslide_nowcast - Global Landslide Nowcast (learn more about the Global Landslide Nowcast)
- global_landslide_nowcast_30mn - Global Landslide Nowcast Updated Every 30mn
- lat= The target lattitude of the data to be retrieved. GPM IMERG data has been subsetted into 10 regions which span the globe. Specifying a lat/lon anywhere within one of those regional boxes will retrieve the data for that region. Flood and landslide data are always global so the lat/lon paremeters will have no effect. To obtain global datasets, omit the lat and lon parameters.
- lon= The target longitude of the data to be retrieved.
- limit= Limits the number of results returned to the specified value.
- startTime= The earliest date of the data you would like to retrieve, in the format YYYY-MM-DD. Data is available for 60 days from the current day.
- endTime= The latest date of the data you would like to retrieve, in the format YYYY-MM-DD.
Response
A successful request to the API will return a JSON object in response, which is formated according to the W3C "Activity Streams" specification. Learn more about activity streams here:
- https://www.w3.org/TR/activitystreams-core/
- https://www.w3.org/TR/2014/WD-activitystreams-core-20141023/
Displaying Vector Files
We have used Mapbox.js to display vector-based datasets (topoJSON, geoJSON) within the web browser, although other tools are possible. Please refer to the following resources for guidance:
Example Request / Response
Below is a typical request with its associated response. Comments have been added to the JSON response file to indicate specific fields of interest.
Request URL
https://pmmpublisher.pps.eosdis.nasa.gov/opensearch?q=precip_1d&lat=38&lon=100&limit=1&startTime=2016-11-12&endTime=2016-11-12
Response Body
{
"@context": "http://pmmpublisher.pps.eosdis.nasa.gov/vocab",
"@language": "en",
"@id": "urn:ojo:opensearch:q=precip_1d&lat=38&lon=100&limit=1&startTime=2016-11-12&endTime=2016-11-12",
"displayName": "NASA GSFC Product Publisher",
"@type": "as:Collection",
"url": "http://pmmpublisher.pps.eosdis.nasa.gov/opensearch?q=precip_1d&lat=38&lon=100&limit=1&startTime=2016-11-12&endTime=2016-11-12",
"mediaType": "application/activity+json",
//total number of results returned from the query
"totalItems": 1,
//array of length = totalItems, each of which is one dataset that matches the request parameters
"items": [
{
"@id": "gpm_1d_20161112",
"@type": "geoss:precipitation",
"displayName": "gpm_1d_20161112",
//preview .png image of this dataset
"image": [
{
//request this URL to access the preview image
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/s3/r09/gpm_1d/2016/317/gpm_1d.20161112_thn.png",
"mediaType": "image/png",
"rel": "browse"
}
],
//bounding boxes of the region displayed in this dataset (region is determined by lat/lon parameters)
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
90,
10
],
[
90,
60
],
[
180,
60
],
[
180,
10
],
[
90,
10
]
]
]
},
//metadata for this dataset
"properties": {
"source": {
"@label": "source",
"@value": "NASA GSFC GPM"
},
//dataset source
"url": {
"@label": "url",
"@value": "https://pmm.nasa.gov/data-access/downloads/gpm"
},
"sensor": {
"@label": "sensor",
"@value": "GPM"
},
"date": {
"@label": "date",
"@value": "20161112"
},
"resolution": {
"@label": "resolution",
"@value": "0.1deg"
}
},
//actions that can be performed with this dataset (this is how you will download the actual dataset files)
"action": [
{
"@type": "ojo:browse",
"displayName": "browse",
"using": [
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "browse",
"mediaType": "html",
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/gpm_1d/browse/r09/2016/317/gpm_1d.20161112",
"displayName": "browse"
}
]
},
{
"@type": "ojo:download",
"displayName": "download",
//array of dataset downloads
"using": [
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "gpm_1d.20161112.topojson.gz",
"mediaType": "application/x-gzip",
//url to download topoJson file
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/s3/r09/gpm_1d/2016/317/gpm_1d.20161112.topojson.gz",
"displayName": "topojson.gz"
},
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "gpm_1d.20161112.tif",
"mediaType": "image/tiff",
//url to download geoTIFF file
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/s3/r09/gpm_1d/2016/317/gpm_1d.20161112.tif",
"displayName": "geotiff"
}
]
},
{
"@type": "ojo:map",
"displayName": "map",
"using": [
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "legend",
"mediaType": "text/html",
//url to access the dataset legend
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/mapinfo/gpm_1d/legend?product=gpm_1d",
"displayName": "legend"
},
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "style",
"mediaType": "application/json",
//url to access the dataset style (default color tables)
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/mapinfo/gpm_1d/style?product=gpm_1d",
"displayName": "style"
},
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "credits",
"mediaType": "application/json",
//url to download the credits for this dataset
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/mapinfo/gpm_1d/credits",
"displayName": "credits"
}
]
},
{
"@type": "ojo:subset",
"displayName": "subset",
"using": [
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "subset",
"mediaType": "application/vnd.geo+json",
//url to spatially subset this dataset (experimental, only works for certain datasets)
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/gpm_1d/subset/r09/2016/317/gpm_1d.20161112?bbox={LLlon},{LLlat},{URLon},{URLat}",
"displayName": "subset"
}
]
},
{
"@type": "ojo:metadata",
"displayName": "metadata",
"using": [
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "metadata",
"mediaType": "application/json",
//url to access metadata about this file
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/gpm_1d/metadata/r09/2016/317/gpm_1d",
"displayName": "metadata"
}
]
},
{
"@type": "ojo:export",
"displayName": "export",
//array containing additional dataset downloads in various formats
"using": [
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "geojson",
"mediaType": "application/json",
//url to download the dataset in geoJSON format
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/gpm_1d/export/r09/2016/317/gpm_1d.20161112.geojson",
"displayName": "geojson"
},
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "arcjson",
"mediaType": "application/json",
//url to download the data in arcJSON format
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/gpm_1d/export/r09/2016/317/gpm_1d.20161112.arcjson",
"displayName": "arcjson"
},
{
"@type": "as:HttpRequest",
"method": "GET",
"@id": "shp.zip",
"mediaType": "application/zip",
//url to download the data in SHP (shapefile) format
"url": "https://pmmpublisher.pps.eosdis.nasa.gov/products/gpm_1d/export/r09/2016/317/gpm_1d.20161112.shp.zip",
"displayName": "shp.zip"
}
]
}
]
}
]
}