Getting Started


  1. Prerequisites

    • A valid API key provided by SkyWatch
    • Software that can read .jp2 images

    If you do not have an API key, please fill out a request form. If your API key no longer works, please contact the support contact that provided you with the API key.

    GIMP is free software that can view .jp2 files on Mac and Linux operating systems. For Windows users, IrfanView is a lightweight option to view .jp2 file. Photoshop can also be used to view .jp2 files if you already own the software. If you have previously installed a .jp2 file viewer, you’re good to go!
    NOTE: If using IrfanView, you will also need to download the plugins to view .jp2 files.

  2. Setup

    For this quick start guide we will be demonstrating API requests to the SkyWatch API via cURL & wget.

    Mac & Linux

    cURL is pre-installed.

    wget on Mac can be installed via Homebrew (https://brew.sh/) using brew install wget

    Windows

    cURL is not installed by default but can be installed in a variety of methods.

    Chocolately

    If you use Chocolately, in your command prompt, run choco install curl. After it finishes, you should now be able to execute cURL commands.

    Running choco install wget will install wget on your machine. Upon completion you should be able to execute wget commands in your command prompt.

    Using Bash

    Later versions of Windows 10 allow for the use of the Bash shell and linux environment directly in Windows. While not enabled by default, you can enable it by following Microsoft’s guide here.

    If you are running an older version of Windows or would prefer another alternative you can use the bash terminal that can be installed with git. You can download git & bash from here. Once the installer is complete, you should see a new entry in the start menu for ‘Git Bash’. Opening this application will allow you to run cURL.

    Download Installer

    You can download a cURL installer by going to https://curl.haxx.se/download.html. Scroll down to the Win64 - Generic section and download the latest version. After running the installer, you should now be able to execute curl commands.

    https://eternallybored.org/misc/wget/ is a recommended location to install wget from. After running the installer, you should now be able to execute wget commands.

    Test cURL

    In your terminal, enter curl https://example.com and press enter. If curl is installed correctly and you have an internet connection, you should see the HTML output in your terminal. If you see the HTML output, you are ready to continue.

  3. Filtering Searches

    Using the search from running your first search as a starting point, we will work towards finding a clear image of the Eiffel Tower. The first issue we have is that we were only returned a single result to choose from. This indicates that only one true colour image was captured on February, 15th, 2017 over the Eiffel Tower. To get more results, we want to start broadening the search criteria; so let’s expand our criteria to search for images available for the months of January and February 2017.

    To do this, update the search’s time parameter from /time/2017-02-15 to /time/2017-01-01,2017-02-28. By providing 2 partial ISO UTC timestamps, we are now requesting a custom time range. Let’s see what results we get from the expanded search.

    It appears that we have a few images to choose from. For our purposes, the image captured on January 26th, 2017 seems like a great choice. It was taken close to our original date & has a cloud cover of 0%! Keep your results, continue to Downloading Data to download and view the Eiffel Tower or move to our Parameters section and experiment with different filters.

  4. Downloading Data

    To download the image, we need to first copy the download link. You can find this in the returned object under the download_path property. The next step is to look under the returned object's `type` property. This is the file type that you will need to save the file as.

    In your terminal, enter in the following command replacing << api key here >> with your valid api key, << download link >> with the link that you copied and << file type >> with the file type to save as. You can also rename the output file to whatever you wish. For our Eiffel Tower image, the file type will be a .jp2 file.

    curl -H "x-api-key:<< api key here >>" << download link >> --output outputFileName.<< file type
                        >>

    Note: On Mac & Linux, the terminal defaults to your home directory. On Windows, it defaults to a nested folder in your user’s appdata folder. We recommend opening a command prompt in either documents or desktop.

    If entered correctly, you should see the file start to download to the directory that the command was executed from. From here, open the file in your preferred image viewer (in our case GIMP). If you zoom in to the pixel coordinates of 4828, 8808 you should be looking at the Eiffel Tower! Looking above the Tower, we can see its shadow being cast too!

    Congratulations! You have successfully downloaded your first image using the SkyWatch API! For the purpose of this quick start guide, we chose to download an image but you can also search for and download non-imagery data such as CO².