PMM Publisher Documentation

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 interpreting 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_3hr - GPM IMERG "Early Run" 3 Hour Precip. Accumulation
- precip_3hr_1d - GPM IMERG "Early Run" 1 Day Precip. Accumulation Updated Every 3 Hours
- 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_3h4 - Global Landslide Nowcast Updated Every 3hr
lat= The target latitude 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 parameters will have no effect. Not specifying a latitude and/or longitude will result in Global data being returned.
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 formatted according to the W3C "Activity Streams" specification. Learn more about activity streams here:

Displaying Vector Files

We have used Mapbox.js to display vector-based datasets (topoJSON, geoJSON) within the web browser, although other tools can be used as well. Please refer to the following resources for guidance:

Vector vs. Raster Data

There are two ways that precipitation accumulation data are represented in the files available in the PMM Publisher: Vector (GeoJSON, Shapefile, TopoJSON) and Raster (GeoTIFF)

Vector files contain overlapping contours where a geographic point's value is represented as more than the largest contour containing that point. For example, if a point has it's maximum contour as 120 mm, that means that the precipitation accumulation value is greater than 120 mm but less than the next interval of contour (200 mm).

Raster files contain point values on a 0.1x0.1 degree grid. These values are in units of tenths of a millimeter, so if a point's value is 1561, that means the precipitation accumulation there is 156.1 mm.

For more information on the tiff files from which all of the PMM Publisher precipitation accumulation files are generated, check out this documentation

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"
            }
          ]
        }
      ]
    }
  ]
}