podaacpy webservices API

class podaac.Podaac
dataset_metadata(dataset_id='', short_name='', _format='iso')

Dataset metadata service retrieves the metadata of a dataset on PO.DAACs dataset catalog using the following parameters: dataset_id, short_name, and format.

Parameters:
  • dataset_id (string) – dataset persistent ID. dataset_id or short_name is required for this metadata service.
  • short_name (string) – dataset short_name. dataset_id or short_name is required for this metadata service.
  • _format (string) – metadata format. Default format is iso.
Returns:

an xml response based on the requested ‘format’. Options are ‘iso’ and ‘gcmd’.

Dataset Search service searches PO.DAAC’s dataset catalog, over Level 2, Level 3, and Level 4 datasets, using the following parameters: dataset_id, short_name, start_time, end_time, bbox, and others.

Parameters:
  • keyword (string) – keyword specifies search text to search for datasets. Example: ‘modis’
  • start_time (time) – start time in the format of YYYY-MM-DDTHH:mm:ssZ. ‘Z’ is the time-offset, where ‘Z’ signifies UTC or an actual offset can be used. Example: 2012-01-22T01:21:21Z
  • end_time (time) – stop time in the format of YYYY-MM-DDTHH:mm:ssZ. ‘Z’ is the time-offset, where ‘Z’ signifies UTC or an actual offset can be used. Example: 2012-01-22T01:21:21Z
  • start_index (int) – start index of entries found for search. Example: 1
  • items_per_page (int) – number of results per page for opensearch result. If format is not specified, format is set to 50. The value range is from 0 to 400
  • dataset_id (string) – dataset persistent ID. Example: PODAAC-MODSA-T8D9N
  • short_name (string) – dataset short_name. Example: MODIS_AQUA_L3_SST_THERMAL_8DAY_9KM_NIGHTTIME
  • instrument (string) – dataset instrument. Example: MODIS
  • satellite (string) – dataset satellite. Example: AQUA
  • file_format (string) – dataset data format. Possible values: HDF, NetCDF
  • status (string) – dataset status. Possible values: OPEN, PREVIEW, SIMULATED, RETIRED
  • processLevel (string) – dataset processing level. Possible values: 1B, 2, 2P, 3, 4
  • _format (string) – response format. If format is not specified, format is set to atom. Possible values: atom, html.
  • sort_by (string) – determines ordering of response. If sort_by is not specified, sort order is by score (most relevant dataset first). Possible values: timeAsc, timeDesc, popularityAsc, popularityDesc.
  • bbox (string) – bounding box for spatial search. format should look like “bbox=0.0,-45.0,180.0,40.0” which is in order of west, south, east, north. Longitude values needs to be in range of [-180.0,180.0]. Example: 0.0,-45.0,180.0,40.0
  • full (string) – “true” to return response with complete PO.DAAC metadata per entry. If full is not specified, full is set to false. Possible values: true, false
Returns:

the specified response format. If format is not specified, format is set to atom. Possible values: atom, html
dataset_variables(dataset_id)

Given a PO.DAAC dataset identifier this function will return list of dataset variables.

Parameters:dataset_id (string) – dataset persistent ID. dataset_id is required for this metadata service.
Returns:a list of dataset variables for the dataset.
extract_l4_granule(dataset_id='', path='')

This is an additional function that we have provided apart from the available webservices. The extract_l4_granule helps retrieve the level 4 datasets from OPeNDAP server directly, accompanied by the search granule for retrieving granule name related to the specific dataset_id.

Parameters:
  • dataset_id (string) – dataset persistent ID. dataset_id or short_name is required for a granule search. Example: PODAAC-ASOP2-25X01
  • path – Destination directory into which the granule needs to be downloaded.
Returns:

string representation of granule name.
granule_metadata(dataset_id='', short_name='', granule_name='', _format='iso')

Granule metadata service retrieves the metadata of a granule on PO.DAACs catalog in ISO-19115.

Parameters:
  • dataset_id (string) – dataset persistent ID. dataset_id or short_name is required for this metadata service.
  • short_name (string) – dataset short_name. dataset_id or short_name is required for this metadata service.
  • granule_name (string) – granule name. granule name is required for this metadata service.
  • _format (string) – metadata format. Default format is iso.
Returns:

an xml response based on the requested ‘format’.
granule_preview(dataset_id='', image_variable='', path='')

