This repository has been archived by the owner. It is now read-only.
Documentation and tools for the SkyWatch API
Switch branches/tags
Nothing to show
Clone or download
skywatchspaceapps Update README.md
NO LONGER APPLICABLE - The following documentation is out-of-date - For further details please visit the SkyWatch [website](https://www.skywatch.co/)
Latest commit 966a3c0 Nov 17, 2017
Permalink
Failed to load latest commit information.
examples
CHANGELOG.md
EXAMPLES.md
README.md

README.md

SkyWatch API

NO LONGER APPLICABLE - The following documentation is out-of-date - For further details please visit the SkyWatch website

Table of Contents

  1. Overview
  2. API Usage
  3. Search Results, Limits, and Downloading the Data
  4. API Fields
  5. Example API Calls
  6. Dataset Documentation
  7. HDF Documentation and Resources
  8. Known Issues
  9. Troubleshooting

Overview

Through the API you can access the following satellite imagery and climate/atmospheric datasets:

  • Sentinel-2 (Data level: level 1 - imagery only)
  • Landsat-8 (Data level: level 1 - imagery only)
  • AIRS (Data level: level 2 and 3)
  • GOSAT/ACOS (Data level: level 2 and 3)
  • MOPITT (Data level: level 1 and 3)
  • OCO-2 (Data level: level 2 only)
  • TES (Data level: level 2 and 3)

You can use the API to search satellite imagery and datasets by wavelength (band), cloud cover, resolution, data level, source, location, and date-time.

API calls through the Command-Line Interface (CLI) or programmatically will return a JSON (JavaScript Object Notation) response with a signed URL to download imagery and datasets that meet the search criteria.

API Usage

curl -H "x-api-key: <api-key>" https://api.skywatch.co/data/time/<time-period>/location/<longitude-latitude>/source/<instrument-satellite>/level/<data-level>/resolution/<max-resolution>/cloudcover/<max-cloudcover>/band/<wavelength-band>

NOTE: time/<time-period> and location/<longitude-latitude> are the only two mandatory fields - others are optional. The order of the fields is not important, and fields can be omitted.

Search Results, Limits, and Downloading the Data

The search results from the JSON response are sorted by descending order of the date and time the image or the data were captured.

The current API limits are 1000 requests per second, and 2000 bursts per request. API calls must complete within 30 seconds.

Each signed URL can be directly downloaded through a browser or programmatically, which expires 1 hour after being generated. If downloading via wget ensure double qoutes (") are around the signed URL.

API Fields

api-key

If you would like an API key please sign-up to be added to the list.

time-period

One or two UTC timestamps in ISO format (yyyy-mm-ddThh:mm:ss.sssss+|-zzzz). Partial or complete dates and timestamps can be specified (e.g. 2009, 2009-12, 2009-12-25, 2009-12-25T13:25:00.0000+0000). If no time is specified, midnight UTC on the day in question is assumed.

If only one timestamp is passed in, the range of one day is assumed. For example, if 2009-12-25 is specified, the search takes place as if 2009-12-25T00:00:00.0000+0000,2009-12-25T23:59:59.9999+9999 was specified. If the single timestamp is a month, that entire month is searched. For example if 2015-09 is specified, the search takes place as if midnight 2015-09-01 to midnight 2015-10-01 was specified. If a single year is specified, that entire year is searched. For example if 2015 is specified, the search takes place as if midnight 2015-01-01 to midnight 2016-01-01 was specified.

longitude-latitude

A list of longitude, latitude coordinate pairs as a flat, comma-separated list. A list of two numbers represents a point, four numbers is a square area where the coordinates are the corners, or if there are more than four numbers the coordinates represent a closed polygon, where the first point equals the last point in the list. Because this list represents a number of points, there always has to be an even number of numbers in the list.

NOTE: The order of the coordinates for the API is longitude first, followed by latitude. When using applications such as Google Earth, coordinates are presented in latitude followed by longitude.

Examples:

  • Point: -71.1043443253,-42.3150676016
  • Square: -71.1043443253471,-42.3150676015829,71.1043443253471,42.3150676015829
  • Polygon: 43.81173831375078,-79.69345092773438,43.51668853502909,-79.70581054687499,43.463884091369046,-79.38995361328125,43.69865837138954,-79.34463500976562,43.875128129336716,-79.34188842773438,43.81173831375078,-79.69345092773438

instrument-satellite

Search criteria can be specified by the source of the data - either the instrument on-board the satellite or the satellite itself. Single or multiple sources can be specified.

Choice of sources are: ACOS, AIRS, CAI, FTS-SWIR, Landsat-8, MOPITT, OCO2, Sentinel-2 and TES.

This field is not case-sensitive, and multiple sources can be specified (separated by commas).

data-level

The data level is an optional path of the API URL that corresponds to the data processing levels for Earth observation data. Level 1, 2, and 3 (L1, L2, L3) datasets are available. If no data level is specified, datasets of all levels will be returned. Only a single level can be specified.

Choices are: 1, 2, or 3.

max-resolution

This maximum resolution field is only applicable to imagery that's available through the API (i.e. Landsat-8). Resolution is in metres (m). Resolutions less-than or equal-to this value will be returned. The resolution for Landsat-8 is 30 m. All climate/atmospheric datasets have a resolution of 0 m, because it is not applicable. The maximum resolution is 30 m. If resolution is omitted all imagery or data matching other search criteria will be returned.

Resolution must be 0 or greater, and can be a decimal value.

max-cloudcover

This maximum cloud cover field is only applicable to imagery that's available through the API (i.e. Landsat-8). Cloud cover is given as a percentage (%) of the image covered by cloud (0 to 100). Images less-than or equal-to this cloud cover value will be returned. All climate/atmospheric datasets have a cloud cover of 0%, because it is not applicable.If cloud cover is omitted all imagery or data matching other search criteria will be returned.

Cloud cover must be between 0 and 100 (inclusive), and can be a decimal value.

wavelength-band

Search criteria can be specified by the wavelength bands for imagery (i.e. Landsat-8) and by file type for non-imagery data (e.g. Hierarchical-Data-Format).

Choices of bands are: Blue, Cirrus, Coastal-Aerosol, Green, Hierarchical-Data-Format, Datastrip (only for Sentinel-2; metadata for each tile), Near-Infrared, Panchromatic, Red, Short-Wave-Infrared-1, Short-Wave Infrared-2, Thermal-Infrared-1, Thermal-Infrared-2, Vegetation-Red-Edge-1, Vegetation-Red-Edge-2, Vegetation-Red-Edge-3, Vegetation-Red-Edge-4 and Water-Vapor.

This field is not case-sensitive, and multiple bands can be specified (separated by commas).

Example API Calls

Examples of API calls and outputs can be found HERE.

Dataset Documentation

The following list are links to documentation on the individual datasets available through the API:

HDF Documentation and Resources

The following list are links to documentation and resources that relate to HDF (Hierarchical Data Format; .hdf) (HDF4 and HDF5) file formats:

  • HDFView - HDF file viewer
  • HDF5 - applicable for all non-image datasets except AIRS
  • HDF4 - applicable all AIRS datasets
  • Python libraries for HDF:

Known Issues

  • API calls that take longer than 30 seconds to complete will time out. We recommend refining your search criteria to be narrow enough to complete within 30 seconds.

Troubleshooting

For any issues or questions, please contact dexter@skywatch.co.