Getting Started


  1. Prerequisites

    • A valid API key provided by SkyWatch
    • Software that can read .jp2 images
    • Software that can read .geotiff 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.

    For reading GeoTiff & JP2 images, we recommend downloading ESA's SNAP tool included in their Sentinel Toolboxes package. You can download the installer here.

    Alternate cross platform software packages include Orfeo Toolbox & QGIS

  2. Setup

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

    Mac & Linux

    cURL is pre-installed.

    Windows

    cURL is not installed by default.

    You can download a cURL installer by going to the cURL Download Wizard. Choose a link that has SSL enabled. After running the installer, you should now be able to execute curl 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. Creating Your First Pipeline

    To get started, we are going to set your first pipeline to that will enable you to access data from a satellite to your application in less than a minute. Will begin by accessing open data for the Palm Jumeirah in India . We will select a True Colour output with the following configuration:

    To set your pipeline, paste in the following line of code but replace << API key here >> with your valid API key:

    curl -X POST \
    https://api.skywatch.co/earthcache
      -H 'x-api-key: << API key here >>' \
      -d '{
      "ai_id": "154311a8-582a-11e7-b30d-7291b81e23e",
      "aoi_location": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              55.10240321070188,
              25.13560990301876
            ],
            [
              55.10905944159276,
              25.08705813454641
            ],
            [
              55.17229363502395,
              25.09743978812992
            ],
            [
              55.15010619872962,
              25.150673771076626
            ],
            [
              55.10240321070188,
              25.13560990301876
            ]
          ]
        ]
      },
      "cloudcover": 50,
      "end_date": "2017-08-26",
      "intervals": "7d",
      "resolution_low": 10,
      "start_date": "2017-07-30",
      "tags": [
        {
          "tag": "Name",
          "value": "DUBAI  - Getting Started"
        }
      ]
    }'
                    

    Let's break down how this call is getting us what we want:

    "ai_id": "154311a8-582a-11e7-b30d-7291b81e23e" is the ID for the True Colour output. You can discover our available outputs by using our ai API

    "aoi_location" is the GeoJSON object that defines the the polygon of the location to be analysed. It is important that the coordinates are long/lat pairs and that the first pair is the same as the last pair to close the polygon.

    "resolution_low": 30 specifies the date that begins the collection of results of the location.

    "intervals": "7d" specifies the regularity of the data to be returned of the location. The unit of time is by days.

    "start_date": "2017-07-30" specifies the date that begins the collection of results of the location.

    "end_date": "2017-08-26" specifies the date in which the collection of results ends.

    "cloudcover": 50 specifies the cloud cover threshold. In this case, 50, indicates that 50% or less of cloud cover is acceptable on the polygon.

    "tags" are a list of custom identifiers that you can set for searching and categorizing Pipelines.

    NOTE: ai_id, start_date, intervals and resolution_low are the only required parameters.

    After pressing enter you should see a response of a JSON object containing the complete configuration of your Pipeline. It should look similar to the following:

    {
      "id": "<< PIPELINE ID >>",
      "createdAt": 1506526454227,
      "updatedAt": 1506526454227,
      "resolution_low": 30,
      "user_id": "<< USER ID >>",
      "end_date": "2017-08-26",
      "tags": [
        {
          "tag": "Name",
          "value": "DUBAI - TEST - Getting Started"
        }
      ],
      "deleted": false,
      "aoi_location": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              55.10240321070188,
              25.13560990301876
            ],
            [
              55.10905944159276,
              25.08705813454641
            ],
            [
              55.17229363502395,
              25.09743978812992
            ],
            [
              55.15010619872962,
              25.150673771076626
            ],
            [
              55.10240321070188,
              25.13560990301876
            ]
          ]
        ]
      },
      "intervals": "7d",
      "api_key": "<< API KEY >>",
      "start_date": "2017-07-30",
      "ai_id": "154311a8-582a-11e7-b30d-7291b81e23e",
      "active": true,
      "cloudcover": 0,
      "resolution_high": 0,
      "budget": 0,
      "output_format": "geotiff",
      "area": 33.732752772817385,
      "priority": [
        "cost",
        "recent",
        "cloudcover",
        "resolution",
        "first"
      ],
      "interval_slack": "3d"
    }

    Congratulations! You have just successfully created your first Pipeline using the SkyWatch API! Easy right?

    Now, let's easily make a change to the newly set Pipeline by moving to the next section, "Editing a Pipeline".

  4. Editing a Pipeline

    So, you have now created a pipeline, but you want to make an adjustment, whether that is to change the location, output format, or any of the other configurable parameters, we will show you how this can be done.

    In this case, we are going to change the following:

    • intervals from 7 days (7d) to 30 days (30d), and also change the start and end dates of the Pipeline.
    • start_date from July 30th, 2017 to August 13th, 2017
    • end_date from September 26th, 2017 to October 13th, 2017

    To accomplish this, execute the following curl command:

    curl -X PUT \
    https://api.skywatch.co/earthcache/<< Pipeline id >>
      -H 'x-api-key: << API key here >>' \
      -d '{
      "intervals": "30d",
      "start_date": "2017-08-13",
      "end_date": "2017-09-13"
    }'
    

    After submitting your changes, you should see a JSON object returned to you containing your Pipelines updated configuration.

    In the next section we will explain how to download your results.

  5. Downloading Data

    To download your results, simply perform a GET from the EarthCacheâ„¢ Results endpoint as follows:

    curl -X GET https://api.skywatch.co/earthcache/results/<< PIPELINE ID >>
      -H 'x-api-key: << API KEY >>'

    You will be returned the download paths to the available results, as seen below:

    [
      {
        "deleted": false,
        "updatedAt": 1505857539,
        "result_date": "2017-07-30--2017-08-06",
        "aoi_id": "<< PIPELINE ID >>",
        "createdAt": 1505857478,
        "results": [
          {
            "download_path": "<< DOWNLOAD URL >>",
            "aoi_key": "<< PIPELINE ID >>",
            "result_message": "available",
            "result_status": "complete",
            "capture_time": "2017-07-30--2017-08-06"
          }
        ]
      }
    ]

    Note: Results will take 5-10 minutes to populate for Open Data pipelines. Commercial data pipelines will populate within 2-7 business days.

    It is possible to receive multiple download links within the same period. This could be a result of multiple images captured within the interval range, as well as images that are part of different tiles if your location crosses the tile seams.

    You now know how to create, edit and generate results for a pipeline. For further information, please see more details within the EarthCache tab within the left hand menu, or contact support@skywatch.co