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.download(dataset, node, entityids, product='STANDARD', api_key=None)[source]

Though USGS supports multiple products in a single request, there’s ambiguity in the returned list. This wrapper only allows a single product per request.

Additionally, the response has no indiction which URL is associated with which scene/entity id. The URL can be parsed, but the structure varies depending on the product.

usgs.api.metadata(dataset, node, entityids, extended=False, api_key=None)[source]

Request metadata for a given scene in a USGS dataset.

Parameters:
  • dataset –
  • node –
  • entityids –
  • extended – Send a second request to the metadata url to get extended metadata on the scene.
  • api_key –
usgs.api.search(dataset, node, lat=None, lng=None, distance=100, ll=None, ur=None, start_date=None, end_date=None, where=None, max_results=50000, starting_number=1, sort_order='DESC', extended=False, api_key=None)[source]
Parameters:
  • dataset – USGS dataset (e.g. EO1_HYP_PUB, LANDSAT_8)
  • node – USGS node representing a dataset catalog (e.g. CWIC, EE, HDDS, LPVS)
  • 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_fields 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.
Extended:

Boolean flag. When true a subsequent query will be sent to the metadataUrl returned by the first query.
Api_key:

API key for EROS. Required for searching.