The PODAAC Image service renders granules in the PO.DAACs catalog to images such as jpeg and/or png. This image service also utilizes OGC WMS protocol. (http://www.opengeospatial.org/standards/wms). If the granule does not have any data in the given selected bounding box, HTTP 500 will be thrown since there is no data to be imaged. Granule Search service can be used to find level 2 swath data. However, the level 2 spatial search uses coverage footprint polygons generated for each granule, and this footprint can contain no data or gaps. If the selected bounding box resides on no data or gaps, HTTP 500 will be thrown. There are three request methods in this service. They are GetCapabilities, GetLegendGraphic, and GetMap.

Parameters:
  • dataset_id (string) – dataset persistent ID. dataset_id or short_name is required for a granule search. Example: PODAAC-ASOP2-25X01 string
  • image_variable – variables of the granule which have ‘Preview Images’. Image variables can be found from Dataset Variable service. Use “id” from “imgVariable” element. :type image_variable: string
  • path – Destination directory into which the granule needs to be downloaded.
Returns:

a png image file.

Search Granule does granule searching on PO.DAAC level 2 swath datasets (individual orbits of a satellite), and level 3 & 4 gridded datasets (time averaged to span the globe). Coverage footpritnt polygons are used to enable spatial search on level 2 swath dataset. Currently, our footprints can contain no data and also gaps in the swath data. Spatial search on level 2 data can return granules where actual data does not intersect the selected bounding box but its footprint intersects the selected bounding box. The following parameters are supported: dataset_id, short_name, start_time, end_time, bbox, and others.

Parameters:
  • dataset_id (string) – dataset persistent ID. dataset_id or short_name is required for a granule search. Example: PODAAC-ASOP2-25X01
  • start_time (time) – start time in the format of YYYY-MM-DDTHH:mm:ssZ. ‘Z’ is the time-offset, where ‘Z’ signifies UTC or an actual offset can be used. Example: 2013-01-01T01:30:00Z
  • end_time (time) – stop time in the format of YYYY-MM-DDTHH:mm:ssZ. ‘Z’ is the time-offset, where ‘Z’ signifies UTC or an actual offset can be used. Example: 2014-01-01T00:00:00Z
  • bbox (string) – bounding box for spatial search. format should look like “bbox=0,0,180,90” which is in order of west, south, east, north. Longitude values needs to be in range of [-180, 180]. Latitude values needs to be in range of [-90, 90]. For level 2 datasets, spatial search is available for a subset. Call the list_available_Level2_dataset_ids and list_available_level2_datasetShortNames functions to see the subset. BBox example: 0,0,180,90
  • start_index (int) – start index of entries found for search. Example: 1
  • items_per_page (int) – number of results per page for opensearch result. If format is not specified, format is set to 50. The value range is from 0 to 400
  • sort_by (string) – determines ordering of response. Possible values: timeAsc, timeDesc.
  • _format (string) – response format. If format is not specified, format is set to atom. Possible values: atom, html.
Returns:

an xml response based on the requested ‘format’. Options are ‘atom’ and ‘html’.
granule_subset(input_file_path, path='')

Subset Granule service allows users to Submit subset jobs. Use of this service should be preceded by a Granule Search in order to identify and generate a list of granules to be subsetted. NOTE : At present PODAAC’s granule subsetting service is only restricted to Level2 granules.

Parameters:
  • input_file_path (string) – path to a json file which contains the the request that you want to send to PO.DAAC
  • path (string) – path to a directory where you want the subsetted dataset to be stored.
Returns:

a string token which can be used to determine the status of a subset task.
last24hours_datacasting_granule_md(dataset_id='', short_name='', _format='datacasting', items_per_page=50)

Granule metadata service retrieves metadata for a list of granules archived within the last 24 hours in Datacasting format.

Parameters:
  • dataset_id (string) – dataset persistent ID. dataset_id or short_name is required for this metadata service.
  • short_name (string) – dataset short_name. dataset_id or short_name is required for this metadata service.
  • _format (string) – metadata format. Must set to ‘datacasting’.
  • items_per_page (int) – number of results per page. Default value is 50. The value range is from 0 to 5000.
Returns:

an xml response based on the requested ‘format’. Options are ‘iso’ and ‘gcmd’.
subset_status(token='')

Subset Granule Status service allows users to check the status of submitted subset job. The possible status that it returns include the following..

* "submitted" : returned on successful submission of the request.
* "error" : returned when there is error in the JSON POST request.
* "unknown" : returned when the datasetId you sent is not valid.
* "done" : returned when subsetting job you submitted is done.
Parameters:token (string) – string token that is returned by PO.DAAC whilst submitting a subset request.
Returns:the a status string of the subset request.