USGS API

Examples

The where parameter used for searching a USGS dataset is best understood by example.

from usgs import api


def submit_where_query():

    # USGS uses numerical codes to identify queryable fields
    # To see which fields are queryable for a specific dataset,
    # send off a request to dataset-fields

    results = api.dataset_fields('LANDSAT_8_C1', 'EE')

    for field in results['data']:
        print field

    # WRS Path happens to have the field id 20514
    where = {
        20514: '043'
    }
    results = api.search('LANDSAT_8_C1', 'EE', where=where, start_date='2017-04-01', end_date='2017-05-01', max_results=10, extended=True)

    for scene in results['data']['results']:
        print scene
usgs.api.dataset_download_options(dataset, api_key=None)[source]

The dataset download options method is used to discover downloadable products for a specified dataset. Unlike the download_options method, this does not check product availability.

Parameters:

dataset (str) – Used to identify the which dataset to return results for.

usgs.api.download_request(dataset, entity_id, product_id, api_key=None)[source]

This method is used to insert the requested downloads into the download queue and returns the available download URLs.

usgs.api.login(username, password, save=True)[source]

Log in, creating a temporary API key and optionally storing it for later use.

Parameters:
  • username (str) – Username of the USGS account to log in with.

  • password (str) – Password of the USGS account to log in with.

  • save (bool) – If true, the API key will be stored in a local file (~/.usgs) until api.logout is called to remove it. The stored key will be used by other functions to authenticate requests whenever an API key is not explicitly provided.

usgs.api.logout()[source]

Log out by deactivating and removing the stored API key, if one exists.

usgs.api.scene_metadata(dataset, entity_id, api_key=None)[source]

Request metadata for a given scene in a USGS dataset.

Parameters:
  • dataset (str) –

  • entity_id (str) –

  • api_key (str) –

Parameters:
  • dataset – USGS dataset (e.g. EO1_HYP_PUB, LANDSAT_8)

  • lat – Latitude

  • lng – Longitude

  • distance – Distance in meters used to for a radial search

  • ll – Dictionary of longitude/latitude coordinates for the lower left corner of a bounding box search. e.g. { “longitude”: 0.0, “latitude”: 0.0 }

  • ur – Dictionary of longitude/latitude coordinates for the upper right corner of a bounding box search. e.g. { “longitude”: 0.0, “latitude”: 0.0 }

  • start_date – Start date for when a scene has been acquired

  • end_date – End date for when a scene has been acquired

Where:

Dictionary representing key/values for finer grained conditional queries. Only a subset of metadata fields are supported. Available fields depend on the value of dataset, and maybe be found by submitting a dataset_filters query.

Max_results:

Maximum results returned by the server

Starting_number:

Starting offset for results of a query.

Sort_order:

Order in which results are sorted. Ascending or descending w.r.t the acquisition date.

Api_key:

API key for EROS. Required for searching.