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)

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)

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

usgs.api.login(username, token, save=True)

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.

• token (str) – Application Token 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()

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

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

Request metadata for a given scene in a USGS dataset.

Parameters:

• dataset (str)

• entity_id (str)

• api_key (str)

usgs.api.scene_search(dataset, max_results=5000, metadata_type=None, start_date=None, end_date=None, ll=None, ur=None, lat=None, lng=None, distance=100, where=None, scene_filter=None, starting_number=1, sort_order='DESC', api_key=None)

Parameters:

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

• lat (str) – Latitude

• lng (str) – Longitude

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

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

• ur (dict) – 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 (str) – Start date for when a scene has been acquired

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

• where (dict) – 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 (int) – Maximum results returned by the server

• scene_filter (dict) – Additional filters to apply to the “sceneFilter”. Can override filters set using other parameters. e.g. {“ingestFilter”: {“start”: “2010-01-01”, “end”: “2012-01-31”}}

• starting_number (int) – Starting offset for results of a query.

• sort_order (str) – Order in which results are sorted. Ascending or descending w.r.t the acquisition date.

• api_key (str) – API key for EROS. Required for searching.