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.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) –
- 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, starting_number=1, sort_order='DESC', api_key=None)[source]¶
- 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.