User GuideAPI ReferenceWhat's NewQuick Tutorials
ContactAbout Us

Getting Results

Suggest Edits

Getting Results

The GO API provides two mechanisms for retrieving results from your completed project:

  • Synchronously: The API allows you to fetch individual sets of results for your project and have
    them returned to you directly in the HTTP response payloads as JSON objects.
  • Asynchronously: The API also allows you to request all the results be collected into a CSV file
    that is then made available for you to download via S3.

The asynchronous approach is more efficient in terms of network traffic, but at the cost of having
to wait up to half an hour for the download link to be made available.

Both approaches are described in the following sections.

Accessing (Synchronous) Results

When using the synchronous API to access results, some understanding of how GO internally organizes
the data generated from executing a project is required:

  • A Project has one or more AOIs (which can be retrieved via
    GET /projects/$P/versions/$V/aois).

  • Divisions:

    • The data for a completed Project are organized into one or more Divisions
      (GET /projects/$P/versions/$V/divisions).
    • Each Division is associated with an AOI, by matching the Division's division_id field to
      the AOI's id field.
    • Each Division may have zero or more subdivisions; the Division's children field contains a
      list of the ids of the subdivisions (which may, in turn, point to further subdivisions).

  • Results

    • A completed Project has one or more Results (GET /projects/$P/versions/$V/results).
    • The Result object contains information about what kind of data has been produced by the
      algorithm(s) in the Project, such as geographic data, time series data, etc.
    • The division_id field of a Result is used to match that Result with a Division (or
      subdivision).

The relationship between Projects, AOIs, Divisions, and Results can be viewed like this:

1900

Here is an alternative view:

949

In that second view, we see a given Result is associated with a Division, which is in turn
associated with an AOI, and that Result is also associated with actual data in the form of time
series object, geographic information objects, and so on.

In Appendix A, we provide Python 3 code which demonstrates how to navigate these data structures to
access each individual data point.

We next describe two of the types of results returned from GO's algorithms. If you have questions
about other result types or data structures, please contact the Orbital Insight Client Success team
([email protected]).

Timeseries Results
^^^^^^^^^^^^^^^^^^

You can retrieve "time series" data by specifying the time series type from the timeseries
field) as $T for a specific result $R:

GET /projects/$P/versions/$V/results/$R/timeseries/$T

The JSON response will contain one or more measurements expressed as (x,y) pairs:

{
   "x_value": "...",
   "y_value": "..."
}

For the time series types raw.count and scene.subaoi.fillforward.normalized.count, the data
will be a list of X and Y objects that will give the measurement value and the date that the
measurement was taken:

{
      "x_value": {
         "imaging_ts": "2017-05-31 19:16:04Z",
         "field_format": "%Y-%m-%d %H:%M:%SZ"
      },
      "y_value": {
         "measured_count": 2428.0,
         "measurement_id": "53ec7a78-bc5a-4a53-a033-4f4d63824598"
      }
   }

For the time series type change_detection.valid_geoms, the (x,y) pairs will look like:

{
      "x_value": {
         "start_target_timerange": "2018-07-01 00:00:00Z",
         "field_format": "%Y-%m-%d %H:%M:%SZ"
      },
      "y_value": {
         "baseline_timerange": [ "2018-04-01 00:00:00", "2018-07-01 00:00:00"],
         "change_class": "buildings",
         "change_type": "construction",
         "target_timerange": ["2018-07-01 00:00:00", "2018-10-01 00:00:00"],
         "valid_geom": "POLYGON ((...))"
      }
   }

GeoInfo Results
^^^^^^^^^^^^^^^

You can retrieve "geographic information" data with the /geoinfo endpoint:

GET /projects/$P/versions/$V/results/$R/geoinfo

The JSON response will contain a list of the form:

[
      {
         "geom_id": "...",
         "geom": "...",
         "attributes": { "...": "..." }
      },
      "..."
   ]

Getting Results Asynchronously

For very large result sets, it is simpler and more efficient to download the results as a single
large CSV file stored on AWS S3.

First, you must request that the results be made available as an S3 download. This is done as a
POST operation:

POST /projects/$P/versions/$V/results/download

with the request body simply this:

{
    "detail": false
}

The detail field is used to request additional results information. (The
return_tile_level_results field is used to organize the results into tiles. Tiles can be used
to provide an different granularity of spatial resolution, along with AOIs and Divisions. Please
contact the Orbital Insight Client Success team ([email protected]) for information on
this feature.)

The POST will return a response of the form

{
  "data": {
    "results_download_id": "f4d639f8-9057-4466-822f-bd19562eaeff"
  },
  "status": 202
}

You will get an email notification once your results are ready to be downloaded. Alternatively, you may also use the results_download_id field to poll the system, waiting for the download link to
be ready:

GET /projects/$P/versions/$V/results/download?results_download_id=$D

The response will look like this:

{
  "data": {
    "expiry_ts": "2019-08-13 21:15:22+00:00Z",
    "url": "https://orbital-go-download-prod.s3.amazonaws.com/public/export/go/results/test-BbkXnL/test-BbkXnL-1.0.0/..."
  },
  "status": 201
}

The status field will be returned with the value 404 (and with a message of "S3 Object not
found") until the file is ready to be downloaded, after which time the status field be set to
201. At that time, the url field will give the path to the S3 file. The file is only stored
temporarily; you will not be able to access it after the date given by expiry_ts.

You can download the file with curl:

curl -S -s -X GET "...the-aws-s3-url..." > results.zip

Note that the S3 URL may need to be put in double quotes, as it may contain embedded ampersand
(&) characters.

The file you download is a ZIP file containing one or more CSV files. The fields in the CSV file
should be self-explanatory; please contact the Orbital Insight Client Success Team
([email protected]) if you have any questions.

Updated about 3 years ago