# usgs

usgs is a Python library for interfacing with the US Geologic Survey’s Inventory Service. The Inventory Service supports a variety of requests for accessing USGS datasets, including searching datasets, downloading data products, and accessing metadata on data products.

Note

All requests require an account with USGS’s EROS service. The account must also have Machine to Machine privileges.

Note

As of May 15, 2017 the USGS has deprecated their SOAP API. This library has been updated to use their JSON API. As a result most, if not all, responses through this client will have a different structure compared to the older SOAP version.

Note

This library currently uses version 1.4 of the USGS Inventory Service API.

## Installation

    pip install usgs

## Examples

These two examples demonstrate how to access metadata for a Hyperion scene and Landsat 8 scene. Both datasets are part of the EarthExplorer catalog. Hyperion is designated by the dataset `EO1_HYP_PUB`, Landsat 8 is designated by `LANDSAT_8`.

### Python

    from usgs import api

    # Set the EarthExplorer catalog
    node = 'EE'

    # Set the Hyperion and Landsat 8 dataset
    hyperion_dataset = 'EO1_HYP_PUB'
    landsat8_dataset = 'LANDSAT_8'

    # Set the scene ids
    hyperion_scene_id = 'EO1H1820422014302110K2_SG1_01'
    landsat8_scene_id = 'LC80290462015135LGN00'

    # Submit requests to USGS servers
    api.metadata(hyperion_dataset, node, [hyperion_scene_id])
    api.metadata(landsat8_dataset, node, [landsat8_scene_id])

### Command Line

    $ usgs metadata --node EE EO1_HYP_PUB EO1H1820422014302110K2_SG1_01
    {
      "errorCode": null,
      "executionTime": 1.6408669948578,
      "data": [
        {
          "metadataUrl": "https://earthexplorer.usgs.gov/metadata/xml/1854/EO1H1820422014302110K2_SG1_01/",
          "upperLeftCoordinate": {
            "latitude": 26.253489,
            "longitude": 21.53022
          },
          "fgdcMetadataUrl": "https://earthexplorer.usgs.gov/fgdc/1854/EO1H1820422014302110K2_SG1_01/save_xml",
          "displayId": "EO1H1820422014302110K2_SG1_01",
          "acquisitionDate": "2014-10-29",
          "browseUrl": "https://earthexplorer.usgs.gov/browse/eo-1/hyp/182/42/2014/EO11820422014302110K2_SG1_01.jpeg",
          "dataAccessUrl": "https://earthexplorer.usgs.gov/order/process?dataset_name=EO1_HYP_PUB&ordered=EO1H1820422014302110K2_SG1_01&node=INVSVC",
          "orderUrl": "https://earthexplorer.usgs.gov/order/process?dataset_name=EO1_HYP_PUB&ordered=EO1H1820422014302110K2_SG1_01&node=INVSVC",
          "upperRightCoordinate": {
            "latitude": 26.240475,
            "longitude": 21.602509
          },
          "summary": "Entity ID: EO1H1820422014302110K2_SG1_01, Acquisition Date: 29-OCT-14, Target Path: 182, Target Row: 42",
          "downloadUrl": "https://earthexplorer.usgs.gov/download/external/options/EO1_HYP_PUB/EO1H1820422014302110K2_SG1_01/INVSVC/",
          "lowerLeftCoordinate": {
            "latitude": 24.365584,
            "longitude": 21.074194
          },
          "modifiedDate": "2017-03-22",
          "startTime": "2014-10-29",
          "sceneBounds": "21.074194,24.352528,21.602509,26.253489",
          "ordered": false,
          "entityId": "EO1H1820422014302110K2_SG1_01",
          "endTime": "2014-10-29",
          "lowerRightCoordinate": {
            "latitude": 24.352528,
            "longitude": 21.145425
          },
          "bulkOrdered": false
        }
      ],
      "api_version": "1.2.1",
      "error": ""
    }

    $ usgs metadata --node EE LANDSAT_8 LC80290462015135LGN00
    {
      "errorCode": null,
      "executionTime": 1.7327969074249,
      "data": [
        {
          "metadataUrl": "https://earthexplorer.usgs.gov/metadata/xml/4923/LC80290462015135LGN00/",
          "upperLeftCoordinate": {
            "latitude": 21.27723,
            "longitude": -104.10944
          },
          "fgdcMetadataUrl": "https://earthexplorer.usgs.gov/fgdc/4923/LC80290462015135LGN00/save_xml",
          "displayId": "LC80290462015135LGN00",
          "acquisitionDate": "2015-05-15",
          "browseUrl": "https://earthexplorer.usgs.gov/browse/landsat_8/2015/029/046/LC80290462015135LGN00.jpg",
          "dataAccessUrl": "https://earthexplorer.usgs.gov/order/process?dataset_name=LANDSAT_8&ordered=LC80290462015135LGN00&node=INVSVC",
          "orderUrl": "https://earthexplorer.usgs.gov/order/process?dataset_name=LANDSAT_8&ordered=LC80290462015135LGN00&node=INVSVC",
          "upperRightCoordinate": {
            "latitude": 20.90999,
            "longitude": -102.32534
          },
          "summary": "Entity ID: LC80290462015135LGN00, Acquisition Date: 15-MAY-15, Path: 29, Row: 46",
          "downloadUrl": "https://earthexplorer.usgs.gov/download/external/options/LANDSAT_8/LC80290462015135LGN00/INVSVC/",
          "lowerLeftCoordinate": {
            "latitude": 19.54002,
            "longitude": -104.50364
          },
          "modifiedDate": "2017-02-07",
          "startTime": "2015-05-15",
          "sceneBounds": "-104.50364,19.17102,-102.32534,21.27723",
          "ordered": false,
          "entityId": "LC80290462015135LGN00",
          "endTime": "2015-05-15",
          "lowerRightCoordinate": {
            "latitude": 19.17102,
            "longitude": -102.73968
          },
          "bulkOrdered": false
        }
      ],
      "api_version": "1.2.1",
      "error": ""
    }

## Catalogs

USGS provides four catalogs, each containing various datasets. All requests made to the Inventory Service must have an associated node.

Check each catalog for a list of datasets.

Catalog | Node Value | URI
--- | --- | ---
CWIC/LSI Explorer | CWIC | http://lsiexplorer.cr.usgs.gov
EarthExplorer | EE | http://earthexplorer.usgs.gov
HDDSExplorer | HDDS | http://hddsexplorer.usgs.gov
LPCSExplorer | LPCS | http://lpcsexplorer.cr.usgs.gov

Contents:

- USGS CLI
  - Login
  - Logout
  - Search
  - Metadata
  - Download Options
  - Download URL
- USGS API
  - Examples
- USGS Payloads
  - `dataset_download_options()`
  - `dataset_filters()`
  - `dataset_search()`
  - `download_options()`
  - `download_request()`
  - `login()`
  - `scene_metadata()`
- CWIC/LSI Explorer
- EarthExplorer
- HDDSExplorer
- LPCSExplorer

# Indices and tables

- Index

- Module Index