GBDX

Suggest Edits

Authentication Reference Overview

 

/auth/v1/oauth/token

Resources

Type URL Description
POST /auth/v1/oauth/token/ GBDX authentication requires a token to access APIs
GET //auth/v1/validate_token/ A "validate token" request verifies that that the token is valid with a 200 OK response. The response body provides basic information about the user account the token is associated with

Token Response

The response to a request for a token includes the following:

Name Value
access_token The string is your token. This is what you use to make API calls.
token_type Bearer
expires_in 604800 seconds, or 7 days
refresh_token A refresh token can replace an expired token*
scope "openid email offline_access"

*Refresh token: Refresh token can be used to replace an expired token. However, for most use cases, it may be easier to simply get a new token by sending another "Get a Token" request.

Validate Token Response

Property Name Value More information
username GBDX user name In most cases, the username is the user's email address. A small set of legacy usernames are not email addresses.
user_id GBDX user ID This is the identification number associated with the user.
account_id GBDX account ID this is the identification number for the GBDX account the user is associated with.
roles List of roles associated with the user At this time, users can only have one role.
id user ID This field has the same value as the "user_id" field for backward compatibility.
role the role associated with the user This field has the same value as the "roles" field. It has been retained for backward compatibility.
is_super_user TRUE/FALSE value This value is set to false unless the user has been granted "super user" permissions by GBDX.
email The email address the user entered when signing up for a GBDX account For most users, the "username" and "email" fields will have the same value.
account_level GBDX account level Examples: Basic, Eval
 
Suggest Edits

Get a Token

API documentation for "Get a Token" request.

 
posthttps://geobigdata.io/auth/v1/oauth/token/

Form Data

grant_type
string
required

The grant_type is "password"

username
string
required

your username is the email address associated with your GBDX account

password
string
required

This is the password associated with your GBDX account

Note: Type "password" in the grant_type input box.

curl --request POST \
  --url https://geobigdata.io/auth/v1/oauth/token/
var request = require("request");

var options = { method: 'POST',
  url: 'https://geobigdata.io/auth/v1/oauth/token/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/auth/v1/oauth/token/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://geobigdata.io/auth/v1/oauth/token/");

xhr.send(data);
import requests

url = "https://geobigdata.io/auth/v1/oauth/token/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "access_token": <access token string>
    "scope": "read write",
    "token_type": "Bearer",
    "expires_in": 604800,
    "refresh_token": <refresh token string>
}
 
Suggest Edits

Validate a Token

Validate your token, and get information about your account.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/auth/v1/validate_token
 
curl --request GET \
  --url https://geobigdata.io/auth/v1/validate_token
var request = require("request");

var options = { method: 'GET',
  url: 'https://geobigdata.io/auth/v1/validate_token' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/auth/v1/validate_token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://geobigdata.io/auth/v1/validate_token");

xhr.send(data);
import requests

url = "https://geobigdata.io/auth/v1/validate_token"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
""username": [this is the email address the user signed up with],
"user_id": [the ID associated with the user],
"account_id": [the ID for the account the user is a member of],
"roles":[
"account_admin"
],
"id": "66e9eafb-a22a-4ced-9950-0a2f9b482230",
"role": "account_admin",
"is_super_user": false,
"email": [user's email address],
"account_level": "custom",
"client_id": [the id of the client application used to generate the token]
}
 
Suggest Edits

Ordering API Reference Overview

 

/orders/v2/order

Type URL Description Try it Out
GET https://geobigdata.io/orders/v2/heartbeat Check heartbeat Orders Heartbeat v2
POST https://geobigdata.io/orders/v2/order Place an Order Place an Order v2
GET https://geobigdata.ioorders/v2/order/<order_id> Get order status Get Order Status v2

Response Attributes and Values

Attribute Description
order_id The ID assigned to the order.
acquisitions The acquisitions that were part of the order.
acquisition_id A separate line item for each acquisition that was part of the order.
state The status of the acquisition that was ordered. See the Order States table below.
Order States Description
submitted The order has been submitted to the GBDX platform
ordering The acquisitions are being ordered from the DigitalGlobe (DG) factory
placed The order has been placed with the DG factory.
delivered The acquisition has been delivered from the DG factory and is available
failed The order failed.

Order Limit

Orders are limited to 100 catalog IDs per order requests.

Duplicates in an Order

If the same catalog ID is requested more than once in the same order request, they will be collapsed into one ID before the order is sent to the factory.

 
Suggest Edits

Orders Heartbeat v2

Check the heartbeat of the Orders API.

 
gethttps://geobigdata.io/orders/v2/heartbeat
 
https://geobigdata.io/orders/v2/heartbeat
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Place an Order v2

Place an Order for one or more catalog IDs to the Orders V2 API

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
posthttps://geobigdata.io/orders/v2/order

Body Params

catID
array of strings

Type a catalog ID you want to order in the box

The example above shows two catalog IDs (acquisitions) that have been delivered to the GBDX catalog. The location shows the S3 bucket location where the acquisitions are stored.

Note: When placing an order using the Postman collection, use the arrays formatted as they are in the example. If you are using the "try it out" feature on this page, input each catalog ID in a separate box.

[
    "104001000506EE00",
    "1010010005231400"
]
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "order_id": "ebffda38-1d6e-4fff-9ae2-aaca94243c45",
  "acquisitions": [
    {
      "acquisition_id": "1010010005231400",
      "state": "delivered",
      "location": "s3://receiving-dgcs-tdgplatform-com/055046034010_01_003"
    },
    {
      "acquisition_id": "104001000506EE00",
      "state": "delivered",
      "location": "s3://receiving-dgcs-tdgplatform-com/055046005010_01_003"
    }
  ]
}
 
Suggest Edits

Get Order Status v2

Get the status of an Order by Order ID. This is version 2 of the Orders API.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/orders/v2/order/order_id

Path Params

order_id
string
required

The ID assigned to the order.

 
https://geobigdata.io/orders/v2/order/9f5b786e-9548-49b9-928d-9b8c683e2678


This is the order ID: ebffda38-1d6e-4fff-9ae2-aaca94243c45
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "order_id": "9f5b786e-9548-49b9-928d-9b8c683e2678",
  "acquisitions": [
    {
      "acquisition_id": "1010010005231400",
      "state": "delivered",
      "location": "s3://receiving-dgcs-tdgplatform-com/055140225010_01_003"
    },
    {
      "acquisition_id": "104001000506EE00",
      "state": "delivered",
      "location": "s3://receiving-dgcs-tdgplatform-com/055140226010_01_003"
    }
  ]
}
 
Suggest Edits

Place Order with Callbacks

To place an order and get a callback notification when the order has completed or failed, use the OrderCB API. If you don't need callbacks, use the Ordering V2 API.

 
posthttps://geobigdata.io/orders/v2/ordercb

Body Params

json

Input catalog IDs with callback url

The "Try it Out" feature is not available for this API request.

Please use the GBDX Postman Collection to try this request.

The JSON request must include the acquisition IDs (catIDs) and the url that will receive the callback message.

Callback messages are sent for the entire order, not for individual acquisition IDs.

Callback messages are sent when the order has either completed or failed.

Callbacks are not sent for acquisitions that have already been delivered.

To check the status of your order, use the order ID to query orders/v2/orders for status. See Get Order Status v2.

{ 
  "acquisitionIds": [ "CATID1", "CATID2" ],
  "callback": "http://domainname.tld/callbackHandler"
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "order_id": "01af5259-64d9-4e16-a161-d6d5e6f3e958",
  "acquisitions": [
    {
      "acquisition_id": "CATID1",
      "state": "submitted"
    },
    {
      "acquisition_id": "CATID2",
      "state": "submitted"
    }
  ],
  "callback": "http://domainname.tld/callbackHandler"
}
 
Suggest Edits

Catalog V2 API Reference

 

/catalog/v2/search

Resources

Type URL Description Try it Out
GET https://geobigdata.io/catalog/v2/heartbeat Check the Catalog V2 API's heartbeat Catalog V2 Heartbeat
GET https://geobigdata.io/catalog/v2/ Search the Catalog by area, date range, types, or filters Get a Token
GET https://geobigdata.io/catalog/v2/record/:recordID Get a record by ID Catalog V2 Get a Record
 
Suggest Edits

Catalog V2 Heartbeat

Check the heartbeat of the Catalog API

 
gethttps://geobigdata.io/catalog/v2/heartbeat
 
https://geobigdata.io/catalog/v2/heartbeat
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Search the Catalog

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
posthttps://geobigdata.io/catalog/v2/search

Body Params

string
required

Search request body

Note: To try this out, paste a search request in the box next to the words "search request body." You can copy and paste the example to the right, or create your own request. To learn more about how to search the GBDX catalog using the Catalog V2 API, see Catalog V2 API Course.

 {
   	"searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
   	"startDate": "2014-01-01T00:00:00.000Z",
   	"endDate": "2014-12-31T23:59:59.999Z",
   	"filters": ["(sensorPlatformName == WORLDVIEW03_VNIR) OR (sensorPlatformName == WORLDVIEW03_SWIR)"],
   	"types": ["1BProduct"],
   	"limit":3
   }
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "stats": {
        "recordsReturned": 3,
        "totalRecords": 3,
        "typeCounts": {
            "GBDXCatalogRecord": 3,
            "DigitalGlobeProduct": 3,
            "1BProduct": 3,
            "WV03_VNIR": 3
        }
    },
    "results": [
        {
            "identifier": "1040010006129900_P001_MUL_056814719010",
            "type": [
                "GBDXCatalogRecord",
                "WV03_VNIR",
                "DigitalGlobeProduct",
                "1BProduct"
            ],
            "properties": {
                "rpbFile": "14DEC28180020-M1BS-056814719010_01_P001.RPB",
                "sunAzimuth": 164.7,
                "cloudCover": 0,
                "catalogID": "1040010006129900",
                "xmlFile": "14DEC28180020-M1BS-056814719010_01_P001.XML",
                "timestamp": "2014-12-28T18:00:20.000Z",
                "attFile": "14DEC28180020-M1BS-056814719010_01_P001.ATT",
                "browseJpgFile": "14DEC28180020-M1BS-056814719010_01_P001-BROWSE.JPG",
                "offNadirAngle": 25.5,
                "platformName": "WORLDVIEW03_VNIR",
                "sunElevation": 25.5,
                "vendor": "DigitalGlobe",
                "soli": "056814719",
                "bands": "Multi",
                "bucketPrefix": "056814719010_01_003/056814719010_01/056814719010_01_P001_MUL",
                "readmeTxtFile": "14DEC28180020-M1BS-056814719010_01_P001_README.TXT",
                "imageFile": "14DEC28180020-M1BS-056814719010_01_P001.TIF",
                "part": 1,
                "bucketName": "receiving-dgcs-tdgplatform-com",
                "resolution": 1.478,
                "footprintWkt": "MULTIPOLYGON(((-104.758169811 39.9311723572, -104.57590596 39.9137643293, -104.575885638 39.796801788, -104.758630276 39.8143432989, -104.758169811 39.9311723572)))",
                "geoFile": "14DEC28180020-M1BS-056814719010_01_P001.GEO",
                "tilFile": "14DEC28180020-M1BS-056814719010_01_P001.TIL",
                "sensorPlatformName": "WORLDVIEW03_VNIR",
                "productLevel": "LV1B",
                "imdFile": "14DEC28180020-M1BS-056814719010_01_P001.IMD",
                "ephFile": "14DEC28180020-M1BS-056814719010_01_P001.EPH",
                "bandsList": "BAND_C,BAND_B,BAND_G,BAND_Y,BAND_R,BAND_RE,BAND_N,BAND_N2"
            }
        },
      [results truncated]
 
Suggest Edits

Get a Record by ID

Search for a record by its identifier.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/catalog/v2/record/RecordID

Path Params

RecordID
string
required

The ID for the record to be retrieved.

To try this API request, use the record ID in the search example in the "Try it Out" box, or use another GBDX catalog ID.

To learn more about records in the GBDX catalog using the Catalog V2 API, see Catalog V2 API Course.

https://geobigdata.io/catalog/v2/record/LC80330322017024LGN00
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "identifier": "LC80330322017024LGN00",
    "type": [
        "GBDXCatalogRecord",
        "Acquisition",
        "Landsat8",
        "LandsatAcquisition"
    ],
    "properties": {
        "vendor": "Landsat",
        "browseURL": "https://s3-us-west-2.amazonaws.com/landsat-pds/L8/033/032/LC80330322017024LGN00/LC80330322017024LGN00_thumb_large.jpg",
        "timestamp": "2017-01-24T17:37:24.048Z",
        "bucketPrefix": "L8/033/032/LC80330322017024LGN00",
        "footprintWkt": "MULTIPOLYGON(((-105.616 39.251, -105.616 41.38968, -102.9163 41.38968, -102.9163 39.251, -105.616 39.251)))",
        "cloudCover": 75,
        "catalogID": "LC80330322017024LGN00",
        "bucketName": "landsat-pds",
        "path": 33,
        "sensorPlatformName": "LANDSAT08",
        "multiResolution": 30,
        "row": 32,
        "platformName": "LANDSAT08",
        "panResolution": 15
    }
}
 
Suggest Edits

Workflow Reference API Overview

 

/workflows/v1/tasks

Type URL Description
GET https://geobigdata.io/workflows/v1/heartbeat Check heartbeat
GET https://geobigdata.io/workflows/v1/tasks List all tasks in the task registry
POST https://geobigdata.io/workflows/v1/tasks Register a task
GET https://geobigdata.io/workflows/v1/tasks/task_id Get a task definition from the task registry
DELETE https://geobigdata.io/workflows/v1/tasks/task_id:task version Delete a Task

/workflows/v1/workflows

Type URL Description
GET https://geobigdata.io/workflows/v1/workflows Get a list of workflows
POST https://https://geobigdata.io/workflows/v1/workflows Submit a workflow
GET https://geobigdata.io/workflows/workflow_id Get a workflow and its Status
GET https://geobigdata.io/workflows/workflow_id/events Get a workflow's status events
POST https://geobigdata.io//workflows/v1/workflows/:workflow_id/cancel Cancel a Workflow Cancel a Workflow
GET https://geobigdata.io/workflows/v1/workflows/workflow_id/tasks/task_id/stdout Get the stdout output from a completed task in a workflow
GET https://geobigdata.io/workflows/v1/workflows/workflow_id/tasks/task_id/stderr Get the stderr output from a completed task in a workflow

/workflows/v1/workflows/search

Type URL Description
GET https://geobigdata.io//workflows/v1/workflows/search List workflow filters
POST https://geobigdata.io//workflows/v1/workflows/search Search workflows by filter

Workflow Filter Properties

Property Value Type Description
owner 1 to 50 string Owner to filter by. This filter is only available for super-users. For regular users, the results are filtered by username
state see list below enum workflow state
lookback_h 0 to 720 number Look back time in hours

Workflow States

* submitted
* scheduled
* started
* canceled
* cancelling
* failed
* succeeded
* timedout
* pending
* running
* complete
* all

/workflows/v1/schemas

Type URL Description
GET https://geobigdata.io/workflows/v1/schemas/TaskDescriptor Get the Task Definition Schema
GET https://geobigdata.io/workflows/v1/schemas/WorkflowDescriptor Get the Workflow Definition Schema

Note: Please see the Task and Workflow Course for complete descriptions of the task and workflow definitions.

 
Suggest Edits

Workflows Heartbeat

Check the heartbeat of the Workflow API

 
gethttps://geobigdata.io/workflows/v1/heartbeat
 
https://geobigdata.io/workflows/v1/heartbeat
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Get Task Definition

Get a Task Definition from the Task Registry

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/tasks/name

Path Params

name
string
required

String Identifier of the task. For example, Getting_Started

Get a Task by Name and Version Number

Retrieving a task by name returns the latest registered version of that task. To get a specific version of a task, include the version number in the request.

The request will look like this:

https://geobigdata.io/workflows/v1/tasks/name:version

  • Note: The task name case must match the task registry or the request will return a 404 error.*
https://geobigdata.io/workflows/v1/tasks/Getting_Started:0.0.1
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "containerDescriptors": [
    {
      "command": "",
      "type": "DOCKER",
      "properties": {
        "image": "tdgp/hello_gbdx:latest"
      }
    }
  ],
  "description": "Get a personalized greeting to GBDX",
  "inputPortDescriptors": [
    {
      "required": true,
      "type": "string",
      "description": "Enter your name here for a personalized greeting to the platform.",
      "name": "your_name"
    }
  ],
  "version": "0.0.1",
  "outputPortDescriptors": [
    {
      "required": true,
      "type": "txt",
      "description": "The output directory of text file",
      "name": "data"
    }
  ],
  "properties": {
    "isPublic": true,
    "canPersist": true,
    "timeout": 7200
  },
  "name": "Getting_Started"
}
 200 OK
 
Suggest Edits

List All Tasks

List all tasks in the GBDX task registry.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/tasks
 
curl --request GET \
  --url https://geobigdata.io/workflows/v1/tasks
var request = require("request");

var options = { method: 'GET',
  url: 'https://geobigdata.io/workflows/v1/tasks' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/workflows/v1/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://geobigdata.io/workflows/v1/tasks");

xhr.send(data);
import requests

url = "https://geobigdata.io/workflows/v1/tasks"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
                "tasks":[
                    "FastOrtho",
                    "AComp",
                    "StageDataToS3"
                ]
            }
{
  "status": "404 Not Found",
  "message": "Not Found"
}
{
  "status": "401 Unauthorized", 
  "message": "Authentication Failed."
}
 
Suggest Edits

Register a task

Register a new task or an updated version of an existing task.

 
posthttps://geobigdata.io/workflows/v1/tasks

The "Try it Out" feature is not available for this request.

Please use the GBDX Postman Collection to try this request.

See How to Version a Task for more information on how to register a new version of a task.

{
    "inputPortDescriptors": [
        {
            "required": true,
            "description": "A string input.",
            "name": "inputstring",
            "type": "string"
        },
        {
            "name": "dependency_input",
            "type": "string"
        }
    ],
    "outputPortDescriptors":[
        {
            "name": "dependency_output",
            "type": "string"
        }
    ],
    "containerDescriptors": [
        {
            "type": "DOCKER",
            "command": "",
            "properties": {
                "image": "tdgp/test-success",
                "mounts": [
                    {
                        "local": "$task_data_dir",
                        "container": "/mnt/work",
                        "read_only": false
                    }
                ]
            }
        }
    ],
    "description": "Runs a no-op task that writes successful output status.",
    "name": "test-success",
    "version": "0.0.1",
    "taskOwnerEmail": "TEST@TEST.com",
    "properties": {
      "isPublic": false,
      "timeout": 7200,
      "authorizationRequired": true
    }
  }
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
 test-success successfully registered.
 
Suggest Edits

Delete a Task

Delete a task from the task registry. Deleting a task requires a version number. Only one version of a task can be deleted at a time.

 
deletehttps://geobigdata.io/workflows/v1/tasks/<task_id>:<version>

The "Try it Out" feature is not available for this API request.

Please use the GBDX Postman Collection to try this request.

  • Deleting a task requires the version number. Only one version of a task can be deleted at a time.

  • Deleting a task removes the task from the task registry, but does not remove the docker image from the AWS ECS.

  • Only the tasks's owner can delete a task.The owner is the account, so any user within the account can delete the task.

  • A task cannot be deleted while docker migration for that task is in progress.

  • If a task version version is deleted, any workflow that uses the version of the task that's deleted, will error out. If the workflow only referred to the task name with no version number, the workflow will run the latest version of the task registered in the task registry.

  • Attempting to delete a task that doesn't exist in the task registry will result in this error message:
         {
     "status": "400 Bad Request",
     "message": "Invalid task id"
    }

https://geobigdata.io/workflows/v1/tasks/doctask:0.0.1
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
 [TaskName] successfully deleted
{
    "status": "400 Bad Request",
    "message": "Invalid task id"
}
{
  "status": "401 Unauthorized", 
  "message": "Authentication Failed."
}
 
Suggest Edits

List Workflows

List workflows in the GBDX workflow system

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/workflows
 
curl --request GET \
  --url https://geobigdata.io/workflows/v1/workflows
var request = require("request");

var options = { method: 'GET',
  url: 'https://geobigdata.io/workflows/v1/workflows' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/workflows/v1/workflows")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://geobigdata.io/workflows/v1/workflows");

xhr.send(data);
import requests

url = "https://geobigdata.io/workflows/v1/workflows"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "Workflows": [
    "4533914856650109382",
    "4533914873730972221",
    "4533914900438238041",
    "4533914983140964076",
    
     ]
}
{
  "status": "404 Not Found",
  "message": "Not Found"
}
{
  "status": "401 Unauthorized", 
  "message": "Authentication Failed."
}
 
Suggest Edits

Submit a Workflow

Submit a workflow to the GBDX workflow system

 
posthttps://geobigdata.io/workflows/v1/workflows

The "Try it Out" feature is not available for this request.

Please use the GBDX Postman Collection to try this request.

Please see the Task and Workflow Course for a complete explanation of the workflow definition.

 {
 	"name": "Getting_Started_Workflow",
 	"tasks": [{
 		"name": "show_getting_started",
 		"taskType": "Getting_Started",
 		"inputs": [{
 			"name": "your_name",
 			"value": "GBDX U"
 		}],
 		"outputs": [{
 			"name": "data",
 			"persist": true,
 			"persistLocation": "getting_started"
 		}]
 	}]
 }

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "tasks": [
        {
            "inputs": [
                {
                    "source": null,
                    "dataflow_channel": null,
                    "type": "string",
                    "name": "your_name",
                    "value": "GBDX U"
                }
            ],
            "outputs": [
                {
                    "persistLocation": "732835da-2059-42de-ad90-03e6e5198fc6/getting_started",
                    "dataflow_channel": null,
                    "name": "data",
                    "value": null,
                    "source": null,
                    "type": "txt"
                }
            ],
            "start_time": null,
            "taskType": "Getting_Started:0.0.1",
            "id": "4919508329669638987",
            "name": "show_getting_started",
            "note": null,
            "callback": null,
            "state": {
                "state": "pending",
                "event": "submitted"
            },
            "run_parameters": {
                "mounts": [
                    {
                        "read_only": false,
                        "local": "$task_data_dir",
                        "container": "/mnt/work"
                    }
                ],
                "image": "Getting_Started",
                "tag": "0.0.1",
                "command": "",
                "devices": []
            },
            "timeout": 7200,
            "instance_info": {
                "domain": "default"
            }
        }
    ],
    "completed_time": null,
    "callback": null,
    "state": {
        "state": "pending",
        "event": "submitted"
    },
    "submitted_time": "2018-08-01T20:04:52.919853+00:00",
    "owner": "sherri.barksdale@digitalglobe.com",
    "id": "4919508329672498334"
}

{
  "status": "404 Not Found",
  "message": "Not Found"
}
{
  "status": "401 Unauthorized", 
  "message": "Authentication Failed."
}
 
Suggest Edits

Get Workflow Status

Get a Workflow by Workflow ID, see status.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/workflows/workflow_id

Path Params

workflow_id
string
required

Workflow identifier

 
https://geobigdata.io/workflows/v1/workflows/4249073422254282656
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "tasks": [
        {
            "inputs": [
                {
                    "source": null,
                    "dataflow_channel": null,
                    "type": "string",
                    "name": "your_name",
                    "value": "GBDX U"
                }
            ],
            "outputs": [
                {
                    "persistLocation": "732835da-2059-42de-ad90-03e6e5198fc6/getting_started",
                    "dataflow_channel": null,
                    "name": "data",
                    "value": null,
                    "source": null,
                    "type": "txt"
                }
            ],
            "start_time": "2018-08-09T17:01:34.104851+00:00",
            "taskType": "Getting_Started:0.0.1",
            "id": "4925214126814967046",
            "name": "show_getting_started",
            "note": "===== Task successfully completed ======",
            "callback": null,
            "state": {
                "state": "complete",
                "event": "succeeded"
            },
            "run_parameters": {
                "mounts": [
                    {
                        "read_only": false,
                        "container": "/mnt/work",
                        "local": "/tmp/workflows/4925214126814967046"
                    }
                ],
                "image": "Getting_Started",
                "tag": "0.0.1",
                "command": "",
                "devices": []
            },
            "timeout": 7200,
            "instance_info": {
                "instance_id": "i-0ef95eef23f2321d9",
                "domain": "default"
            }
        }
    ],
    "completed_time": "2018-08-09T17:02:03.089181+00:00",
    "callback": null,
    "state": {
        "state": "complete",
        "event": "succeeded"
    },
    "submitted_time": "2018-08-09T17:01:16.943938+00:00",
    "owner": [owner email address],
    "id": "4925214126822474693"
}
{
    "status": "404 Not Found",
    "message": "Not Found"
}
 
Suggest Edits

Workflow status events

Get a Workflow's status events by Workflow Identifier.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/workflows/workflow_id/events

Path Params

workflow_id
string
required

Workflow identifier

 
https://geobigdata.io/workflows/v1/workflows/4249073422254282656/events
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "Events": [
    {
      "task": "show_getting_started",
      "task_id": "4920177479723553006",
      "timestamp": "2018-08-02T18:14:21.837313+00:00",
      "when": "6 minutes ago",
      "note": "",
      "state": "pending",
      "event": "submitted"
    },
    {
      "task": "show_getting_started",
      "task_id": "4920177479723553006",
      "timestamp": "2018-08-02T18:14:23.687640+00:00",
      "when": "6 minutes ago",
      "note": "instance_id: i-0979d4e16c4de2636",
      "state": "pending",
      "event": "scheduled"
    },
    {
      "task": "show_getting_started",
      "task_id": "4920177479723553006",
      "timestamp": "2018-08-02T18:14:23.829248+00:00",
      "when": "6 minutes ago",
      "note": "instance_id: i-003fd65cc93447078, domain: default",
      "state": "running",
      "event": "started"
    },
    {
      "task": "show_getting_started",
      "task_id": "4920177479723553006",
      "timestamp": "2018-08-02T18:14:49.095359+00:00",
      "when": "6 minutes ago",
      "note": "instance_id: i-003fd65cc93447078,  Note: ===== Task successfully completed ======",
      "state": "complete",
      "event": "succeeded"
    }
  ]
}
   
{
    "status": "404 Not Found",
    "message": "Not Found"
}
 
Suggest Edits

Cancel a Workflow

Cancel a workflow that's running, GBDX workflow system

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
posthttps://geobigdata.io/workflows/v1/workflows/workflow_id/cancel

Path Params

workflow_id
string
required

Workflow identifier

 
https://geobigdata.io/workflows/v1/workflows/4249073422254282656/cancel
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
 canceling workflow {workflow_id}
 
Suggest Edits

List workflow filters

List available filters for the workflow system

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/workflows/search
 
curl --request GET \
  --url https://geobigdata.io/workflows/v1/workflows/search
var request = require("request");

var options = { method: 'GET',
  url: 'https://geobigdata.io/workflows/v1/workflows/search' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/workflows/v1/workflows/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://geobigdata.io/workflows/v1/workflows/search");

xhr.send(data);
import requests

url = "https://geobigdata.io/workflows/v1/workflows/search"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "properties": {
    "owner": {
      "minLength": 1,
      "type": "string",
      "description": "Owner to filter by. This filter is only available for super-users. For regular user the results are filtered by username.",
      "maxLength": 50
    },
    "state": {
      "enum": [
        "submitted",
        "scheduled",
        "started",
        "canceled",
        "cancelling",
        "failed",
        "succeeded",
        "timedout",
        "pending",
        "running",
        "complete",
        "all"
      ],
      "description": "State to filter by."
    },
    "lookback_h": {
      "minimum": 0,
      "type": "number",
      "maximum": 720,
      "description": "Look back time in hours."
    }
  },
  "minProperties": 1,
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "id": "urn:jsonschema:com:digitalglobe:workflows:WorkflowsSearch"
}
 
Suggest Edits

Task Definition Schema

Get the Task Definition schema from the Workflow Endpoint.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/schemas/TaskDescriptor

Please see the Task and Workflow Course for a complete explanation of the task definition.

https://geobigdata.io/workflows/v1/schemas/Task Descriptor
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "definitions": {
    "TaskExtraProperties": {
      "required": [
        "timeout"
      ],
      "type": [
        "object",
        "null"
      ],
      "description": "Additional properties of the task.",
      "properties": {
        "authorizationRequired": {
          "type": "boolean",
          "description": "Indicator that the task logic will require GBDX authorization from the running user. If this is true and during workflow invocation 'impersonation_allowed' flag is not set on the task workflow will fail. Defaults to false."
        },
        "isPublic": {
          "type": "boolean",
          "description": "Visibility of the task to other users. Defaults to false."
        },
        "timeout": {
          "minimum": 0,
          "type": "integer",
          "description": "The integer of the default timeout to this task (in seconds). Max: 172,800 (48 hours).",
          "maximum": 172800
        }
      }
    },
    "TaskSequenceDescriptor": {
      "allOf": [
        {
          "$ref": "workflow_schema.json#/definitions/Workflow"
        },
        {
          "required": [
            "outputMapping"
          ],
          "properties": {
            "outputMapping": {
              "minItems": 0,
              "items": {
                "$ref": "#/definitions/OutputMapping"
              },
              "type": "array"
            }
          }
        }
      ]
    },
    "PortDescriptor": {
      "required": [
        "name",
        "type"
      ],
      "type": "object",
      "properties": {
        "multiplex": {
          "type": "boolean",
          "description": "Are multiple ports port name as prefix allowed."
        },
        "required": {
          "type": "boolean",
          "description": "Is the port required.  If not required, the system will select a reasonable default value."
        },
        "type": {
          "type": "string",
          "description": "The port type."
        },
        "description": {
          "type": "string",
          "description": "A description of the port."
        },
        "name": {
          "type": "string",
          "description": "The port name."
        }
      }
    },
    "ContainerDescriptor": {
      "required": [
        "type",
        "properties"
      ],
      "type": "object",
      "properties": {
        "type": {
          "enum": [
            "DOCKER",
            "GPUDOCKER",
            "AMI",
            "TASK_DRIVER"
          ],
          "type": "string",
          "description": "The container type."
        },
        "command": {
          "type": "string",
          "description": "The command used to launch the container."
        },
        "properties": {
          "required": [
            "image"
          ],
          "type": "object",
          "description": "Container descriptor properties",
          "properties": {
            "image": {
              "type": "string",
              "description": "An image name that uniquely identifies the container within the GBD system."
            },
            "domain": {
              "type": "string",
              "description": "Identifies the worker domain/group/collective under which to run."
            }
          }
        }
      }
    },
    "OutputMapping": {
      "required": [
        "source",
        "name"
      ],
      "type": "object",
      "properties": {
        "source": {
          "minLength": 1,
          "type": "string"
        },
        "name": {
          "minLength": 1,
          "type": "string"
        }
      }
    },
    "TaskDefinition": {
      "allOf": [
        {
          "required": [
            "name",
            "version",
            "inputPortDescriptors"
          ],
          "properties": {
            "name": {
              "pattern": "^[a-zA-Z0-9]{1}[a-zA-Z0-9_.-]+[a-zA-Z0-9]{1}$",
              "type": "string",
              "description": "A name that uniquely identifies the task descriptor.",
              "maxLength": 128
            },
            "inputPortDescriptors": {
              "minItems": 1,
              "items": {
                "$ref": "#/definitions/PortDescriptor"
              },
              "type": "array",
              "description": "The input ports for the task."
            },
            "version": {
              "pattern": "^0\\.0\\.([1-9][0-9]{0,4})$|^0\\.([1-9][0-9]{0,4})\\.(0|[1-9][0-9]{0,4})$|^([1-9][0-9]{0,4})\\.(0|[1-9][0-9]{0,4})\\.(0|[[1-9][0-9]{0,4})$",
              "type": "string",
              "description": "Version (Major, Minor, Patch) identifier"
            },
            "outputPortDescriptors": {
              "minItems": 0,
              "items": {
                "$ref": "#/definitions/PortDescriptor"
              },
              "type": "array",
              "description": "The ports that are output by the task."
            },
            "properties": {
              "$ref": "#/definitions/TaskExtraProperties"
            },
            "description": {
              "type": "string",
              "description": "A human-readable description of the function performed by this task."
            }
          }
        },
        {
          "oneOf": [
            {
              "required": [
                "containerDescriptors"
              ],
              "properties": {
                "containerDescriptors": {
                  "minItems": 1,
                  "items": {
                    "$ref": "#/definitions/ContainerDescriptor"
                  },
                  "type": "array",
                  "description": "The containers that are capable of running the task.",
                  "maxItems": 1
                }
              }
            },
            {
              "required": [
                "taskSequenceDescriptor"
              ],
              "properties": {
                "taskSequenceDescriptor": {
                  "$ref": "#/definitions/TaskSequenceDescriptor"
                }
              }
            }
          ]
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "$ref": "#/definitions/TaskDefinition"
}
 
Suggest Edits

Workflow Definition Schema

Get the Workflow schema from the Workflow Endpoint.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/schemas/WorkflowDescriptor

The workflow system uses JSON schemas to validate user inputs. Submitted task definitions and submitted workflows must comply with the schemas.

Please see the Task and Workflow Course for a complete explanation of the workflow definition.

curl --request GET \
  --url https://geobigdata.io/workflows/v1/schemas/WorkflowDescriptor
var request = require("request");

var options = { method: 'GET',
  url: 'https://geobigdata.io/workflows/v1/schemas/WorkflowDescriptor' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/workflows/v1/schemas/WorkflowDescriptor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://geobigdata.io/workflows/v1/schemas/WorkflowDescriptor");

xhr.send(data);
import requests

url = "https://geobigdata.io/workflows/v1/schemas/WorkflowDescriptor"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "definitions": {
    "OutPort": {
      "$ref": "#/definitions/Port"
    },
    "Task": {
      "required": [
        "name",
        "taskType",
        "inputs"
      ],
      "type": "object",
      "properties": {
        "inputs": {
          "minItems": 1,
          "uniqueItems": true,
          "type": "array",
          "items": {
            "$ref": "#/definitions/InputPort"
          }
        },
        "name": {
          "minLength": 1,
          "type": "string"
        },
        "outputs": {
          "uniqueItems": true,
          "items": {
            "$ref": "#/definitions/OutPort"
          },
          "type": "array"
        },
        "timeout": {
          "minimum": 0,
          "type": "integer",
          "description": "User-defined timeout value (in seconds).",
          "maximum": 36000
        },
        "taskType": {
          "minLength": 1,
          "type": "string"
        },
        "impersonation_allowed": {
          "type": "boolean",
          "description": "Allow the task to use user security token."
        }
      }
    },
    "InputPort": {
      "type": "object",
      "allOf": [
        {
          "$ref": "#/definitions/Port"
        },
        {
          "oneOf": [
            {
              "required": [
                "value"
              ],
              "properties": {
                "value": {
                  "minLength": 1,
                  "type": "string"
                }
              }
            },
            {
              "required": [
                "source"
              ],
              "properties": {
                "source": {
                  "minLength": 1,
                  "type": "string"
                }
              }
            }
          ]
        }
      ]
    },
    "Port": {
      "required": [
        "name"
      ],
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "name": {
          "minLength": 1,
          "type": "string"
        }
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "required": [
    "name",
    "tasks"
  ],
  "type": "object",
  "properties": {
    "tasks": {
      "minItems": 1,
      "uniqueItems": true,
      "type": "array",
      "additionalProperties": false,
      "items": {
        "$ref": "#/definitions/Task"
      }
    },
    "name": {
      "minLength": 1,
      "type": "string"
    }
  }
}
 
Suggest Edits

STDOUT output from a workflow task

Retrieve STDOUT output from a completed task in a workflow

 
gethttps://geobigdata.io/workflows/v1/workflows/workflow_id/tasks/task_id/stdout

Path Params

workflow_id
string
required

numeric value, workflow_id

task_id
string
required

numeric value, task_id

parameter
description

workflow_id

The numeric id given to a workflow once it's been run. Find it at the bottom of a "submit a workflow" or workflow status and workflow events response.

task_id

The number id given to a task that's part of a workflow. Look for id in task description in the "submit a workflow" or workflow status and workflow events response.

This is a sample response from a "Get Workflow status" request. The task_id and workflow_id are shown in red.

STDOUT Responses

Response: 200 OK
Response body contains the STDOUT from the Docker container that ran the task.
When there is no data, the request will return "empty.

This is another example of an STDOUT output:

GET: https://geobigdata.io/workflows/v1/workflows/4238412131064055622/tasks/4238412131057043184/stdout

Response:

inputImageDir = /mnt/work/input/input_image/054619420020_01
fileTif = /mnt/work/input/input_image/054619420020_01/054619420020_01_assembly.tif
############ FILES #############
################################
parameters:
{'village_boundary_scale': u'30', 'population_resolution': u'50', 'daouzek_area_bounds': u'60 1000', u'parameter_set': u'desert', 'population_compute': u'false', 'daouzek_results_type': u'confidence', 'daouzek_threshold': u'700', 'daouzek_imp_threshold': u'40 255', 'daouzek_fuse_type': u'rgbmax', 'village_use_bue': u'true', 'run_cloud_mask': u'true', 'daouzek_centroids': u'true'}
Writing parameters to: /mnt/work/output/log/params.sh
Input file size is 8480, 7283
0...10...20...30...40...50...60...70...80...90...100 - done.
MAXF finsished reading
0...10...20...30...40...50...60...70...80...90...100 - done.
Creating output /mnt/work/output/imagery/054619420020_01_assembly_bue.json of format GeoJSON.
0...10...20...30...40...50...60...70...80...90...100 - done.
/mnt/work/output/imagery/annot_tmp.json
/mnt/work/output/imagery/054619420020_01_assembly_bue_annot.json
[(0, (inf, 10000.0)), (1, (10000.0, 5000.0)), (2, (5000.0, 2500.0)), (3, (2500.0, 1000.0)), (4, (1000.0, 0.0))]

The "Try it Out" feature is not available for this request.

Please use the GBDX Postman Collection to try this request.

https://geobigdata.io/workflows/v1/workflows/4319343759119412532/tasks/4319343759114673547/stdout
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
<empty>
 
Suggest Edits

STDERR output from a workflow task

Retrieve STDERR output from a completed task in a workflow

 
gethttps://geobigdata.io/workflows/v1/workflows/workflow_id/tasks/task_id/stderr

Path Params

workflow_id
string
required

numeric value, workflow_id

task_id
string
required

numeric value, task_id

parameter
description

workflow_id

The numeric id given to a workflow once it's been run. Find it at the bottom of a "submit a workflow" or workflow status and workflow events response.

task_id

The number id given to a task that's part of a workflow. Look for id in task description in the "submit a workflow" or workflow status and workflow events response.

This is a sample response from a "Get Workflow status" request. The task_id and workflow_id are shown in red.

STDERR Responses

Response: 200 OK
Response body contains the STDERR from the Docker container that ran the task.
When there is no data, the request will return "empty."

This is another example of an STDERR response:

GET:
https://geobigdata.io/workflows/v1/workflows/4238412131064055622/tasks/4238412131057043184/stderr

Response:

cp: cannot stat `/mnt/work/status.json': No such file or directory
mkdir: cannot create directory `/mnt/work/output/imagery/': File exists

The "Try it Out" feature is not available for this request.

Please use the GBDX Postman Collection to try this request.

https://geobigdata.io/workflows/v1/workflows/4319343759119412532/tasks/4319343759114673547/stderr
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
<empty>
 
Suggest Edits

Submit a batch workflow

Submit a batch workflow that spawns multiple workflows.

 
posthttps://geobigdata.io/workflows/v1/batch_workflows

Batch Workflow request elements

element
type
description

name

string

user provided workflow name

batch values

input name and batch values for the input

name

string

name of the input port.

values

string

input values for the named input port

tasks

a list of tasks and their input and output values that will run in this workflow

name

string

name of the task. This can be a user provided name. Does not have to match name in task definition

outputs

the output from the task. Commonly named "data"

name

string

user provided name of the output

inputs

list of inputs for the task

name

string

user provided name of the output

value

string

$ indicates a batch value. The name used here needs to match the name used in the workflow batch values list

Example:
"name": "input_data",
$batch_value:input_data"

taskType

string

This is the name of the task as it is registered in the task registry.

The "Try it Out" feature is not available for this request.

Please use the GBDX Postman Collection to try this request.

{
       "name": "batch_test",
       "batch_values": [
           {
               "name": "input_data",
               "values": [
                   "CAT1",
                   "CAT2",
                   "CAT3"
               ]
           },
           {
               "name": "input_dem",
               "values": [
                   "SRTM90",
                   "SRTM120",
                   "SRTM150"
               ]
           },
           {
               "name": "destination",
               "values": [
                   "result/1",
                   "result/2",
                   "result/3"
               ]
           }
       ],
       "tasks": [
           {
               "name": "task_1",
               "outputs": [
                   {
                       "name": "data",
                       "persist": true,
                       "persistLocation": "{{destination}}""
                   }
               ],
               "inputs": [
                   {
                       "name": "data",
                       "value": "{{input_data}}"
                   },
                   {
                       "name": "demspecifier",
                       "value": "{{input_dem}}"
                   }
               ],
               "taskType": "test_task"
           }
       ]
    }
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "owner": "username",
  "batch_workflow_id": "4346139242736357640",
  "workflow_name": "fastortho_stagetos3",
  "submitted_time": "2016-06-01T17:42:51.415894+00:00",
  "workflows": [
    {
      "workflow_id": "4346139242751065655",
      "state": "submitted"
    },
    {
      "workflow_id": "4346139242764152386",
      "state": "submitted"
    },
    {
      "workflow_id": "4346139242780426784",
      "state": "submitted"
    }
  ]
}
 
Suggest Edits

Get a batch workflow

Get a batch workflow by ID.

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/workflows/v1/batch_workflows/<batch_workflow_id>

The "Get a batch workflow" request lets you see the state of each workflow in the batch.

A batch workflow does not have events or states. Each workflow in the batch has its own state. Submitting a batch workflow kicks off all workflows in the batch in parallel.

curl --request GET \
  --url https://geobigdata.io/workflows/v1/batch_workflows/%3Cbatch_workflow_id%3E
var request = require("request");

var options = { method: 'GET',
  url: 'https://geobigdata.io/workflows/v1/batch_workflows/%3Cbatch_workflow_id%3E' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/workflows/v1/batch_workflows/%3Cbatch_workflow_id%3E")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://geobigdata.io/workflows/v1/batch_workflows/%3Cbatch_workflow_id%3E");

xhr.send(data);
import requests

url = "https://geobigdata.io/workflows/v1/batch_workflows/%3Cbatch_workflow_id%3E"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "owner": "myUserName",
    "batch_workflow_id": "4320822787474689603",
    "workflow_name": "AOP_Strip_Processor_stagetos3",
    "submitted_time": "2016-04-27T19:23:34.770011+00:00",
    "workflows": [
        {
            "workflow_id": "4320822787507746157",
            "state": "submitted"
        },
        {
            "workflow_id": "4320822787515379476",
            "state": "submitted"
        },
        {
            "workflow_id": "4320822787522659702",
            "state": "submitted"
        }
    ]
}
 
Suggest Edits

Cancel a batch workflow

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
posthttps://geobigdata.io/workflows/v1/batch_workflows/<batch_workflow_id>/cancel

Canceling a batch workflow cancels all workflows in the batch. Each workflow has its own worklfow ID and its own state. To cancel a single workflow from the batch,select the workflow ID you want to cancel and use Cancel a Workflow.

Once a workflow has completed, it cannot be canceled.

https://geobigdata.io/workflows/v1/batch_workflows/<4320822787474689603>/cancel
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "owner": "myUserName",
    "batch_workflow_id": "4320822787474689603",
    "workflow_name": "fastortho_stagetos3",
    "submitted_time": "2016-04-27T19:23:34.770011+00:00",
    "workflows": [
        {
            "workflow_id": "4320822787507746157",
            "state": "canceled"
        },
        {
            "workflow_id": "4320822787515379476",
            "state": "canceled"
        },
        {
            "workflow_id": "4320822787522659702",
            "state": "canceled"
        }
    ]
}
 
Suggest Edits

Storage Service Guide Reference

 

/s3creds/v1/prefix

Type URL Description
GET https://geobigdata.io/s3creds/v1/prefix?duration=3600 Get temporary credentials to a GBDX S3 location
PUT https://geobigdata.io/s3creds/v1/prefix Update a Prefix
GET https://geobigdata.io/s3creds/v1/prefix Get prefix size

Note: If the prefix does not exist it will be created implicitly.

The credentials provided by the GBDX S3 Storage Service are temporary and session-based. When a request is made for credentials, the system will return:

  • Bucket (The S3 Bucket is gbd-customer-data)
  • Prefix (The Prefix is your account ID)
  • S3_access_key
  • S3_session_token
Duration Type Value
Minimum 900 seconds (.25 hours)
Default 3600 seconds (1 hour)
Maximum 129600 seconds (36 hours)
 
Suggest Edits

Get Temp S3 Creds for Prefix

Get temporary S3 credentials from the GBDX S3 Storage Service

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/s3creds/v1/prefix

Note: If the prefix does not exist, it will be created implicitly.

The credentials provided by the GBDX S3 Storage Service are temporary and session-based. When a request is made for credentials, the system will return:

  • Bucket (The S3 Bucket is gbd-customer-data)
  • Prefix (The Prefix is your account ID)
  • S3_access_key
  • S3_session_token
Duration Type Value
Minimum 900 seconds (.25 hours)
Default 3600 seconds (1 hour)
Maximum 129600 seconds (36 hours)

To try this request, input a value in seconds in the duration

	This is an example credentials request that sets the duration in seconds. 

https://geobigdata.io/s3creds/v1/prefix?duration=129600
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "S3_secret_key": "JjnAy0NdO2WO5N7JgGRTuCoy3zqQdnSA4KLD9ogb",
  "prefix": "782839ja-2059-42de-ad70-03e6e5192fc6",
  "bucket": "gbd-customer-data",
  "S3_access_key": "ASIAIE3GWTJ7LLJLMCYB",
  "S3_session_token": "AQoDYXdzEBoa4ANP+zSjA4Pi6KLXiqw91T6oYhaJCMFmdtLcVcQcrGd1aIcy/3J8ZLfDmIkzsDWJhL8TvPvASaqxt/xYj8+SmlGNgnGH1jpSNwsDzCqTItlm6N5y8BZjCgSj3EKoyWW7XbTAAn+evMfMQEPlZM6onEdsYsm0CVx0DY8JnvTJBhA7I06/3g8XmSqOTxOfpqsYK5jt1JxseG956UOAWD35k34/r2BSQ+GKPpQ/drlcfPlQR/lDBopi8VejFh0Wq0GRUHg+yEJvZ1Ytrtm8R1MdMasXb3jVtMxm4SNH5/dVEP61yq9cA5B9UIl2LoFJYGx+fSnwRVaC0/1NjJzRNJmsR48Kyfaop1FNsKuCXWnGg1LWktnJRZft3vs+eaXQ2rvscex9cwxxg0Er9I9B1F0qD9ucHyrpxgRetMMymp3omIHMB3wcI+QCx39MKkBDCdpXNE3fCd0TaCbXX48XbJVaACCp60aNfvtkt7nRkyDsTx/gQ6GUpPiONxX8BKYLbsg6yvcXCyy6umAZBcOq+dYWxm5MSvIjJHFHbgS1+6xaJTkyAmtXRcJHzWwaUTmDe9Fh/qXA8aVu9NW2hf/aok61HqZqothqIEQeox7wI+21spXAh+uT+kT2YIDsnxRxR1GpMXkgzPLFtwU="
}
 
Suggest Edits

Get Prefix Size

Use the GBDX S3 Storage Service to get the size of a prefix

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/s3creds/v1/prefix/<Prefix>

Query Params

Prefix
string
required

the prefix to retrieve the size for

Permissions Required: account_user

Note: The prefix must exist in the database, raises 404.

curl --request GET \
  --url 'https://geobigdata.io/s3creds/v1/prefix/%3CPrefix%3E?Prefix=Prefix'
var request = require("request");

var options = { method: 'GET',
  url: 'https://geobigdata.io/s3creds/v1/prefix/%3CPrefix%3E',
  qs: { Prefix: 'Prefix' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/s3creds/v1/prefix/%3CPrefix%3E?Prefix=Prefix")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://geobigdata.io/s3creds/v1/prefix/%3CPrefix%3E?Prefix=Prefix");

xhr.send(data);
import requests

url = "https://geobigdata.io/s3creds/v1/prefix/%3CPrefix%3E"

querystring = {"Prefix":"Prefix"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
 {
          "message": "Total prefix size is 36bytes.",
          "total_bytes": 36,
          "success": true
        }
 
Suggest Edits

Get temp creds-Folder

Get temporary S3 credentials for a folder

 
get/s3creds/v1/folder/?folder_path?duration

Query Params

folder_path
string
required

the folder path listed as "prefix"

duration
string

time in seconds that the credentials will be valid. Valid range is 900s to 129600s.

Permissions Required: account_user

Note: If user's account doesn't have a prefix one will be implicitly created. The folder must exist under user's prefix, raises 400.

curl --request GET \
  --url 'http://example.com/s3creds/v1/folder/%7B?folder_path=folder_path&folder_path%7D%7B%3Fduration%7D='
var request = require("request");

var options = { method: 'GET',
  url: 'http://example.com/s3creds/v1/folder/%7B',
  qs: 
   { folder_path: 'folder_path',
     'folder_path}{?duration}': '' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("http://example.com/s3creds/v1/folder/%7B?folder_path=folder_path&folder_path%7D%7B%3Fduration%7D=")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://example.com/s3creds/v1/folder/%7B?folder_path=folder_path&folder_path%7D%7B%3Fduration%7D=");

xhr.send(data);
import requests

url = "http://example.com/s3creds/v1/folder/%7B"

querystring = {"folder_path":"folder_path","folder_path}{?duration}":""}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
          "S3_secret_key": "{temp_s3_secret_key}",
          "prefix": "{folder_path}",
          "bucket": "gbd-customer-data",
          "S3_access_key": "{temp_s3_access_key}",
          "S3_session_token": "{temp_s3_session_token}"
        }
 
Suggest Edits

Get temp creds-Object

Get temporary S3 credentials for an object

 
get/s3creds/v1/object/?object_path?duration

Query Params

object_path
string
required

object path under prefix

duration
string

time in seconds that the credentials will be valid. Valid range is 900s to 129600s.

Permissions Required: account_user

Note: If user's account doesn't have a prefix one will be implicitly created. The object must exist under user's prefix, raises 400.

curl --request GET \
  --url 'http://example.com/s3creds/v1/object/%7B?object_path=object_path&object_path%7D%7B%3Fduration%7D='
var request = require("request");

var options = { method: 'GET',
  url: 'http://example.com/s3creds/v1/object/%7B',
  qs: 
   { object_path: 'object_path',
     'object_path}{?duration}': '' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("http://example.com/s3creds/v1/object/%7B?object_path=object_path&object_path%7D%7B%3Fduration%7D=")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://example.com/s3creds/v1/object/%7B?object_path=object_path&object_path%7D%7B%3Fduration%7D=");

xhr.send(data);
import requests

url = "http://example.com/s3creds/v1/object/%7B"

querystring = {"object_path":"object_path","object_path}{?duration}":""}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "S3_secret_key": "{temp_s3_secret_key}",
  "prefix": "{object_path}",
  "bucket": "gbd-customer-data",
  "S3_access_key": "{temp_s3_access_key}",
  "S3_session_token": "{temp_s3_session_token}"
}
 
Suggest Edits

Get Download URL for an object

Get a temporary download URL for an object using the GBDX S3 storage service

 

OAuth2 Auth

Bearer
Authenticate via OAuth2
 Authentication is required for this endpoint.
gethttps://geobigdata.io/s3creds/v1/object/url?object_name=folder/file.txt

Query Params

object_name
string

/{account_prefix}/{folder}/{object}`) ... full path to an object on S3. This includes the users account prefix.

 
curl --request GET \
  --url 'https://geobigdata.io/s3creds/v1/object/url?object_name=folder%2Ffile.txt'
var request = require("request");

var options = { method: 'GET',
  url: 'https://geobigdata.io/s3creds/v1/object/url',
  qs: { object_name: 'folder/file.txt' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://geobigdata.io/s3creds/v1/object/url?object_name=folder%2Ffile.txt")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://geobigdata.io/s3creds/v1/object/url?object_name=folder%2Ffile.txt");

xhr.send(data);
import requests

url = "https://geobigdata.io/s3creds/v1/object/url"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
  {
              "url": “{full s3 url to object}",
              "success": true
            }

Permissions Required: AUTH_USER

Note: The object must exist in the database, raises 404.

When a request is successful, the response body will provide the download URL.

Suggest Edits

Python Examples

Python example script for sending a request to the GBDX Storage service and accessing the contents of the S3 bucket.

 

Python Example #1

This Python script covers the following steps:

  1. Get your OAuth access token
  2. Request temporary credentials from the GBDX S3 Storage Service
  3. Send temporary credentials to AWS CLI
  4. Execute CLI command
 First install the aws cli:
        pip install aws-cli
        
        
        Copy this code into  create_s3tmp_creds.py :
        
        import requests
        
        # Get nricklin user token
        username = '<username>'
        password = '<password>'
        api_key = '<api-key>'
        
        token_url = 'https://geobigdata.io/auth/v1/oauth/token/'
        
        headers = {'Authorization': "Basic %s" % api_key}
        body = {"grant_type":'password', 'username': username, 'password': password}
        
        r = requests.post(token_url, headers=headers, data=body)
        
        access_token = r.json()['access_token']
        
        url          = 'https://geobigdata.io/s3creds/v1/prefix?duration=36000'
        headers      = {'Content-Type': 'application/json',"Authorization": "Bearer " + access_token}
        results      = requests.get(url,headers=headers)
        
        # print out the json results
        print "[DEFAULT]"
        print "aws_secret_access_key=" + results.json()['S3_secret_key']
        print "aws_access_key_id=" + results.json()['S3_access_key']
        print "aws_session_token=" + results.json()['S3_session_token']
        
        Dump credentials into your aws cli credentials file:
        python create_s3tmp_creds.py > ~/.aws/credentials
        
        
        Finally, use the AWS CLI to list items in your storage location:
        aws s3 ls s3://gbd-customer-data/<your_prefix>/

Python Example #2

This Python example assumes you already have a valid OAuth token. It competes the following steps:

  1. Request temporary credentials from the GBDX S3 Storage Service
  2. Send temporary credentials to AWS CLI
  3. Execute CLI command
```python
import requests
import json
import sys

access_token = "Bearer " + sys.argv[1]
url = 'https://geobigdata.io/s3creds/v1/prefix?duration=3600'
headers = {'Content-Type': 'application/json',"Authorization": access_token}
results = requests.get(url,headers=headers)
                
print
print "bucket/directory to send output data to: " + "s3://" + results.json()['bucket'] + "/" + results.json()['prefix']
print
print "### save the information below to a s3creds file for use with S3CMD"
print
print "[default]"
print "secret_key = " + results.json()['S3_secret_key']
print "access_key = " + results.json()['S3_access_key']
print "access_token = " + results.json()['S3_session_token']
#print "session_token = " + results.json()['S3_session_token']
print
```

Finally, use the AWS CLI to list items in your storage location:
        aws s3 ls s3://gbd-customer-data/<your_prefix>/
 
Suggest Edits

AnswerFactory Project Reference Overview

Overview of the AnswerFactory Project API

 
Table of Contents
AnswerFactory Project JSON
AnswerFactory Project API Parameters
Associated API Calls for AnswerFactory Projects

Project JSON

An AnswerFactory project consists of four main parts:

  • project metadata
  • a set of configurations for building "answers" for the project
  • a set of geometries defining the original base geometries for a project
  • a set of geometries defining a buffered area of interest (AOI) around those geometries

Error responses

For all requests, if an error occurs, the response body will consist of JSON formatted like this:

{ "error" : "message" }

The HTTP response code will depend on the error.

Project API Parameters

Parameter Data Type Parameter Type Description Required?
accountId String Body Identifier for account the owner of project belongs to; defaults to GBDX account the user making project creation request belongs to. Optional
acquisitionIds String Body String of comma or whitespace delimited catalog IDs/acquisition IDs of images to run recipes on. Optional
aois String Body Array of GeoJSON geometry with buffer applied. Required
continuouslyOrdered Boolean Body Determines whether the project watches for new images that intersect the project aoi. If true the project's recipes will be run on every new valid image that intersects the project aoi. Required
createDate ISO-8601 Formatted Date/Time String Body Timestamp when project was created in yyyy-MM-ddTHH:mm:ss.SSSZ format. Required
dateRange String Body Contains sub-parts startDate and endDate, providing the date range to restrict images/vectors to. Note: acquisitionIds trumps dateRange when project is being processed. See Date Range Sub-Part Parameters for sub-part definitions. Optional
description String Body User specified string; project description. Optional
enabled Boolean Body Determines whether the project is visible to anyone; if false this project will be hidden. Required
id String Body Project's unique identifier; must not be specified when creating an object. Required
name String Body User-specified project identifier. This is the human-readable project identifier; must be unique per account. Required
namedBuffers String Body Contains sub-parts name and buffer, providing individual aoi specifics for the project. See Named Buffers Sub-Part Parameters for sub-part definitions. Required
notes String Body User specified string; general notes for the project. Optional
originalGeometries String Body Array of GeoJSON objects from the source; source may be shapefile or other. Required
owner String Body Username of user who owns project; defaults to GBDX username of user making project creation request. Optional
recipeConfigs String Body Contains sub-parts recipeId, recipeName, configurationDate, startDate, endDate, and parameters, providing project-specfic recipe information. See Recipe Configs Sub-Part Parameters for sub-part definitions. Required
tags String Body User specified string or array of strings providing tags to associate with the project for easier lookup of similar projects. Multiple projects can have the same tag or tags. Example: "tags": [ "tag1", "tag-2" ] Optional
updateDate ISO-8601 Formatted Date/Time String Body Timestamp when project was last modified in yyyy-MM-ddTHH:mm:ss.SSSZ format. Required
visibility String Body Determines whether the project is made public to GBDX users or kept private; set to public to allow users outside the owner's account to view the project; otherwise leave as an empty array. Optional

Date Range Sub-Part Parameters

Parameter Data Type Parameter Type Description Required?
endDate ISO-8601 Formatted Date/Time String Body Sub-part of dateRange; latest timestamp in yyyy-MM-ddTHH:mm:ss.SSSZ format of input images/vectors to use when running all recipes. Optional
startDate ISO-8601 Formatted Date/Time String Body Sub-part of dateRange; earliest timestamp in yyyy-MM-ddTHH:mm:ss.SSSZ format of input images/vectors to use when running all recipes. Optional

Named Buffers Sub-Part Parameters

Parameter Data Type Parameter Type Description Required?
buffer String Body Sub-part of namedBuffers; GeoJSON geometry with buffer applied. Required
name String Body Sub-part of namedBuffers; user-facing identifier for area of interest. Required

Recipe Configs Sub-Part Parameters

Parameter Data Type Parameter Type Description Required?
configurationDate ISO-8601 Formatted Date/Time String Body Timestamp when recipe was added to project in yyyy-MM-ddTHH:mm:ss.SSSZ format. Required
endDate ISO-8601 Formatted Date/Time String Body Latest timestamp in yyyy-MM-ddTHH:mm:ss.SSSZ format of input images/vectors to use when running this recipe. Note: This endDate will be recipe-specific inside of the project; other recipes will not be effected by this parameter. Optional
parameters String Body Contains sub-parts such as name, type, and value that are recipe specific. See AnswerFactory Recipe Reference Overview for more details on recipe parameters. Only required if recipe parameter is required for the given recipe.
recipeId String Body Identifier of the recipe to run. Example: "recipeId": "query-tweets" Required
recipeName String Body The name of the recipe to run. Example: "recipeName": "Query Tweets" Required
startDate ISO-8601 Formatted Date/Time String Body Earliest timestamp in yyyy-MM-ddTHH:mm:ss.SSSZ format of input images/vectors to use when running this recipe. Note: This startDate will be recipe-specific inside of the project; other recipes will not be effected by this parameter. Optional

Associated API Calls for AnswerFactory Projects

Check availability of AnswerFactory Project Endpoints
Check uniqueness of AnswerFactory Project Name
Create an AnswerFactory Project
Delete an AnswerFactory Project
Retrieve an AnswerFactory Project
Retrieve Listing of AnswerFactory Projects for Account
Update an AnswerFactory Project

 
Suggest Edits

Check Availability of AnswerFactory Project Endpoints

AnswerFactory Project Heartbeat

 
gethttps://vector.geobigdata.io/answer-factory-project-service/api/heartbeat

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Setup:
Request:
GET /answer-factory-project-service/api/heartbeat

Response:
200 OK


Example:
https://vector.geobigdata.io/answer-factory-project-service/api/heartbeat
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
No response examples available
 
Suggest Edits

Check Uniqueness of AnswerFactory Project Name

 
posthttps://vector.geobigdata.io/answer-factory-project-service/api/project/validate/name

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Setup:
Request:
POST /answer-factory-project-service/api/project/validate/name

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Body:
  {
   "id": "guid of existing project; only applicable for pre-existing projects",
   "name": "human readable project name"
  }


Response:
200 OK


Examples:
New project:
https://vector.geobigdata.io/answer-factory-project-service/api/project/validate/name

Body:
{"name":"08May_index_t2"}


Change name on existing project:
https://vector.geobigdata.io/answer-factory-project-service/api/project/validate/name

Body:
{"id":"2a9219aa-e3ba-4a0b-8a86-19fd4c1c8e4a","name":"08May_index_t2"}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
OK
Project name must be unique in the system. (path = ProjectResource.validateProjectUniqueness.arg0, invalidValue = Project{id='null', owner='null', name='08May_index_t2', accountId='null', aois=null, recipeConfigs=null, originalGeometries=null, namedBuffers=null, createDate=null, updateDate=null, notes='null', description='null', tags=null, visibility=null, continuouslyOrdered=false, dateRange='null', acquisitionIds='null', enabled=true, attributes=null})
 
Suggest Edits

Create AnswerFactory Project

 
posthttps://vector.geobigdata.io/answer-factory-project-service/api/project

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Link reference in Example: AnswerFactory Project Reference Overview

Specifying the Recipe

To run the latest version of a recipe, refer to the "base" recipe id; that is, the recipe id with no version attached. An example base recipe id, referring to the latest version of the recipe: "recipeId": "example-recipe". With the version attached: "recipeId": "example-recipe:1.0.0".

Each time the recipe is updated, the base recipe id is also updated to refer to the newest version of the recipe. In addition, the recipe id is also updated with the latest version number. Previous versions of the recipe will still be available. If a user requires any specific version of the recipe, or if an externally configured service simply wants to avoid potentially breaking updates to a recipe, use the recipe id with the specific version number appended. For example: "recipeId": "example-recipe:2.0.0".

Note: The latest version of a recipe can also be called with its "versioned" recipe id. For example, if the recipe is on version 3.1.2: "recipeId": "example-recipe" and "recipeId": "example-recipe:3.1.2" will both refer to the same version, the latest version, of the recipe. However, to use any past version of a recipe, the recipe must be referred to specifically with the versioned recipe id. For example: "recipeId": "example-recipe:3.1.1".

Setup:
Request:
POST /answer-factory-project-service/api/project

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Body:
  {
   ... project definition: see AnswerFactory Project Reference Overview, linked in the docs section below example and results ...
  }

Notes:
  project ID must not be specified


Response (success):
202 Accepted


Example:
https://vector.geobigdata.io/answer-factory-project-service/api/project

Body:
{"id":null,"owner":"testuser","name":"TEST","accountId":"...","aois":[{"type":"Polygon","coordinates":[[[-77.045145,38.856419],[-77.04051,38.857355],[-77.038622,38.850403],[-77.042999,38.849401],[-77.045145,38.856419]]]}],"recipeConfigs":[{"recipeId":"query-aircraft","recipeName":"Query Aircraft","parameters":[],"configurationDate":"2017-05-09T16:07:09.919Z"}],"originalGeometries":[{"type":"Feature","properties":{"name":"AOI001"},"geometry":{"type":"Polygon","coordinates":[[[-77.045145035,38.856419107],[-77.040510178,38.857354835],[-77.038621902,38.850403422],[-77.042999268,38.849400758],[-77.045145035,38.856419107]]]}}],"namedBuffers":[{"name":"AOI001","buffer":{"type":"Polygon","coordinates":[[[-77.045145,38.856419],[-77.04051,38.857355],[-77.038622,38.850403],[-77.042999,38.849401],[-77.045145,38.856419]]]}}],"createDate":"2017-05-09T16:07:09.919Z","updateDate":"2017-05-09T16:07:09.919Z","notes":"","description":"","tags":[],"visibility":[],"continuouslyOrdered":false,"acquisitionIds":"","dateRange":{"startDate":null,"endDate":null,"count":null},"enabled":true,"attributes":null}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"id":"2a9219aa-e3ba-4a0b-8a86-19fd4c1c8e4a","owner":"testuser","name":"TEST","accountId":"...","aois":[{"type":"Polygon","coordinates":[[[-77.045145,38.856419],[-77.04051,38.857355],[-77.038622,38.850403],[-77.042999,38.849401],[-77.045145,38.856419]]]}],"recipeConfigs":[{"recipeId":"query-aircraft","recipeName":"Query Aircraft","parameters":[],"configurationDate":1494346029919}],"originalGeometries":[{"type":"Feature","properties":{"name":"AOI001"},"geometry":{"type":"Polygon","coordinates":[[[-77.045145035,38.856419107],[-77.040510178,38.857354835],[-77.038621902,38.850403422],[-77.042999268,38.849400758],[-77.045145035,38.856419107]]]}}],"namedBuffers":[{"name":"AOI001","buffer":{"type":"Polygon","coordinates":[[[-77.045145,38.856419],[-77.04051,38.857355],[-77.038622,38.850403],[-77.042999,38.849401],[-77.045145,38.856419]]]}}],"createDate":1494346029919,"updateDate":1494346029919,"notes":"","description":"","tags":[],"visibility":[],"continuouslyOrdered":false,"acquisitionIds":"","dateRange":{"startDate":null,"endDate":null,"count":null},"enabled":true,"attributes":null}
 
Suggest Edits

Delete AnswerFactory Project

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://vector.geobigdata.io/answer-factory-project-service/api/project/projectId

Path Params

projectId
string
required

The id of the project.

 
Setup:
Request:
DELETE /answer-factory-project-service/api/project/:projectId

Headers:
  Authorization: Bearer {token}

Params:
  projectId: the ID of the project to delete

Notes:
  Requesting user's account must be project owner's account
  If project is public then requesting user must be project's owner


Response (success):
200 OK


Example:
https://vector.geobigdata.io/answer-factory-project-service/api/project/349a5f7e-152d-4182-9807-73ad0c226b2b
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Retrieve AnswerFactory Project

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-project-service/api/project/projectId

Path Params

projectId
string
required

The id of the project.

Link reference in Example: AnswerFactory Project Reference Overview

Setup:
Request:
GET /answer-factory-project-service/api/project/:projectId

Headers:
  Authorization: Bearer {token}
  Accept: application/json

Params:
  projectId: the ID of the project to retrieve


Response (success):
200 OK

Body:
  {
   ... project definition: see AnswerFactory Project Reference Overview, linked in the docs section below example and results ...
  }


Example:
https://vector.geobigdata.io/answer-factory-project-service/api/project/b1a51475-783b-45b5-bf0d-86e881354575
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "b1a51475-783b-45b5-bf0d-86e881354575",
  "owner": "cberman",
  "name": "08May_index_t1",
  "accountId": "c8f...",
  "aois": [
    {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -77.006355,
            38.844137
          ],
          [
            -77.004263,
            38.844103
          ],
          [
            -77.004434,
            38.842942
          ],
          [
            -77.006462,
            38.843042
          ],
          [
            -77.006355,
            38.844137
          ]
        ]
      ]
    }
  ],
  "recipeConfigs": [
    {
      "recipeId": "query-foliage",
      "recipeName": "Query Foliage",
      "configurationDate": 1494240768199,
      "startDate": null,
      "endDate": null,
      "parameters": []
    }
  ],
  "originalGeometries": [
    {
      "type": "Feature",
      "properties": {
        "name": "AOI001"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -77.006354928,
              38.844136542
            ],
            [
              -77.006462216,
              38.84304187
            ],
            [
              -77.004434466,
              38.842941594
            ],
            [
              -77.004262805,
              38.844103117
            ],
            [
              -77.006354928,
              38.844136542
            ]
          ]
        ]
      }
    }
  ],
  "namedBuffers": [
    {
      "name": "AOI001",
      "buffer": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -77.006355,
              38.844137
            ],
            [
              -77.004263,
              38.844103
            ],
            [
              -77.004434,
              38.842942
            ],
            [
              -77.006462,
              38.843042
            ],
            [
              -77.006355,
              38.844137
            ]
          ]
        ]
      }
    }
  ],
  "createDate": 1494240559917,
  "updateDate": 1494240769863,
  "notes": "",
  "description": "",
  "tags": [],
  "visibility": [],
  "continuouslyOrdered": false,
  "acquisitionIds": "",
  "dateRange": {
    "startDate": 1483271387756,
    "endDate": 1494240600592,
    "count": null
  },
  "enabled": true,
  "attributes": null
}
 
Suggest Edits

Retrieve Listing of AnswerFactory Projects for Account

Retrieve a listing of projects for the current users account

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-project-service/api/project
 
Setup:
Request:
GET /answer-factory-project-service/api/project

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
[ 
  { "name": "project 1 name",
    "id": "project 1 ID"
  },
  { "name": "project 2 name",
    "id": "project 2 ID"
  },  
  { "name": "project 3 name",
    "id": "project 3 ID"
  },
  ...
]


Example:
https://vector.geobigdata.io/answer-factory-project-service/api/project
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "name": "07Apr_query-summarize_t2",
    "id": "c623d80b-c785-4a59-aeff-a557a27219a6"
  },
  {
    "name": "eric_Chimney_Tops",
    "id": "94848cd0-a1d8-427a-a79f-8441c36cf133"
  },
...
]
 
Suggest Edits

Update AnswerFactory Project

 
puthttps://vector.geobigdata.io/answer-factory-project-service/api/project/projectId

Path Params

projectId
string
required

The id of the project.

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Link reference in Example: AnswerFactory Project Reference Overview

For details on specifying the recipe version, check Create AnswerFactory Project.

Setup:
Request:
PUT /answer-factory-project-service/api/project/:projectId

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Params:
  projectId: the ID of the project to update

Body:
  {
   ... project definition: see AnswerFactory Project Reference Overview, linked in the docs section below example and results ...
  }

Notes:
  Project ID must be specified and match projectId param
  If project is public then requesting user must be project's owner
  Any newly added recipes will be run
  Any removed recipes will have their results deleted


Response (success):
202 Accepted


Example:
https://vector.geobigdata.io/answer-factory-project-service/api/project/2a9219aa-e3ba-4a0b-8a86-19fd4c1c8e4a

Body:
{"id":"2a9219aa-e3ba-4a0b-8a86-19fd4c1c8e4a","owner":"testuser","name":"TEST","accountId":"...","aois":[{"type":"Polygon","coordinates":[[[-77.045145,38.856419],[-77.04051,38.857355],[-77.038622,38.850403],[-77.042999,38.849401],[-77.045145,38.856419]]]}],"recipeConfigs":[{"recipeId":"query-aircraft","recipeName":"Query Aircraft","parameters":[],"configurationDate":"2017-05-08T14:05:00.367Z"}],"originalGeometries":[{"type":"Feature","properties":{"name":"AOI001"},"geometry":{"type":"Polygon","coordinates":[[[-77.045145035,38.856419107],[-77.040510178,38.857354835],[-77.038621902,38.850403422],[-77.042999268,38.849400758],[-77.045145035,38.856419107]]]}}],"namedBuffers":[{"name":"AOI001","buffer":{"type":"Polygon","coordinates":[[[-77.045145,38.856419],[-77.04051,38.857355],[-77.038622,38.850403],[-77.042999,38.849401],[-77.045145,38.856419]]]}}],"createDate":"2017-05-08T14:00:56.679Z","updateDate":"2017-05-08T14:00:56.679Z","notes":"","description":"","tags":[],"visibility":[],"continuouslyOrdered":false,"acquisitionIds":"","dateRange":{"startDate":"2013-02-05T15:00:56.646Z","endDate":"2017-05-08T14:05:30.149Z","count":null},"enabled":true,"attributes":null}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "projectId" : "2a9219aa-e3ba-4a0b-8a86-19fd4c1c8e4a"
}
 
Suggest Edits

AnswerFactory Recipe Reference Overview

Overview of the AnswerFactory Recipe API

 
Table of Contents
AnswerFactory Recipe JSON
AnswerFactory Recipe API Parameters
Associated API Calls for AnswerFactoryRecipes

Recipe JSON

An AnswerFactory recipe consists of four main parts:

  • recipe metadata
  • recipe type metadata
  • a set of parameters that will ultimately be configurable by an AnswerFactory user
  • a set of properties specific to the recipe that are not part of the general metadata

Error responses

For all requests, if an error occurs, the response body will consist of JSON formatted like this:

{ "error" : "message" }

The HTTP response code will depend on the error.

Recipe API Parameters

Parameter Data Type Parameter Type Description Required?
access String Body Set to 'disabled' to hide recipe. Optional
accountId String Body Identifier for account recipe is visible to; defaults to GBDX account the user making recipe creation request belongs to. Leave as empty array to make recipe public. Optional
definition String Body String or JSON object that describes how the specified system should execute the recipe. Required
description String Body Explanation of what the recipe does. Required
id String Body Recipe's unique identifier. For example, query-tweets. Required
inputType String Body Name of the input to the recipe. For example, acquisition. Required
name String Body The human-readable unique recipe identifier. For example, Query Tweets. Required
owner String Body The username of the user who created recipe; defaults to GBDX username of user making recipe creation request. Optional
outputType String Body Name of the output to the recipe; determines how the result of the recipe will be displayed. Required
parameters String Body Contains sub-parts name, description, type, required, allowedValues, and allowMultiple, providing specific information on parameters necessary for recipe execution. See Parameters Sub-Part Parameters for sub-part definitions. Optional
parentRecipeId String Body The id of the recipe to inherit non-overriden fields from. Optional
prerequisites String Body Contains sub-parts aggregator, id, and properties, providing specifics on recipes that must run as precursors to this recipe. See Prerequisites Sub-Part Parameters for sub-part definitions. Optional
properties String Body List of properties associated with the recipe, in the format "property key 1":"property value 1", "property key 2":"property value 2", "...":"...". For example, "image_bands": "Pan_MS1,Pan_MS1_MS2". For more information on particular properties, go here. Optional
recipeType String Body Name of the system utilized to execute the recipe. Required
version String Body Formatted as 'major.minor.patch'. Set by default to 1.0.0 when submitting a recipe, and automatically iterates when the recipe is updated. Next iteration will be 2.0.0, then 3.0.0, etc. Version can be manually set, but there will be an error if version is set to the value of an already existing version. For example, if version 2.0.1 exists, attempting to save with "version" : "2.0.1" will error. Required (automatically added), optional to manually enter
virtual Boolean Body Values may be true or false. Recipes with virtual set to true are not independent recipes and cannot be run by themselves; these recipes inherent the workflow definition from runnable recipes. If virtual is not set, it will default to false. Optional

Parameters Sub-Part Parameters

Parameter Data Type Parameter Type Description Required?
allowMultiple Boolean Body Sub-part of parameters; if allowedValues is set and this is true than the user can select more than one of the allowedValues; otherwise users can only select one of the allowedValues at a time. Optional
allowedValues String Body Sub-part of parameters; array of acceptable values, in the format of "possible value 1", "possible value 2", .... For example, RoadTracker has allowedValues of "Dirt_Urban", "Trail", "Suburban". Optional
description String Body Sub-part of parameters; the explanation of the parameter. Optional
name String Body Sub-part of parameters; the unique identifier for the parameter. Optional
required Boolean Body Sub-part of parameters; true if the user must specify parameter; false otherwise. Optional
type String Body Sub-part of parameters; the type of parameter value. Optional

Prerequisites Sub-Part Parameters

Parameter Data Type Parameter Type Description Required?
aggregator String Body Sub-part of prerequisites; how to combine results of prerequisite recipe before running this recipe. Required if prerequisites are part of the recipe, optional if no prerequisites
id String Body Sub-part of prerequisites; id of recipe to execute before the primary recipe. Required if prerequisites are part of the recipe, optional if no prerequisites
properties String Body Sub-part of prerequisites; list of properties associated with the prerequisites to the recipe, in the format "property key 1":"property value 1", "property key 2":"property value 2", "...":"...". Optional

For greater detail in formatting and putting together a recipe json, review the Create a Recipe with JSON Object page.

Associated API Calls for AnswerFactory Recipes

Check Availability of AnswerFactory Recipe Endpoints
Create a Recipe with JSON Object for Recipe Definition
Create a Recipe with JSON String for Recipe Definition
Delete a Recipe
Retrieve a Recipe
Retrieve Listing of Recipes for Account
Send Recipe Suggestion
Update a Recipe with JSON Object for Recipe Definition
Update a Recipe with JSON String for Recipe Definition
Recipe Runner Blueprints
Recipe Runner Blueprint Build

 
Suggest Edits

Check Availability of AnswerFactory Recipe Endpoints

AnswerFactory Recipe Heartbeat

 
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/heartbeat

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Setup:
Request:
GET /answer-factory-recipe-service/api/heartbeat

Response:
200 OK


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/heartbeat
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
No response examples available
 
Suggest Edits

Create a Recipe with JSON Object

Create a recipe with JSON object for recipe definition

 
posthttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/json

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Link reference in Example: AnswerFactory Recipe Reference Overview

For this version of the recipe creation API call, the recipe definition parameter must be a JSON object which the specified recipe type can understand. See Create a Recipe with JSON String for set up to support using a JSON string for the recipe definition.

Below are the currently supported combinations of recipeType, inputType, and outputType:

recipeType inputType outputType
workflow none vector-service
workflow acquisition vector-service
workflow acquisitions vector-service
workflow vector-service vector-service
partitioned-workflow acquisition vector-service
workflow seasonal-acquisition vector-service
partitioned-workflow seasonal-acquisition vector-service
workflow acquisitions esri-service
workflow esri-service esri-service
vector-query vector-service vector-service
vector-aggregation vector-service vector-service

Note: The entire recipe needs to be included in the body. The difference between this endpoint and the JSON string endpoint is that this endpoint converts the recipe definition parameter to a string, which is useful for workflow recipes.

Note: In most cases, when creating an Extraction (or workflow) recipe, use JSON Object. When creating a Query recipe, use JSON String.

Substitution Variables

GBDX Workflows must be appropriately templatized so that AnswerFactory knows how to apply inputs and outputs to the recipe. The following curly-bracket substitutions are available to be used in the workflow and are automatically replaced with their specific values when executed:

When recipeType=workflow
{user} - GBDX username of project creator
{project_id} - unique identifier for project
{project_name} - identifier specified by user for project
{recipe_id} - unique identifier for project
{recipe_name} - human readable identifier for recipe
{project_geometry} - project AOI in WKT format
{task_name} - name of workflow task this substitution variable is contained in; not to be confused with task type

When recipeType=workflow AND outputType=vector-service
{run_id} - unique identifier for this execution of a recipe for a given project; part of the
Vector Service query string to retrieve the output vectors
{vector_host} - Vector Service host, for example vector.geobigdata.io if production,
devvector.geobigdata.io if dev
{vector_ingest_bucket} - name of the bucket Vector Services uses for ingest
{ingest_date} - time of workflow submission in yyyyMMdd format
{query_index} - name of Vector Service index the output vectors
will be ingested to

When recipeType=workflow AND inputType=acquisition/acquisitions
{raster_path} - S3 location of input acquisition
{raster_path_i} - S3 location of input acquisition i, where i is 0,1,2...
{catalog_id} - catalog identifier of input acquisition
{catalog_id_i} - catalog identifier of input acquisition i, where i is 0,1,2...
{acquisition_id} - acquisition ID of input acquisition
{acquisition_id_i} - acquisition ID of input acquisition i, where i is 0,1,2...
{acquisition_date} - timestamp of input acquisition
{acquisition_date_i} - timestamp of input acquisition i, where i is 0,1,2...
{acquisition_bands} - bands field (Pan, Pan_MS1, Pan_MS1_MS2, etc) of input acquisition
{acquisition_bands_i} - bands field (Pan, Pan_MS1, Pan_MS1_MS2, etc) of input acquisition i, where i is 0,1,2...
{acquisition_geometry} - footprint in WKT format of input acquisition
{acquisition_geometry_i} - footprint in WKT format of input acquisition i, where i is 0,1,2...
{acquisition_index_i} - zero based position of input acquisition i in list of input acquistions, where i is 0,1,2...; equal to 0,1,2...
{acquisition_intersection} - intersection of all input acquisitions' geometries in WKT format
{project_acquisition_intersection} - intersection of project AOI and intersection of all input acquisitions' geometries in WKT format
{model_location_s3} - S3 location of best model in Model Catalog, if applicable

When recipeType=workflow AND inputType=vector-service AND outputType=vector-service
{query_string} - Vector Service query of input
{query_string_i} - Vector Service query of input i, where i is 0,1,2...
{query_index} - Vector Service index of input
{query_index_i} - Vector Service index of input i, where i is 0,1,2...
{result_geometry} - preceding recipe result geometry in WKT format

User-Defined Substitution Variables

Additional recipe-specific substitution variables may be used to pass additional information into the workflow tasks via the recipe "parameters" section.

Example of recipe with parameters: 

{
  "id": "extract-roads",
  "name": "Extract Roads",
  "parameters": [
    {
      "name": "road_type",
      "allowedValues": [
        "Dirt Urban",
        "Suburban",
        "Trails"
      ],
      "allowMultiple": true
    }
  ]
  ...
}

At a minimum the parameter name is required. This is what is shown in the UI to the user and specifiable via REST API call. The substitution variable is based on the name, in this case it'll be "{road_type}".

allowedValues is optional and restricts the the user to the enumerated values. In the UI this is shown as a dropdown list.

allowMultiple gives the user the option to pick more than one value. In that case AnswerFactory would handle adding additional tasks for each value selected.

Recipe Properties

Properties contains the specific key/value pairs for a particular recipe type, for example "acquisition_types":"LandsatAcquisition" is a property specific to recipes that take acquisitions as input.

Note these are also used as substitution variables, so using the earlier example, "{acquisition_types}" would get replaced with "LandsatAcquisition".

When inputType=acquisition/acquisitions
acquisition_types - comma delimited list that filters input acquisitions by type; possible values: DigitalGlobeAcquisition, LandsatAcquisition, SENTINEL2, MDAProduct; defaults to DigitalGlobeAcquisition
image_bands - comma delimited list that filters input acquisitions by bands field; possible values are Pan, Pan_MS1, Pan_MS1_MS2; defaults to allow any number of bands
input_filter - a Vector Services ES query string for specialized acquisition filters, for example "attributes.offNadirAngle_dbl:[* TO 10] AND attributes.sunElevation_dbl:[70 TO *]"; no default values
num_acquisitions - the number of acquisitions that this recipe requires as input specified as an integer or a range, for example 1, 2, 1-7 are all valid; defaults to 1
reusable_results_enabled - true or false; if false, previously processed results will be ignored upon recipe kickoff, while if true previously processed results will be used if all requirements are met; defaults to true.
sensors - comma delimited list that filters input acquisitions by sensors, for example WORLDVIEW03_VNIR, GEOEYE01

When recipeType=workflow AND inputType=acquisition/acquisitions
crop_to_project - true or false; if true crops input acquisitions to project AOI; defaults to true
model_type - type of model registered in Model Catalog to retrieve for input acquisitions
order_type - what level of acquisition to order; possible values: 1B, OR2A; defaults to 1B
rda_enabled - true or false; if true, uses RDA for data. _Note: RDA does not currently support DRA, so if DRA is required, do not set rdaenabled to true.

When recipeType=partitioned-workflow AND inputType=acquisition/acquisitions
partition_size - max size in square kilometers of each chunk of the acquistition to process in a single task; defaults to 100

When outputType=vector-service
additional_display_fields - comma delimited list of names of Vector Service item fields to show in UI vector table (double clicking a cell)
calculate_vector_metrics - true or false; if true calculations over resulting vectors are made like area, length, etc; defaults to true
hover_fields - comma delimited list of name of Vector Service item fields to show in UI when hovering over vector on map; format is NameToDisplayInUI:NameOfVectorServiceField
summary_sum_field - name of Vector Service item field used to calculate sum

When recipeType=vector-query AND inputType=vector-service AND outputType=vector-service
query_index - Vector Service index to query; defaults to all vector indexes

When recipeType=vector-aggregation AND inputType=vector-service AND outputType=vector-service
query_index - Vector Service index to aggregate; defaults to all vector indexes

Automatic Workflow Expansion

AnswerFactory automatically analyzes and expands the supplied workflow definition to enable the workflow to perform AnswerFactory specific tasks, such as ingesting to VectorServices or partitioning an image into multiple chunks for parallelized processing. Below is a list of such workflow expansions:

When recipeType=workflow
When multiple values are selected by the user for a recipe config parameter with allowMultiple=true: a corresponding number of algorithm tasks will be added: one for each selected value.

When recipeType=workflow AND outputType=vector-service
Existing IngestToVectorServices tasks will be updated: the optional additionalFields port will be populated with ingest attributes for run_id_raw, project_id_raw, recipe_id_raw appended; the callbackUrl port will be set to notify AnswerFactory when the vector ingest is complete; the index port will be defaulted to "vector-workflow-{ingest_date}"

When recipeType=workflow AND inputType=acquisition/acquisitions
If an input acquisition is not available on GBDX then an Auto_Ordering task (or Auto_Ordering_OR2A task depending on the order_type property) will be added before any task with {raster_path} or {raster_path_i} substitutions.
If the crop_enabled property is not set or is set to True then a CropGeotiff task is added after each task containing {raster_path} or {raster_path_i} to crop to the project AOI if there are no existing CropGeotiff tasks. If there are exitsing CropGeotiff tasks then their wkt input ports will be set to the project AOI.

When recipeType=partitioned-workflow AND inputType=acquisition/acquisitions
If the intersection of acquisition and project AOI is greater than partition_size property square kilometers, then additional CropGeotiff tasks are added as well as the corresponding chain of subsequent tasks to process the piece of the input acquisition that the CropGeotiff outputs.

Setup:
Request:
POST /answer-factory-recipe-service/api/recipe/json

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Body:
  {
   ... recipe definition: see AnswerFactory Recipe Reference Overview, linked in the docs section below example and results ...
  }


Response (success):
202 Accepted


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/json

Body:
{
        "id": "test-workflow-recipe",
        "version": "1.0.1",
        "name": "Test Workflow Recipe",
        "owner": "testuser",
        "description": "Manually deciding version number here, but that is unnecessary.",
        "recipeType": "workflow",
        "inputType": "vector-service",
        "outputType": "vector-service",
        "parameters": [ {
                "name": "compare_with",
                "type": "string",
                "required": true,
                "description": "Compare With",
                "allowedValues": [ "next most recent", "1 month", "1 year" ],
                "allowMultiple": false
            } ],
        "prerequisites": [ {
                "id": "extract-protogen-lulc:1.0.0",
                "aggregator": "PAIR_INTERSECTION",
                "operator": null,
                "properties": {}
            } ],
        "definition": "{\"tasks\":[{\"name\":\"compare\",\"taskType\":\"CompareVectors\",\"timeout\":36000,\"impersonation_allowed\":true,\"inputs\":[{\"name\":\"host\",\"value\":\"{vector_host}\"},{\"name\":\"query_a\",\"value\":\"{query_string_0}\"},{\"name\":\"query_b\",\"value\":\"{query_string_1}\"},{\"name\":\"index_a\",\"value\":\"{query_index_0}\"},{\"name\":\"index_b\",\"value\":\"{query_index_1}\"},{\"name\":\"wkt\",\"value\":\"{result_geometry}\"},{\"name\":\"group_by_fields\",\"value\":\"item_type\"},{\"name\":\"min_area\",\"value\":\"500\"}],\"outputs\":[{\"name\":\"data\"}]},{\"name\":\"vector\",\"taskType\":\"IngestShpToVectorServices\",\"timeout\":36000,\"impersonation_allowed\":true,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"items\",\"source\":\"compare:data\"},{\"name\":\"shapefileMapping\",\"value\":\"vector.crs=EPSG:4326\\nvector.ingestSource=Test Workflow\\nitem_type=item_type\"}],\"outputs\":[{\"name\":\"result\"}]},{\"name\":\"s3_vector\",\"taskType\":\"SaveToS3\",\"timeout\":36000,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"data\",\"source\":\"vector:result\"},{\"name\":\"destination\",\"value\":\"s3://{vector_ingest_bucket}/{recipe_id}/{run_id}/{task_name}\"}],\"outputs\":[]}],\"name\":\"extract\"}"
}
Setup:
Request:
POST /answer-factory-recipe-service/api/recipe/json

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Body:
  {
   ... recipe definition: see AnswerFactory Recipe Reference Overview, linked in the docs section below example and results ...
  }


Response (success):
202 Accepted


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/json

Body:
{
        "id": "test-recipe",
        "version": "0.0.1",
        "name": "Test Recipe",
        "owner": "testuser",
        "description": "Manually deciding version number here, but that is unnecessary.",
        "recipeType": "partitioned-workflow",
        "inputType": "acquisition",
        "outputType": "vector-service",
        "parameters": [
            {
                "name": "feature_type",
                "type": "string",
                "required": true,
                "description": "",
                "allowedValues": [
                    "Dirt Urban",
                    "Suburban",
                    "Trails"
                ],
                "allowMultiple": true
            }
        ],
        "properties": {
            "image_bands": "Pan_MS1, Pan_MS1_MS2",
            "rda_enabled": "true"
        },
        "definition": "{\"name\":\"rt_automated\",\"tasks\":[{\"name\":\"aop\",\"taskType\":\"AOP_Strip_Processor\",\"containerDescriptors\":[{\"properties\":{\"domain\":\"raid\"}}],\"inputs\":[{\"name\":\"data\",\"value\":\"{raster_path}\"},{\"name\":\"enable_dra\",\"value\":\"false\"},{\"name\":\"enable_pansharpen\",\"value\":\"true\"},{\"name\":\"enable_acomp\",\"value\":\"true\"},{\"name\":\"ortho_epsg\",\"value\":\"UTM\"},{\"name\":\"ortho_interpolation_type\",\"value\":\"Bilinear\"}],\"outputs\":[{\"name\":\"log\"},{\"name\":\"data\"}]},{\"taskType\":\"rt_support\",\"name\":\"rt_support\",\"inputs\":[{\"name\":\"data\",\"source\":\"aop:data\"},{\"name\":\"featuretype\",\"value\":\"all\"},{\"name\":\"filename\",\"value\":\"False\"},{\"name\":\"numthreads\",\"value\":\"16\"}],\"outputs\":[{\"name\":\"out\"}]},{\"name\":\"rt_automated\",\"taskType\":\"rt_automated\",\"inputs\":[{\"name\":\"data\",\"source\":\"rt_support:out\"},{\"name\":\"featuretype\",\"value\":\"{feature_type}\"},{\"name\":\"filename\",\"value\":\"False\"},{\"name\":\"inputshpname\",\"value\":\"du.shp\"},{\"name\":\"missingfeatures\",\"value\":\"true\"},{\"name\":\"numthreads\",\"value\":\"4\"}],\"outputs\":[{\"name\":\"out\"}]},{\"name\":\"reproject\",\"taskType\":\"gdal-cli-multiplex:0.0.1\",\"inputs\":[{\"name\":\"data\",\"source\":\"rt_automated:out\"},{\"name\":\"command\",\"value\":\"mkdir -p $outdir/data; ogr2ogr -f \\\"ESRI Shapefile\\\" -a_srs \\\"EPSG:4326\\\" -t_srs \\\"EPSG:4326\\\" $outdir/data/reprojected.shp $indir/data/*.shp\"}],\"outputs\":[{\"name\":\"data\"}]},{\"name\":\"vector\",\"taskType\":\"IngestShpToVectorServices\",\"impersonation_allowed\":true,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"items\",\"source\":\"reproject:data\"},{\"name\":\"shapefileMapping\",\"value\":\"vector.crs\\u003dEPSG:4326\\nvector.ingestSource\\u003dRoad Tracker\\nFeatTyp_GE\\u003ditem_type\\n\"}],\"outputs\":[{\"name\":\"result\"}]}]}"
    }
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "test-workflow-recipe:1.0.1",
    "version": "1.0.1",
    "name": "Test Workflow Recipe",
    "owner": "testuser",
    "accountId": null,
    "access": null,
    "description": "Manually deciding version number here, but that is unnecessary.",
    "recipeType": "workflow",
    "inputType": "vector-service",
    "outputType": "vector-service",
    "parentRecipeId": null,
    "virtual": null,
    "defaultDayRange": null,
    "parameters": [
        {
            "name": "compare_with",
            "type": "string",
            "required": true,
            "description": "Compare With",
            "allowedValues": [
                "next most recent",
                "1 month",
                "1 year"
            ],
            "allowMultiple": false
        }
    ],
    "validators": null,
    "prerequisites": [
        {
            "id": "extract-protogen-lulc:1.0.0",
            "aggregator": "PAIR_INTERSECTION",
            "operator": null,
            "properties": {}
        }
    ],
    "linkedTo": null,
    "properties": null,
    "definition": "{\"tasks\":[{\"name\":\"compare\",\"taskType\":\"CompareVectors\",\"timeout\":36000,\"impersonation_allowed\":true,\"inputs\":[{\"name\":\"host\",\"value\":\"{vector_host}\"},{\"name\":\"query_a\",\"value\":\"{query_string_0}\"},{\"name\":\"query_b\",\"value\":\"{query_string_1}\"},{\"name\":\"index_a\",\"value\":\"{query_index_0}\"},{\"name\":\"index_b\",\"value\":\"{query_index_1}\"},{\"name\":\"wkt\",\"value\":\"{result_geometry}\"},{\"name\":\"group_by_fields\",\"value\":\"item_type\"},{\"name\":\"min_area\",\"value\":\"500\"}],\"outputs\":[{\"name\":\"data\"}]},{\"name\":\"vector\",\"taskType\":\"IngestShpToVectorServices\",\"timeout\":36000,\"impersonation_allowed\":true,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"items\",\"source\":\"compare:data\"},{\"name\":\"shapefileMapping\",\"value\":\"vector.crs=EPSG:4326\\nvector.ingestSource=Test Workflow\\nitem_type=item_type\"}],\"outputs\":[{\"name\":\"result\"}]},{\"name\":\"s3_vector\",\"taskType\":\"SaveToS3\",\"timeout\":36000,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"data\",\"source\":\"vector:result\"},{\"name\":\"destination\",\"value\":\"s3://{vector_ingest_bucket}/{recipe_id}/{run_id}/{task_name}\"}],\"outputs\":[]}],\"name\":\"extract\"}"
}
{
        "id": "test-recipe:0.0.1",
        "version": "0.0.1",
        "name": "Test Recipe",
        "owner": "testuser",
        "accountId": null,
        "access": null,
        "description": "Manually deciding version number here, but that is unnecessary.",
        "recipeType": "partitioned-workflow",
        "inputType": "acquisition",
        "outputType": "vector-service",
        "parentRecipeId": null,
        "virtual": null,
        "defaultDayRange": null,
        "parameters": [
            {
                "name": "feature_type",
                "type": "string",
                "required": true,
                "description": "",
                "allowedValues": [
                    "Dirt Urban",
                    "Suburban",
                    "Trails"
                ],
                "allowMultiple": true
            }
        ],
        "validators": null,
        "prerequisites": null,
        "linkedTo": null,
        "properties": {
            "image_bands": "Pan_MS1, Pan_MS1_MS2",
            "rda_enabled": "true"
        },
        "definition": "{\"name\":\"rt_automated\",\"tasks\":[{\"name\":\"aop\",\"taskType\":\"AOP_Strip_Processor\",\"containerDescriptors\":[{\"properties\":{\"domain\":\"raid\"}}],\"inputs\":[{\"name\":\"data\",\"value\":\"{raster_path}\"},{\"name\":\"enable_dra\",\"value\":\"false\"},{\"name\":\"enable_pansharpen\",\"value\":\"true\"},{\"name\":\"enable_acomp\",\"value\":\"true\"},{\"name\":\"ortho_epsg\",\"value\":\"UTM\"},{\"name\":\"ortho_interpolation_type\",\"value\":\"Bilinear\"}],\"outputs\":[{\"name\":\"log\"},{\"name\":\"data\"}]},{\"taskType\":\"rt_support\",\"name\":\"rt_support\",\"inputs\":[{\"name\":\"data\",\"source\":\"aop:data\"},{\"name\":\"featuretype\",\"value\":\"all\"},{\"name\":\"filename\",\"value\":\"False\"},{\"name\":\"numthreads\",\"value\":\"16\"}],\"outputs\":[{\"name\":\"out\"}]},{\"name\":\"rt_automated\",\"taskType\":\"rt_automated\",\"inputs\":[{\"name\":\"data\",\"source\":\"rt_support:out\"},{\"name\":\"featuretype\",\"value\":\"{feature_type}\"},{\"name\":\"filename\",\"value\":\"False\"},{\"name\":\"inputshpname\",\"value\":\"du.shp\"},{\"name\":\"missingfeatures\",\"value\":\"true\"},{\"name\":\"numthreads\",\"value\":\"4\"}],\"outputs\":[{\"name\":\"out\"}]},{\"name\":\"reproject\",\"taskType\":\"gdal-cli-multiplex:0.0.1\",\"inputs\":[{\"name\":\"data\",\"source\":\"rt_automated:out\"},{\"name\":\"command\",\"value\":\"mkdir -p $outdir/data; ogr2ogr -f \\\"ESRI Shapefile\\\" -a_srs \\\"EPSG:4326\\\" -t_srs \\\"EPSG:4326\\\" $outdir/data/reprojected.shp $indir/data/*.shp\"}],\"outputs\":[{\"name\":\"data\"}]},{\"name\":\"vector\",\"taskType\":\"IngestShpToVectorServices\",\"impersonation_allowed\":true,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"items\",\"source\":\"reproject:data\"},{\"name\":\"shapefileMapping\",\"value\":\"vector.crs\\u003dEPSG:4326\\nvector.ingestSource\\u003dRoad Tracker\\nFeatTyp_GE\\u003ditem_type\\n\"}],\"outputs\":[{\"name\":\"result\"}]}]}"
    }
 
Suggest Edits

Create a Recipe with JSON String

Create a recipe with JSON string for recipe definition

 
posthttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipe

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Link reference in Example: AnswerFactory Recipe Reference Overview

For this version of the recipe creation API call, the recipe definition parameter must be a string which the specified recipe type can understand. See Create a Recipe with JSON Object for set up to support using a JSON object for the recipe definition.

Note: In most cases, when creating an Extraction (or workflow) recipe, use JSON Object. When creating a Query recipe, use JSON String.

Setup:
Request:
POST /answer-factory-recipe-service/api/recipe

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Body:
  {
   ... recipe definition: see AnswerFactory Recipe Reference Overview, linked in the docs section below example and results ...
  }


Response (success):
202 Accepted


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe

Body:
{
  "id": "test-recipe",
  "name": "Test Recipe",
  "owner": "testuser",
  "accountId" : ["..."],
  "definition": "item_type:test",
  "description": "No need to include version; it's automatic.",
  "recipeType": "vector-query",
  "inputType": "vector-service",
  "outputType": "vector-service",
  "properties": {
    "query_index": "test-result"
  }
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "test-recipe:1.0.0",
    "version": "1.0.0",
    "name": "Test Recipe",
    "owner": "testuser",
    "accountId": [
        "..."
    ],
    "access": null,
    "description": "No need to include version; it's automatic.",
    "recipeType": "vector-query",
    "inputType": "vector-service",
    "outputType": "vector-service",
    "parentRecipeId": null,
    "virtual": null,
    "defaultDayRange": null,
    "parameters": null,
    "validators": null,
    "prerequisites": null,
    "linkedTo": null,
    "properties": {
        "query_index": "test-result"
    },
    "definition": "item_type:test"
}
 
Suggest Edits

Delete a Recipe

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/recipeId

Path Params

recipeId
string
required

Unique identifier of the recipe.

Specifying the Recipe Version

With recipe versioning, it is possible to delete a specific version of the recipe but leave the other versions. To delete a specific version of a recipe, include the version number in the recipeID.

For example, assume that there is a recipe with versions "example-recipe:2.0.0" and "example-recipe:2.0.1" in GBDX. Using the REST call
DEL https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/example-recipe:2.0.1
Will only delete "example-recipe:2.0.1", but will leave all other versions of the recipe, such as "example-recipe:2.0.0", for instance, available to users.

To delete ALL versions of a recipe, leave off the recipe version in the recipeID.

For example,
DEL https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/example-recipe
Will delete all versions of example-recipe, from the first to the final version that exists within GBDX.

Note Deleting a recipe disables it, allowing users to continue to view the results that already exist, but no longer allowing users to run the recipe.

Setup:
Request:
DELETE /answer-factory-recipe-service/api/recipe/:recipeId

Headers:
  Authorization: Bearer {token}

Params:
  recipeId: the ID of the recipe to delete


Response (success):
200 OK


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/query-test
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Recipe Listing

Retrieve a short, "id, name" listing of recipes available to the current users account

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipes/listing

Note: This endpoint only displays the "latest" version of a recipe - no version id included.

Setup:
Request:
GET /answer-factory-recipe-service/api/recipes/listing

Headers:
  Authorization: Bearer {token}


Response (success):
200 OK

Body:
[
    {
        "id": recipe id,
        "name": recipe name
    },
    {
        "id": recipe id,
        "name": recipe name
    },
    {
        "id": recipe id,
        "name": recipe name
    },
        ...
]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipes/listing
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "id": "circular-tank-detector",
        "name": "Circular tank detector"
    },
    {
        "id": "crowdai-road-density-esri",
        "name": "CrowdAI Road Density"
    },
    {
        "id": "crowdai-road-detector-esri",
        "name": "GBDX CrowdAI Road Detector"
    },
        ...
]
 
Suggest Edits

Retrieve a Recipe

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/recipeId

Path Params

recipeId
string
required

Unique identifier of the recipe.

Link reference in Example: AnswerFactory Recipe Reference Overview

Setup:
Request:
GET /answer-factory-recipe-service/api/recipe/:recipeId

Headers:
  Authorization: Bearer {token}
  Accept: application/json

Params:
  recipeId: the ID of the recipe to retrieve


Response (success):
200 OK

Body:
  {
   ... recipe definition: see AnswerFactory Recipe Reference Overview, linked in the docs section below example and results ...
  }


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/query-tweets
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "query-tweets",
  "name": "Query Tweets",
  "owner": "mchaudry",
  "accountId": null,
  "access": null,
  "description": "Tweets",
  "definition": "q=item_type:\\\"tweet\\\"",
  "recipeType": "vector-query",
  "inputType": "vector-service",
  "outputType": "vector-service",
  "parentRecipeId": null,
  "defaultDayRange": "1",
  "parameters": null,
  "validators": null,
  "prerequisites": null,
  "properties": {
    "query_index": "vector-sma-twitter*"
  }
}
 
Suggest Edits

Retrieve Listing of Recipes for Account

Retrieve a listing of recipes available to the current users account

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipes

Query Params

accountId
string

Identifier for account recipe is visible to; defaults to GBDX account the user making recipe creation request belongs to. An empty array means the recipe is public.

description
string

Explanation of what the recipe does.

id
string

Recipe's unique identifier.

inputType
string

Name of the input to the recipe.

name
string

The human-readable unique recipe identifier.

outputType
string

Name of the output to the recipe; determines how the result of the recipe will be displayed.

owner
string

The username of the user who created recipe; defaults to GBDX username of user making recipe creation request.

parameter
string
parentRecipeId
string

The id of the recipe to inherit non-overridden fields from.

prerequisite
string

Contains sub-parts that provide specifics on recipes that must run as precursors to this recipe.

propertyKey
string

Corresponds to the actual property.key value.

propertyValue
string

Corresponds to the actual porperty.key=value value.

recipeType
string

The type of recipe, ie vector-query or workflow.

version
string

Values may be true, false, or a number.

virtual
string

Values may be true or false. If virtual is not set, it will default to false.

Link reference in Example: AnswerFactory Recipe Reference Overview

The following Query Parameters may also be included to narrow down search results:

Parameter Description Accepts Wildcards?
accountId Identifier for account recipe is visible to; defaults to GBDX account the user making recipe creation request belongs to. An empty array means the recipe is public. No
description Explanation of what the recipe does. No
id Recipe's unique identifier. For example, query-tweets. No
inputType Name of the input to the recipe. For example, acquisition. No
name The human-readable unique recipe identifier. For example, Query Tweets. Yes
outputType Name of the output to the recipe; determines how the result of the recipe will be displayed. For example, vector-service. No
owner The username of the user who created recipe; defaults to GBDX username of user making recipe creation request. No
parameter Currently only recipe parameter name is searchable. No
parentRecipeId The id of the recipe to inherit non-overridden fields from. No
prerequisite Contains sub-parts that provide specifics on recipes that must run as precursors to this recipe. Currently, only the prerequisite id is filterable. No
propertyKey Corresponds to the actual property.key value. Example: propertyKey=image_bands. If only this is provided and not propertyValue, this will return recipes that have this property without caring about the property's value. Yes
propertyValue Corresponds to the actual porperty.key=value value. Example: propertyValue=Pan_MS1. This can be used without also querying on propertyKey. No, unless querying on the name propertyKey
recipeType The type of recipe, ie vector-query, workflow, etc. No
version Values may be true, false, or a number. By default, version is set to false during querying. To see all versions of a recipe, set version to true. No
virtual Values may be true or false. If virtual is not set, it will default to false. For example, if id=extract-protogen-lulc and version=true, you will get all versions of extract-protogen-lulc. No

Some things to be aware of when referring to recipes by id:

The latest version of a recipe is associated with the "base" recipe id; that is, the recipe id with no version attached. An example base recipe id, referring to the latest version of the recipe, would be: "id": "example-recipe". With the version attached: "id": "example-recipe:4.1.0".

Each time the recipe is updated, the base recipe id is also updated to refer to the newest version of the recipe. In addition, the recipe id is also updated with the latest version number. Previous versions of the recipe will still be available. To query on only a specific version of the recipe, use the recipe id with the specific version number appended. For example: "id": "example-recipe:2.0.0".

Note: The latest version of a recipe can also be called with its "versioned" recipe id. For example, if the recipe is on version 3.1.2: "id": "example-recipe" and "id": "example-recipe:3.1.2" will both refer to the same version, the latest version, of the recipe. However, to view only a past version of a recipe, the recipe must be referred to specifically with the versioned recipe id. For example: "id": "example-recipe:3.1.1". To view all versions of a recipe, query on the base recipe id and query version: true.

Setup:
Request:
GET /answer-factory-recipe-service/api/recipes

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  [
    {
     ... recipe definition: see AnswerFactory Recipe Reference Overview, linked in the docs section below example and results ...
    },
    {
     ... recipe definition: see AnswerFactory Recipe Reference Overview, linked in the docs section below example and results ...
    },
    ...
  ]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipes?name=roads*
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "id": "query-roads",
        "version": "1.0.0",
        "name": "Query Roads",
        ...
    },
    {
        "id": "road-tracker",
        "version": "1.0.0",
        "name": "Extract Roads",
        ...
    }
]
 
Suggest Edits

Send Recipe Suggestion

Send a suggestion for a new recipe/new algorithms.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://vector.geobigdata.io/answer-factory-recipe-service/api/feedback/new_recipe

Body Params

string
required
 
Setup:
Request:
POST /answer-factory-recipe-service/api/feedback/new_recipe

Headers:
  Authorization: Bearer {token}
  Accept: application/json

Body:
  {
   Description of desired recipe/algorithm and/or desired results.
  }

Response (success):
200 OK


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/feedback/new_recipe

Body:
  This is a suggestion for a new recipe.
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Update a Recipe with JSON Object

Update a recipe with JSON object for recipe definition

 
puthttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/json/recipeId

Path Params

recipeId
string
required

Unique identifier of the recipe.

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Link reference in Example: AnswerFactory Recipe Reference Overview

For this version of the recipe update API call, the recipe definition parameter must be a JSON object which the specified recipe type can understand. See Update a Recipe with JSON String for set up to support using a string for the recipe definition.

Note: The entire recipe needs to be included in the body. The difference between this endpoint and the JSON string endpoint is that this endpoint converts the recipe definition parameter to a string, which is useful for workflow recipes. For more details on JSON Object recipe specifications, see documents section for recipe creation.

Note: In most cases, when updating an Extraction (or workflow) recipe, use JSON Object. When updating a Query recipe, use JSON String.

Setup:
Request:
PUT /answer-factory-recipe-service/api/recipe/json/:recipeId

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Params:
  recipeId: the ID of the recipe to update

Body:
  {
   ... recipe definition: see AnswerFactory Recipe Reference Overview, linked in the docs section below example and results ...
  }


Response (success):
202 Accepted


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/json/test-workflow-recipe

Body:
{
        "id": "test-workflow-recipe",
        "name": "Test Workflow Recipe",
        "owner": "testuser",
        "description": "Updating the recipe, but without deciding version number here.",
        "recipeType": "workflow",
        "inputType": "vector-service",
        "outputType": "vector-service",
        "parameters": [
            {
                "name": "compare_with",
                "type": "string",
                "required": true,
                "description": "Compare With",
                "allowedValues": [
                    "next most recent",
                    "1 month",
                    "1 year"
                ],
                "allowMultiple": false
            }
        ],
        "prerequisites": [
            {
                "id": "extract-protogen-lulc:1.0.0",
                "aggregator": "PAIR_INTERSECTION",
                "operator": null,
                "properties": {}
            }
        ],
        "definition": "{\"tasks\":[{\"name\":\"compare\",\"taskType\":\"CompareVectors\",\"timeout\":36000,\"impersonation_allowed\":true,\"inputs\":[{\"name\":\"host\",\"value\":\"{vector_host}\"},{\"name\":\"query_a\",\"value\":\"{query_string_0}\"},{\"name\":\"query_b\",\"value\":\"{query_string_1}\"},{\"name\":\"index_a\",\"value\":\"{query_index_0}\"},{\"name\":\"index_b\",\"value\":\"{query_index_1}\"},{\"name\":\"wkt\",\"value\":\"{result_geometry}\"},{\"name\":\"group_by_fields\",\"value\":\"item_type\"},{\"name\":\"min_area\",\"value\":\"500\"}],\"outputs\":[{\"name\":\"data\"}]},{\"name\":\"vector\",\"taskType\":\"IngestShpToVectorServices\",\"timeout\":36000,\"impersonation_allowed\":true,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"items\",\"source\":\"compare:data\"},{\"name\":\"shapefileMapping\",\"value\":\"vector.crs=EPSG:4326\\nvector.ingestSource=Test Workflow 2\\nitem_type=item_type\"}],\"outputs\":[{\"name\":\"result\"}]},{\"name\":\"s3_vector\",\"taskType\":\"StageDataToS3\",\"timeout\":36000,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"data\",\"source\":\"vector:result\"},{\"name\":\"destination\",\"value\":\"s3://{vector_ingest_bucket}/{recipe_id}/{run_id}/{task_name}\"}],\"outputs\":[]}],\"name\":\"extract\"}"
    }
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "test-workflow-recipe:2.0.0",
    "version": "2.0.0",
    "name": "Test Workflow Recipe",
    "owner": "testuser",
    "accountId": null,
    "access": null,
    "description": "Updating the recipe, but without deciding version number here.",
    "recipeType": "workflow",
    "inputType": "vector-service",
    "outputType": "vector-service",
    "parentRecipeId": null,
    "virtual": null,
    "defaultDayRange": null,
    "parameters": [
        {
            "name": "compare_with",
            "type": "string",
            "required": true,
            "description": "Compare With",
            "allowedValues": [
                "next most recent",
                "1 month",
                "1 year"
            ],
            "allowMultiple": false
        }
    ],
    "validators": null,
    "prerequisites": [
        {
            "id": "extract-protogen-lulc:1.0.0",
            "aggregator": "PAIR_INTERSECTION",
            "operator": null,
            "properties": {}
        }
    ],
    "linkedTo": null,
    "properties": null,
    "definition": "{\"tasks\":[{\"name\":\"compare\",\"taskType\":\"CompareVectors\",\"timeout\":36000,\"impersonation_allowed\":true,\"inputs\":[{\"name\":\"host\",\"value\":\"{vector_host}\"},{\"name\":\"query_a\",\"value\":\"{query_string_0}\"},{\"name\":\"query_b\",\"value\":\"{query_string_1}\"},{\"name\":\"index_a\",\"value\":\"{query_index_0}\"},{\"name\":\"index_b\",\"value\":\"{query_index_1}\"},{\"name\":\"wkt\",\"value\":\"{result_geometry}\"},{\"name\":\"group_by_fields\",\"value\":\"item_type\"},{\"name\":\"min_area\",\"value\":\"500\"}],\"outputs\":[{\"name\":\"data\"}]},{\"name\":\"vector\",\"taskType\":\"IngestShpToVectorServices\",\"timeout\":36000,\"impersonation_allowed\":true,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"items\",\"source\":\"compare:data\"},{\"name\":\"shapefileMapping\",\"value\":\"vector.crs=EPSG:4326\\nvector.ingestSource=Test Workflow 2\\nitem_type=item_type\"}],\"outputs\":[{\"name\":\"result\"}]},{\"name\":\"s3_vector\",\"taskType\":\"StageDataToS3\",\"timeout\":36000,\"containerDescriptors\":[{\"properties\":{\"domain\":\"t2medium\"}}],\"inputs\":[{\"name\":\"data\",\"source\":\"vector:result\"},{\"name\":\"destination\",\"value\":\"s3://{vector_ingest_bucket}/{recipe_id}/{run_id}/{task_name}\"}],\"outputs\":[]}],\"name\":\"extract\"}"
}
 
Suggest Edits

Update a Recipe with JSON String

Update a recipe with JSON string for recipe definition

 
puthttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/recipeId

Path Params

recipeId
string
required

Unique identifier of the recipe.

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Link reference in Example: AnswerFactory Recipe Reference Overview

For this version of the recipe update API call, the recipe definition parameter must be a string which the specified recipe type can understand. See Update a Recipe with JSON Object for set up to support using a JSON object for the recipe definition.

Note: In most cases, when updating an Extraction (or workflow) recipe, use JSON Object. When updating a Query recipe, use JSON String.

Setup:
Request:
PUT /answer-factory-recipe-service/api/recipe/:recipeId

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Params:
  recipeId: the ID of the recipe to update

Body:
  {
   ... recipe definition: see AnswerFactory Recipe Reference Overview, linked in the docs section below example and results ...
  }


Response (success):
202 Accepted


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/test-recipe

Body:
{
  "id": "test-recipe",
  "name": "Test Recipe Take 2",
  "owner": "testuser",
  "accountId" : ["..."],
  "definition": "item_type:test",
  "description": "No need to include version; it's automatic.",
  "recipeType": "vector-query",
  "inputType": "vector-service",
  "outputType": "vector-service",
  "properties": {
    "query_index": "test-index"
  }
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "test-recipe:2.0.0",
    "version": "2.0.0",
    "name": "Test Recipe Take 2",
    "owner": "testuser",
    "accountId": [
        "..."
    ],
    "access": null,
    "description": "No need to include version; it's automatic.",
    "recipeType": "vector-query",
    "inputType": "vector-service",
    "outputType": "vector-service",
    "parentRecipeId": null,
    "virtual": null,
    "defaultDayRange": null,
    "parameters": null,
    "validators": null,
    "prerequisites": null,
    "linkedTo": null,
    "properties": {
        "query_index": "test-index"
    },
    "definition": "item_type:test"
}
 
Suggest Edits

Recipe Runner Blueprints

Get the list of blueprints for the automated recipe builder.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/blueprint
 
Setup:
Request:
GET /answer-factory-recipe-service/api/blueprint

Headers:
  Authorization: Bearer {token}

Response (success):
200 OK


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/blueprint
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "runner": {
            "key": "partitioned-workflow.acquisition.vector-service",
            "name": "Acquisition to Vector Service Partitioned Workflow",
            "description": null
        },
        "inputType": {
            "key": "acquisition",
            "name": "Acquisitions",
            "description": null
        },
        "outputType": {
            "key": "vector-service",
            "name": "Vectors",
            "description": null
        },
        "recipeType": {
            "key": "partitioned-workflow",
            "name": "Parallelized GBDX Workflow ",
            "description": null
        },
        "parameters": [
            {
                "key": "recipe_name",
                "name": "Recipe Name",
                "description": "The text that identifies the recipe.",
                "required": true,
                "allowedValues": null
            },
            {
                "key": "workflow_id",
                "name": "Workflow ID",
                "description": "The ID of the GBDX Workflow to build the recipe from.",
                "required": true,
                "allowedValues": null
            },
            {
                "key": "acquisition_types",
                "name": "Acquisition Type",
                "description": "The type of acquisitions the recipe should be run on. Defaults to 'DigitalGlobeAcquisition'",
                "required": false,
                "allowedValues": [
                    "",
                    "DigitalGlobeAcquisition",
                    "LandsatAcquisition"
                ]
            },
            {
                "key": "minimum_bands",
                "name": "Minimum Number Of Bands",
                "description": "The minimum number of bands the input image is required to have.",
                "required": false,
                "allowedValues": [
                    "",
                    "1",
                    "4",
                    "8"
                ]
            },
            {
                "key": "vector_type",
                "name": "Vector Type",
                "description": "The type of vectors to ingest into GBDX VectorServices.",
                "required": true,
                "allowedValues": [
                    "",
                    "GeoJSON",
                    "Shapefile",
                    "VectorServices Item JSON"
                ]
            },
            {
                "key": "vector_item_type",
                "name": "Vector Item Type",
                "description": "The value to set item_type to in each individual vector when storing in GBDX VectorServices.",
                "required": false,
                "allowedValues": null
            },
            {
                "key": "partition_size",
                "name": "Partition Size",
                "description": "The size, in km squared, to partition the input acquisition into.",
                "required": false,
                "allowedValues": null
            }
        ]
    },
    ...
  ]
 
Suggest Edits

Recipe Runner Blueprint Build

Run the automated recipe builder based on a selected blueprint.

 
posthttps://vector.geobigdata.io/answer-factory-recipe-service/api/blueprint/build

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Setup:
Request:
POST /answer-factory-recipe-service/api/blueprint/build

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Body:
  {
   ... recipe blueprint information ...
  }

Response (success):
200 OK


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/blueprint/build

Body:
{
    "recipe_name": "asdfsadfsdf",
    "workflow_id": "4542624746854993621",
    "minimum_bands": "4",
    "runner": "partitioned-workflow.acquisition.vector-service",
    "vector_type": "GeoJSON",
    "acquisition_types": "DigitalGlobeAcquisition"
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "asdfsadfsdf",
    "name": "asdfsadfsdf",
    "description": "asdfsadfsdf",
    "recipeType": "partitioned-workflow",
    "inputType": "acquisition",
    "outputType": "vector-service",
    "properties": {
        "image_bands": "Pan_MS1"
    },
    "definition": {
        "name": "asdfsadfsdf",
        "tasks": [
            {
                "name": "mrf",
                "taskType": "OptimizeRastersMrf:0.0.4",
                "timeout": 36000,
                "impersonation_allowed": true,
                "containerDescriptors": [],
                "inputs": [
                    {
                        "name": "hash_key",
                        "value": "dgtest"
                    },
                    {
                        "name": "s3_output_key",
                        "value": "1040010021221A00"
                    },
                    {
                        "name": "data",
                        "value": "{raster_path}"
                    }
                ],
                "outputs": [
                    {
                        "name": "results"
                    },
                    {
                        "name": "log"
                    }
                ]
            },
            {
                "name": "features",
                "taskType": "MrfFeatureService:0.0.8",
                "timeout": 36000,
                "impersonation_allowed": true,
                "containerDescriptors": [],
                "inputs": [
                    {
                        "name": "user_service_title",
                        "value": "1040010021221A00"
                    },
                    {
                        "name": "imdpath_prefix",
                        "value": "http://d5b17589-24c0-4178-a6fe-f82bac8b7b9a.s3.amazonaws.com/1040010021221A00/"
                    },
                    {
                        "name": "catid",
                        "value": "1040010021221A00"
                    },
                    {
                        "name": "referer",
                        "value": "digitalglobe.maps.arcgis.com"
                    },
                    {
                        "name": "token_url",
                        "value": "https://www.arcgis.com/sharing/rest/generateToken"
                    },
                    {
                        "name": "username",
                        "value": "Mohammad.Chaudry_digitalglobe"
                    },
                    {
                        "name": "token",
                        "value": "xaoYqMkH-S1QhplaItu3HkVEczh65jU4pFzMyfmwV0eeTRUwMP5WWHcB4o_r0L318mOxsbzh4HSo49XkLp2RLCzAq1bl6zpEv3PlwJfrr4SfdnUet8Gs08j4_yg6DN6uTZphYTWAkXnsNVzGKgR5wduEpDSfUIsIENm316UaTxU."
                    },
                    {
                        "name": "mrf",
                        "source": "mrf:results"
                    }
                ],
                "outputs": [
                    {
                        "name": "data"
                    }
                ]
            },
            {
                "name": "s3_mrf",
                "taskType": "StageDataToS3:0.0.1",
                "timeout": 7200,
                "impersonation_allowed": true,
                "containerDescriptors": [],
                "inputs": [
                    {
                        "name": "destination",
                        "value": "s3://d5b17589-24c0-4178-a6fe-f82bac8b7b9a/or2a_1040010021221A00"
                    },
                    {
                        "name": "data",
                        "source": "mrf:results"
                    }
                ],
                "outputs": []
            },
            {
                "name": "ingest_features",
                "taskType": "IngestGeoJsonToVectorServices",
                "timeout": 36000,
                "impersonation_allowed": true,
                "containerDescriptors": [],
                "inputs": [
                    {
                        "name": "items",
                        "source": "features:data"
                    },
                    {
                        "name": "index",
                        "value": "vector-asdfsadfsdf-{ingest_date}"
                    },
                    {
                        "name": "mapping",
                        "value": "vector.crs=EPSG:4326\nvector.ingestSource=asdfsadfsdf\nvector.itemType=unknown"
                    }
                ],
                "outputs": [
                    {
                        "name": "result"
                    }
                ]
            },
            {
                "name": "stage_ingest_features",
                "taskType": "StageDataToS3",
                "containerDescriptors": [],
                "inputs": [
                    {
                        "name": "data",
                        "source": "ingest_features:result"
                    },
                    {
                        "name": "destination",
                        "value": "s3://{vector_ingest_bucket}/{recipe_id}/{run_id}/{task_name}"
                    }
                ],
                "outputs": []
            }
        ]
    }
}
 
Suggest Edits

AnswerFactory Answer Reference Overview

Overview of the AnswerFactory Answer API

 
Table of Contents
AnswerFactory Answer API Parameters
Associated API Calls for AnswerFactory Answers

Answer API Parameters

Parameter Data Type Parameter Type Description Required?
columnId String Path The column identification in the table of the vector item. Required
projectId String Path The ID of the project. Note: ID, not name. Required
recipeId String Path The ID of the recipe. Note: ID, not name. Required
rowId String Path The row identification in the table of the vector item. This is the AOI name. Required
x String Path The TMS x value. Required
y String Path The TMS y value. Required
z String Path The TMS z value. Required

Associated API Calls for AnswerFactory Answers

Retrieve Answer
Retrieve Answer Fully
Retrieve Answer IDAHO Images
Retrieve Answer Status
Retrieve Answer Status v2
Retrieve Answer Table
Retrieve Answer TMS
Retrieve Results

 
Suggest Edits

Retrieve Answer

The response for this endpoint is usually limited to a certain number of answers (like to 1000 vectors for vector answers) to not overload user interfaces. To get full answers use the Retrieve Answer Fully endpoint.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/answer/cell/projectId/recipeId/rowId/columnId

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

Unique identifier of the recipe.

rowId
string
required

The row identification in the table.

columnId
string
required

The column identification in the table.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/answer/cell/:projectId/:recipeId/:rowId/:columnId

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column
  field: optional value to filter table by

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  {
   ... recipe specific response (typically vectors) ...
  }


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/answer/cell/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/US%20Naval%20Research/e3b96bb1-f174-4597-bc54-21f73bcbd5db
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-77.0197560196733,38.819685392705374],[-77.01889258911089,38.81970032235374],[-77.01887350945644,38.81902485206216],[-77.01973693187246,38.81900992277185],[-77.0197560196733,38.819685392705374]]]},"properties":{"ingest_source":"ObjectDetection","access":{"groups":["_ALL_"],"users":["_ALL_"]},"item_date":"2010-01-27T16:22:25Z","original_crs":"EPSG:4326","item_type":["Airliner"],"format":null,"ingest_date":"2017-05-05T19:20:22Z","source":"OpenSkyNet","name":"/mnt/work/input/data/055335250010_01/055335250010_01_assembly.tif","attributes":{"models":["0ad8b06182088000.zip"],"item_date":"2010-01-27T16:22:25Z","model_StorageTank_dbl":0.014805547,"cat_id_raw":"1030010003A3D500","model_Airliner_dbl":0.93836534,"best_Airliner_dbl":0.93836534,"acquisition_date":"2010-01-27T16:22:25Z","best_StorageTank_dbl":0.014805547,"model_TransportSys_dbl":0.0355906598,"cat_id":"1030010003A3D500","acquisition_id_raw":"1030010003A3D500","best_TransportSys_dbl":0.0355906598,"sat_id":"WV02"},"ingest_attributes":{"recipe_id_raw":"openskynet-aircraft-detection","project_id_raw":"ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc","run_id_raw":"461e2767-74b6-4f6e-a72d-34c8ff89697b"},"id":"aadea006-02a5-4578-96ca-f5352ac4a540","text":"StorageTank Airliner TransportSys"}},{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-77.02528706418965,38.81976981665584],[-77.02442363555772,38.8197847872077],[-77.0244045035957,38.81910931923333],[-77.02526792408135,38.819094349040505],[-77.02528706418965,38.81976981665584]]]},"properties":{"ingest_source":"ObjectDetection","access":{"groups":["_ALL_"],"users":["_ALL_"]},"item_date":"2010-01-27T16:22:25Z","original_crs":"EPSG:4326","item_type":["Helicopter"],"format":null,"ingest_date":"2017-05-05T19:20:22Z","source":"OpenSkyNet","name":"/mnt/work/input/data/055335250010_01/055335250010_01_assembly.tif","attributes":{"models":["0ad8b06182088000.zip"],"best_Helicopter_dbl":0.808356583,"item_date":"2010-01-27T16:22:25Z","cat_id_raw":"1030010003A3D500","cat_id":"1030010003A3D500","model_Helicopter_dbl":0.808356583,"acquisition_id_raw":"1030010003A3D500","best_TransportSys_dbl":0.183288023,"sat_id":"WV02","acquisition_date":"2010-01-27T16:22:25Z","model_TransportSys_dbl":0.183288023},"ingest_attributes":{"recipe_id_raw":"openskynet-aircraft-detection","project_id_raw":"ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc","run_id_raw":"461e2767-74b6-4f6e-a72d-34c8ff89697b"},"id":"e83a5bcc-e424-4906-9e75-c0f604d8f6ec","text":"Helicopter TransportSys"}},{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-77.02526664809696,38.8190493178631],[-77.02440322815438,38.81906428803198],[-77.02438409687696,38.818388819965605],[-77.02524750867352,38.81837385015575],[-77.02526664809696,38.8190493178631]]]},"properties":{"ingest_source":"ObjectDetection","access":{"groups":["_ALL_"],"users":["_ALL_"]},"item_date":"2010-01-27T16:22:25Z","original_crs":"EPSG:4326","item_type":["Helicopter"],"format":null,"ingest_date":"2017-05-05T19:20:22Z","source":"OpenSkyNet","name":"/mnt/work/input/data/055335250010_01/055335250010_01_assembly.tif","attributes":{"best_Background-AOI1_dbl":0.0466706008,"models":["0ad8b06182088000.zip"],"best_Helicopter_dbl":0.574199378,"item_date":"2010-01-27T16:22:25Z","model_StorageTank_dbl":0.257469922,"cat_id_raw":"1030010003A3D500","model_Airliner_dbl":0.0310860313,"best_Airliner_dbl":0.0310860313,"model_Background-AOI1_dbl":0.0466706008,"acquisition_date":"2010-01-27T16:22:25Z","best_StorageTank_dbl":0.257469922,"model_TransportSys_dbl":0.0893141031,"cat_id":"1030010003A3D500","model_Helicopter_dbl":0.574199378,"acquisition_id_raw":"1030010003A3D500","best_TransportSys_dbl":0.0893141031,"sat_id":"WV02"},"ingest_attributes":{"recipe_id_raw":"openskynet-aircraft-detection","project_id_raw":"ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc","run_id_raw":"461e2767-74b6-4f6e-a72d-34c8ff89697b"},"id":"384add84-fb33-4ba5-b857-b0d9863d8290","text":"Background-AOI1 Helicopter Airliner StorageTank TransportSys"}}]
 
Suggest Edits

Retrieve Answer Fully

The response for this endpoint will return all answers and could potentially overload user interfaces. To get a limited set of answers use the Retrieve Answer endpoint.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/answer/entire/cell/projectId/recipeId/rowId/columnId

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

Unique identifier of the recipe.

rowId
string
required

The row identification in the table.

columnId
string
required

The column identification in the table.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/answer/entire/cell/:projectId/:recipeId/:rowId/:columnId

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column
  field: optional value to filter table by

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  {
   ... recipe specific response (typically vectors) ...
  }


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/answer/entire/cell/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/US%20Naval%20Research/e3b96bb1-f174-4597-bc54-21f73bcbd5db
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"type": "FeatureCollection",
"features": [{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-77.0197560196733,38.819685392705374],[-77.01889258911089,38.81970032235374],[-77.01887350945644,38.81902485206216],[-77.01973693187246,38.81900992277185],[-77.0197560196733,38.819685392705374]]]},"properties":{"ingest_source":"ObjectDetection","access":{"groups":["_ALL_"],"users":["_ALL_"]},"item_date":"2010-01-27T16:22:25Z","original_crs":"EPSG:4326","item_type":["Airliner"],"format":null,"ingest_date":"2017-05-05T19:20:22Z","source":"OpenSkyNet","name":"/mnt/work/input/data/055335250010_01/055335250010_01_assembly.tif","attributes":{"models":["0ad8b06182088000.zip"],"item_date":"2010-01-27T16:22:25Z","model_StorageTank_dbl":0.014805547,"cat_id_raw":"1030010003A3D500","model_Airliner_dbl":0.93836534,"best_Airliner_dbl":0.93836534,"acquisition_date":"2010-01-27T16:22:25Z","best_StorageTank_dbl":0.014805547,"model_TransportSys_dbl":0.0355906598,"cat_id":"1030010003A3D500","acquisition_id_raw":"1030010003A3D500","best_TransportSys_dbl":0.0355906598,"sat_id":"WV02"},"ingest_attributes":{"recipe_id_raw":"openskynet-aircraft-detection","project_id_raw":"ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc","run_id_raw":"461e2767-74b6-4f6e-a72d-34c8ff89697b"},"id":"aadea006-02a5-4578-96ca-f5352ac4a540","text":"StorageTank Airliner TransportSys"}},
{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-77.02528706418965,38.81976981665584],[-77.02442363555772,38.8197847872077],[-77.0244045035957,38.81910931923333],[-77.02526792408135,38.819094349040505],[-77.02528706418965,38.81976981665584]]]},"properties":{"ingest_source":"ObjectDetection","access":{"groups":["_ALL_"],"users":["_ALL_"]},"item_date":"2010-01-27T16:22:25Z","original_crs":"EPSG:4326","item_type":["Helicopter"],"format":null,"ingest_date":"2017-05-05T19:20:22Z","source":"OpenSkyNet","name":"/mnt/work/input/data/055335250010_01/055335250010_01_assembly.tif","attributes":{"models":["0ad8b06182088000.zip"],"best_Helicopter_dbl":0.808356583,"item_date":"2010-01-27T16:22:25Z","cat_id_raw":"1030010003A3D500","cat_id":"1030010003A3D500","model_Helicopter_dbl":0.808356583,"acquisition_id_raw":"1030010003A3D500","best_TransportSys_dbl":0.183288023,"sat_id":"WV02","acquisition_date":"2010-01-27T16:22:25Z","model_TransportSys_dbl":0.183288023},"ingest_attributes":{"recipe_id_raw":"openskynet-aircraft-detection","project_id_raw":"ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc","run_id_raw":"461e2767-74b6-4f6e-a72d-34c8ff89697b"},"id":"e83a5bcc-e424-4906-9e75-c0f604d8f6ec","text":"Helicopter TransportSys"}},
{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-77.02526664809696,38.8190493178631],[-77.02440322815438,38.81906428803198],[-77.02438409687696,38.818388819965605],[-77.02524750867352,38.81837385015575],[-77.02526664809696,38.8190493178631]]]},"properties":{"ingest_source":"ObjectDetection","access":{"groups":["_ALL_"],"users":["_ALL_"]},"item_date":"2010-01-27T16:22:25Z","original_crs":"EPSG:4326","item_type":["Helicopter"],"format":null,"ingest_date":"2017-05-05T19:20:22Z","source":"OpenSkyNet","name":"/mnt/work/input/data/055335250010_01/055335250010_01_assembly.tif","attributes":{"best_Background-AOI1_dbl":0.0466706008,"models":["0ad8b06182088000.zip"],"best_Helicopter_dbl":0.574199378,"item_date":"2010-01-27T16:22:25Z","model_StorageTank_dbl":0.257469922,"cat_id_raw":"1030010003A3D500","model_Airliner_dbl":0.0310860313,"best_Airliner_dbl":0.0310860313,"model_Background-AOI1_dbl":0.0466706008,"acquisition_date":"2010-01-27T16:22:25Z","best_StorageTank_dbl":0.257469922,"model_TransportSys_dbl":0.0893141031,"cat_id":"1030010003A3D500","model_Helicopter_dbl":0.574199378,"acquisition_id_raw":"1030010003A3D500","best_TransportSys_dbl":0.0893141031,"sat_id":"WV02"},"ingest_attributes":{"recipe_id_raw":"openskynet-aircraft-detection","project_id_raw":"ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc","run_id_raw":"461e2767-74b6-4f6e-a72d-34c8ff89697b"},"id":"384add84-fb33-4ba5-b857-b0d9863d8290","text":"Background-AOI1 Helicopter Airliner StorageTank TransportSys"}}]
}
 
Suggest Edits

Retrieve Answer IDAHO Images

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/answer/cell/projectId/recipeId/rowId/columnId/idahoImages

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

The ID of the recipe.

rowId
string
required

The row identification in the table.

columnId
string
required

The column identification in the table.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/answer/cell/:projectId/:recipeId/:rowId/:columnId/idahoImages

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  [
    {
      "id": "identifier for idaho image",
      "bucket": "amazon s3 bucket that contains idaho image",
      "acquisitionId": "unique identifier of source image",
      "timestamp": /* source image timestamp in millis from epoch format */
    },
    {
      ...
    }
  ]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/answer/cell/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/US%20Naval%20Research/e3b96bb1-f174-4597-bc54-21f73bcbd5db/idahoImages
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "id": "d568b986-c7b7-4fee-b40c-0edfb7ae6056",
    "bucket": "idaho-images",
    "acquisitionId": "1030010003A3D500",
    "productOrderId": null,
    "timestamp": 1264609345565,
    "cloudCover": null,
    "sensorName": null,
    "bounds": null
  }
]
 
Suggest Edits

Retrieve Answer Status

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/status/projectId

Path Params

projectId
string
required

The ID of the project.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/recipe/status/:projectId

Params:
  projectId: the ID of the project

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  [
    {
      "recipeId": "id of recipe 1",
      "recipeName": "name of recipe 1",
      "status": "state of entire answer; possible values: pending, submitted, running, success, failed",
      "displayAs": "how this answer can be viewed; possible values: vector",
      "resultStatuses": [
        {
          "resultId": "identifier of result 1",
          "runDate": /* timestamp in millis from epoch format when result when submitted */,
          "status": "state of this result; possible values: pending, submitted, running, success, failed",
          "statusDescription": "recipe specific explanation of current state",
          "progressValue": /* optional integer of current progress */,
          "progressMax": /* optional integer of maximum progress */
        },
        {
          "..."
        }
      ],
      "prereqAnswerStatuses": [
        {
          "recipeId": "id of prerequisite recipe 1",
          "recipeName": "name of prerequisite recipe 1",
          "status": "tate of this prerequisite answer; possible values: pending, submitted, running, success, failed",
          "displayAs": "how this prerequisite answer can be viewed; possible values: vector",
          "resultStatuses": [
            {
              "resultId": "identifier of prerequisite result 1",
              "runDate": /* timestamp in millis from epoch format when result when submitted */,
              "status": "state of this prerequisite result; possible values: pending, submitted, running, success, failed",
              "statusDescription": "recipe specific explanation of current state",
              "progressValue": /* optional integer of current progress */,
              "progressMax": /* optional integer of maximum progress */
            },
            {
              ...
            }
          ],
          "prereqAnswerStatuses": ...
        },
        {
          ...
        }
      ]
    },
    {
      ...
    }
  ]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/status/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "recipeId": "openskynet-aircraft-detection",
    "recipeName": "Extract Aircraft",
    "status": "success",
    "displayAs": "vector",
    "resultStatuses": [
      {
        "resultId": "b9119f41-af1d-4cb2-8f21-7d700ef648f2",
        "runDate": 1494007969816,
        "status": "success",
        "statusDescription": "Workflow complete.",
        "progressValue": 5,
        "progressMax": 5
      },
      {
        "resultId": "25a76c38-0464-459a-8290-3550c2afad61",
        "runDate": 1494007968794,
        "status": "success",
        "statusDescription": "Workflow complete.",
        "progressValue": 5,
        "progressMax": 5
      }
    ],
    "prereqAnswerStatuses": null
  },
  ...
]
 
Suggest Edits

Retrieve Answer Status v2

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/status/v2/projectId

Path Params

projectId
string
required

The ID of the project.

Answer Status v2 includes useful additional information, such as the successCount, failedCount, and totalCount, to better track recipe and project progression.

Setup:
Request:
GET /answer-factory-recipe-service/api/recipe/status/v2/:projectId

Params:
  projectId: the ID of the project

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  [
    {
      "recipeId": "id of recipe 1",
      "recipeName": "name of recipe 1",
      "status": "state of entire answer; possible values: pending, submitted, running, success, failed",
      "successCount": "integer number of recipe run over selected acquisitions successfully completed",
      "failedCount": "integer number of recipe run over selected acquisitions that failed to complete successfully",
      "totalCount": "integer number of selected acquisitions for recipe to run against",
      "displayAs": "how this answer can be viewed; possible values: vector",
      "resultStatuses": [
        {
          "resultId": "identifier of result 1",
          "runDate": /* timestamp in millis from epoch format when result when submitted */,
          "processingId": "GBDX workflow id",
          "status": "state of this result; possible values: pending, submitted, running, success, failed",
          "statusDescription": "recipe specific explanation of current state",
          "progressValue": /* optional integer of current progress */,
          "progressMax": /* optional integer of maximum progress */
        },
        {
          "..."
        }
      ],
      "prereqAnswerStatuses": [
        {
          "recipeId": "id of prerequisite recipe 1",
          "recipeName": "name of prerequisite recipe 1",
          "status": "tate of this prerequisite answer; possible values: pending, submitted, running, success, failed",
          "successCount": "integer number of recipe run over selected acquisitions successfully completed",
          "failedCount": "integer number of recipe run over selected acquisitions that failed to complete successfully",
          "displayAs": "how this prerequisite answer can be viewed; possible values: vector",
          "resultStatuses": [
            {
              "resultId": "identifier of prerequisite result 1",
              "runDate": /* timestamp in millis from epoch format when result when submitted */,
              "processingId": "GBDX workflow id",
              "status": "state of this prerequisite result; possible values: pending, submitted, running, success, failed",
              "statusDescription": "recipe specific explanation of current state",
              "progressValue": /* optional integer of current progress */,
              "progressMax": /* optional integer of maximum progress */
            },
            {
              ...
            }
          ],
          "prereqAnswerStatuses": ...
        },
        {
          ...
        }
      ]
    },
    {
      ...
    }
  ]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/recipe/status/v2/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "recipeId": "extract-protogen-lulc-change",
        "recipeName": "Extract Protogen LULC Change",
        "status": "success",
        "successCount": 1,
        "failedCount": 0,
        "totalCount": 1,
        "displayAs": "vector",
        "resultStatuses": [
            {
                "resultId": "4f3939ba-5e64-4b12-b8e1-1a26e22c9bde",
                "runDate": 1507054966761,
                "processingId": "4700574668138406431",
                "status": "success",
                "statusDescription": "Workflow complete.",
                "progressValue": 3,
                "progressMax": 3
            }
        ],
        "prereqAnswerStatuses": [
            {
                "recipeId": "extract-protogen-lulc",
                "recipeName": "Extract Land Use Land Cover Protogen",
                "status": "success",
                "successCount": 2,
                "failedCount": 0,
                "totalCount": 2,
                "displayAs": "vector",
                "resultStatuses": [
                    {
                        "resultId": "2e28b9ca-68ec-4669-bee1-5ae358e3a780",
                        "runDate": 1507051459958,
                        "processingId": "4700545249742918459",
                        "status": "success",
                        "statusDescription": "Workflow complete.",
                        "progressValue": 9,
                        "progressMax": 9
                    },
                    {
                        "resultId": "0c600871-15e6-4031-bbe9-5266363c3e34",
                        "runDate": 1507051458977,
                        "processingId": "4700545242188353270",
                        "status": "success",
                        "statusDescription": "Workflow complete.",
                        "progressValue": 9,
                        "progressMax": 9
                    }
                ],
                "prereqAnswerStatuses": null
            }
        ]
    },
    ...
]
 
Suggest Edits

Retrieve Answer Table

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/answer/table/projectId/recipeId

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

The ID of the recipe.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/answer/table/:projectId/:recipeId

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  field: optional value to filter table by

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  {
    "rows": [
      {
        "id": "area of interest 1 identifier",
        "name": "area of interest 1 name",
        "cells": [
          {
            "columnId": "result 1 identifier",
            "columnName": "typically a date in one of the following formats: yyyy-MM-dd, yyyy-MM, yyyy, yyyy quarter (ex: 2016 Q2)",
            "columnSortName": "value to sort columns on to get natural order",
            "values": {
              "imagePercentage": /* decimal value 0-1 of percentage of area of interest the source image covers */,
              "areaPercentage": /* decimal value 0-1 of percentage of area of interest the result covers */,
              "count": /* number of result items (ex: number of vectors) */
            }
          },
          {
            "..."
          }
        ]
      },
      {
        "..."
      }
    ],
    "field": "current field filtering by; defaults to 'Total'",
    "availableFields": [
      "field value 1",
      "field value 2",
      "..."
    ],
    "displayCellsAs": "how this result can be viewed; possible values: vector"
  }


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/answer/table/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "rows": [
    {
      "id": "DCA Apron",
      "name": "DCA Apron",
      "cells": [
        {
          "columnId": "b9119f41-af1d-4cb2-8f21-7d700ef648f2",
          "columnName": "2010-01-27",
          "columnSortName": "2010-01-27T00:00:00.000Z",
          "values": {
            "area": 0.071674013968932,
            "imagePercentage": 1,
            "areaPercentage": 0.416731033345738,
            "count": 13
          }
        },
        {
          "columnId": "25a76c38-0464-459a-8290-3550c2afad61",
          "columnName": "2016-05-31",
          "columnSortName": "2016-05-31T00:00:00.000Z",
          "values": {
            "area": 0.0337527304957916,
            "imagePercentage": 1,
            "areaPercentage": 0.19624700053562563,
            "count": 6
          }
        }
      ]
    },
    ...
  ],
  "field": "Total",
  "availableFields": [
    "Airliner",
    "Helicopter",
    "Total"
  ],
  "displayCellsAs": "vector"
}
 
Suggest Edits

Retrieve Answer TMS

WARNING: EXPERIMENTAL. The response for this endpoint will return answer as a TMS service. To stream the answer in a different format use one of the other Answer endpoints listed.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/answer/cell/projectId/recipeId/rowId/columnId/z/x/y

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

Unique identifier of the recipe.

rowId
string
required

The row identification in the table.

columnId
string
required

The column identification in the table.

z
string
required

The z value of the TMS.

x
string
required

The x value of the TMS.

y
string
required

The y value of the TMS.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/answer/cell/:projectId/:recipeId/:rowId/:columnId/:z/:x/:y

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column
  z: TMS z value
  x: TMS x value
  y: TMS y value
  field: optional value to filter table by

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  {
   ... recipe specific TMS response ...
  }


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/answer/cell/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/DCA%20Apron/b9119f41-af1d-4cb2-8f21-7d700ef648f2/14/4686/10114
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"type":"FeatureCollection","features":[]}
 
Suggest Edits

Retrieve Results

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/result

Query Params

accountId
string

The account identifier.

acquisitionId
string

The catalog ID.

id
string

The column ID.

processingId
string

The GBDX workflow ID.

projectId
string

The ID of the project.

recipeId
string

The ID of the recipe. For instance, extract-aircraft.

rootRecipeId
string

The ID of the root recipe. For instance, if recipeId is extract-aircraft-change, rootRecipeId would be extract-aircraft. If recipeId is extract-aircraft, the rootRecipeId would also be extract-aircraft.

status
string

The status of the result; possible values: pending, submitted, running, success, failed.

fields
string

A comma delimited list of fields to return. By default, all fields are returned, but user may specify only certain fields.

Without optional query parameters included, this endpoint queries and returns all results associated with the user's account. All query parameters can be used, separately or in combination, to filter the returns of this endpoint.

Setup:
Request:
GET /answer-factory-recipe-service/api/result?optional_query_param(s)

Params:
  accountId: the ID of the account
  acquisitionId: the ID of the catalog item
  id: the column ID
  processingId : the GBDX workflow ID
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rootRecipeId: the ID of the root recipe
  status: the status of the answer results
  fields: comma delimited list of fields to return; by default, all fields returned

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  [
    {
        "id": "column id",
        "projectId": "project id",
        "owner": "user who submitted project",
        "accountId": "account id of user who submitted project",
        "recipeId": "identifier for recipe 1",
        "recipeName": "name of recipe 1",
        "rootRecipeId": "identifier of root recipe 1; can be identical to recipeId",
        "runDate": /* timestamp in millis from epoch format when result submitted */,
        "completeDate": /* timestamp in millis from epoch format when result completes */,
        "processingId": "GBDX workflow id 1",
        "status": "state of this result; possible values: pending, submitted, running, success, failed",
        "statusDescription": "recipe specific explanation of current state",
        "resultType": "type of return; possible values: vector-service",
        "displayAs": "how this answer can be viewed; possible values: vector",
        "resultDate": [
            /* timestamp in millis from epoch format of result; associated with acquisition timestamp */
        ],
        "acquisitionIds": [
            "catalog identifier 1", "catalog identifier 2", ...
        ],
        "idahoImages": [
            {
                "id": "idaho image id",
                "bucket": "s3 bucket idaho images are found in",
                "acquisitionId": "acquisition id",
                "catalogId": "catalog id",
                "productOrderId": null,
                "timestamp": /* timestamp in millis from epoch format of when catalog image was aquired */,
                "cloudCover": /* double value, percent of catalog image hidden by clouds /*,
                "sensorName": null,
                "bounds": null
            }
        ],
        "geom": {
            "type": "Polygon",
            "coordinates": [
                    ...
            ]
        },
        "properties": {
            "query_index": "index(es) results are found under",
            "query_string": "query to return the results"
        },
        "tableResults": [
            {
                "rowId": "row name 1",
                "columnId": "identifier of column 1",
                "values": [
                    {
                        "field": "the item_type of the result",
                        "values": {
                            "area": /* float value, SqKm of aoi /*,
                            "imagePercentage": /* float value, percent of aoi covered by selected images /*,
                            "areaPercentage": /* float value, percent of aoi covered by result vectors /*,
                            "count": /* integer value, number of results returned /*,
                            "length": /* double value, results that include linestring vectors, the total length of the linestrings /*
                        }
                    },
                    {
                        "field": ...,
                    },
                    ...
                    {
                        "field": ...,
                    }
                ]
            }
        ]
    },
    ...
]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/result?projectId=9523b75c-41e9-4a26-b580-aae6260e988b
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "id": "0c7b5104-b4a6-4860-a293-81ff0a7d4eca",
        "projectId": "9523b75c-41e9-4a26-b580-aae6260e988b",
        "owner": "an...",
        "accountId": "c8f...",
        "recipeId": "query-lulc-protogen",
        "recipeName": "Query LULC (Protogen)",
        "rootRecipeId": "query-lulc-protogen",
        "runDate": 1508244213032,
        "completeDate": 1508244213032,
        "processingId": null,
        "status": "success",
        "statusDescription": null,
        "resultType": "vector-service",
        "displayAs": "vector",
        "resultDate": [
            1502014526134
        ],
        "acquisitionIds": [
            "103001006E26CD00"
        ],
        "idahoImages": [
            {
                "id": "81fc7bba-58a9-4bb8-9ecc-21597d80f959",
                "bucket": "idaho-images",
                "acquisitionId": "103001006E26CD00",
                "catalogId": "103001006E26CD00",
                "productOrderId": null,
                "timestamp": 1502014526134,
                "cloudCover": null,
                "sensorName": null,
                "bounds": null
            }
        ],
        "geom": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        12.208471,
                        41.745829
                    ],
                    [
                        12.208471,
                        41.817385
                    ],
                    [
                        12.290354,
                        41.817385
                    ],
                    [
                        12.290354,
                        41.745829
                    ],
                    [
                        12.208471,
                        41.745829
                    ]
                ]
            ]
        },
        "properties": {
            "query_index": "vector-workflow*,vector-protogen-lulc*",
            "query_string": "(ingest_source:\\\"Protogen\\\") AND item_date:[2016-12-01T13:40:32.293Z TO 2017-10-17T12:41:32.293Z] AND ( attributes.cat_id_raw:103001006E26CD00 OR attributes.acquisition_id_raw:103001006E26CD00 OR attributes.acquisition_id_0_raw:103001006E26CD00 )"
        },
        "tableResults": [
            {
                "rowId": "AOI001",
                "columnId": "0c7b5104-b4a6-4860-a293-81ff0a7d4eca",
                "values": [
                    {
                        "field": "Soil",
                        "values": {
                            "area": 0.43441868885728674,
                            "imagePercentage": 1,
                            "areaPercentage": 0.01361282666251095,
                            "count": 195,
                            "length": 0
                        }
                    },
                    {
                        "field": "Water",
                        "values": {
                            "area": 0.19642033168391648,
                            "imagePercentage": 1,
                            "areaPercentage": 0.006154974444675558,
                            "count": 24,
                            "length": 0
                        }
                    },
                    {
                        "field": "BuiltUpArea",
                        "values": {
                            "area": 3.6163624328466555,
                            "imagePercentage": 1,
                            "areaPercentage": 0.11332135612455287,
                            "count": 18,
                            "length": 0
                        }
                    },
                    {
                        "field": "Vegetation",
                        "values": {
                            "area": 0.0009595263034935165,
                            "imagePercentage": 1,
                            "areaPercentage": 0.000030067457000838514,
                            "count": 2,
                            "length": 0
                        }
                    },
                    {
                        "field": "Total",
                        "values": {
                            "area": 4.2481609796913515,
                            "imagePercentage": 1,
                            "areaPercentage": 0.1331192246887402,
                            "count": 239,
                            "length": 0
                        }
                    }
                ]
            }
        ]
    },
    ...
]
 
Suggest Edits

AnswerFactory Estimate Reference Overview

Overview of the AnswerFactory Estimate API

 
Table of Contents
AnswerFactory Project API Parameters
Associated API Calls for AnswerFactory Projects

Estimate API Parameters

Parameter Data Type Parameter Type Description Required?
projectId String Path The ID of the project. Note: ID, not name. Required
recipeId String Path The ID of the recipe. Note: ID, not name. Required

Associated API Calls for AnswerFactory Estimates

Retrieve Estimate for Existing AnswerFactory Project
Retrieve Estimate for New AnswerFactory Project

 
Suggest Edits

Retrieve Estimate for Existing AnswerFactory Project

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/estimate/projectId/recipeId

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

Unique identifier of the recipe.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/estimate/:projectId/:recipeId

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
200 OK

Body:
  {
    ... one estimate object, not array (see Estimate Reference Overview above) ...
  }


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/estimate/c44bb3eb-dc55-412e-bd1e-82e15d90340e/extract-lulc-change
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "projectId": "c44bb3eb-dc55-412e-bd1e-82e15d90340e",
    "recipeId": "extract-lulc-change",
    "recipeName": "Extract LULC Change",
    "durationMillis": 1106390,
    "storageBytes": 0,
    "imageCount": 2,
    "errorMessages": null,
    "warningMessages": [
        "1030010066093B00 - best available model is trained on data 27 km away and from different seasons: summer",
        "10300100694CC500 - best available model is trained on data 27 km away and from different seasons: summer"
    ],
    "specificEstimatesTruncated": false,
    "specificEstimates": [
        {
            "ids": [
                "1030010066093B00"
            ],
            "dates": [
                1491149261779
            ],
            "durationMillis": 553195,
            "storageBytes": 0
        },
        {
            "ids": [
                "10300100694CC500"
            ],
            "dates": [
                1495123748000
            ],
            "durationMillis": 553195,
            "storageBytes": 0
        }
    ]
}
 
Suggest Edits

Retrieve Estimate for New AnswerFactory Project

 
posthttps://vector.geobigdata.io/answer-factory-recipe-service/api/estimate

Body Params

json
required

The "Try it Out" feature is not available for this request.

Please use the GBDX AnswerFactory Postman Collection to try this request.

Setup:
Request:
POST /answer-factory-recipe-service/api/estimate

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe

Headers:
  Authorization: Bearer {token}
  Accept: application/json
  Content-Type: application/json

Body:
  {
   ... project definition ...
  }


Response (success):
200 OK

Body:
  [
    {
      "projectId": "unique identifier of project",
      "recipeId": "unique identifier of recipe",
      "recipeName": "unique name of recipe",
      "durationMillis": /* estimated compute time in milliseconds */,
      "storageBytes": /* estimated amount of S3 customer storage used in bytes */,
      "imageCount": /* number of images that the recipe will process to sufficiently cover project areas of interest */,
      "specificEstimates": [
        {
          "ids": [
            "acquisition/image id 1",
            "..."
          ],
          "dates": [
            "acquisition/image timestamp 1 in millis from epoch format",
            "..."
          ],
          "durationMillis": /* estimated compute time in milliseconds to process this image */,
          "storageBytes": /* estimated amount of S3 customer storage used in bytes to process this image */
        },
        {
          ...
        }
      ],
      "specificEstimatesTruncated": /* boolean; true if not all images that are expected to be processed have corresponding specific estimates */
    },
    {
      ...
    }
  ] 


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/estimate

Body:
{
	"name": "Test_Project",
	"recipeConfigs":[
		{
			"recipeId": "query-tweets",
			"recipeName": "Query Tweets",
			"parameters": [],
			"configurationDate": "2017-05-01T12:56:48.276Z"
		}
		],
		"tags":[],
		"description": "",
		"notes": "",
		"acquisitionIds":"",
		"originalGeometries":[
			{
				"type": "Feature",
				"geometry":{
					"type": "Polygon",
					"coordinates":[
						[
							[12.491111755371088,41.892470325119746],
							[12.489523887634274,41.888381086722546],
							[12.49510288238525,41.88694340165634],
							[12.497076988220211,41.89116051944157],
							[12.491111755371088,41.892470325119746]
						]
					]
				},
				"properties":{
					"name": "Colosseum"
				}
			}
		],
		"aois":[
			{
				"type": "Polygon",
				"coordinates":[
					[
						[12.491112,41.89247],
						[12.497077,41.891161],
						[12.495103,41.886943],
						[12.489524,41.888381],
						[12.491112,41.89247]
					]
				]
			}
		],
		"continuouslyOrdered": false,
		"visibility":[],
		"dateRange":{
			"startDate":null,
			"endDate":null,
			"count":null
		}
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "projectId": null,
    "recipeId": "query-tweets",
    "recipeName": "Query Tweets",
    "durationMillis": 0,
    "storageBytes": 0,
    "imageCount": 0,
    "message": null,
    "specificEstimatesTruncated": false,
    "specificEstimates": null
  }
]
 
Suggest Edits

AnswerFactory Tag Reference Overview

Overview of the AnswerFactory Tagging API

 
Table of Contents
AnswerFactory Tag API Parameters
Associated API Calls for AnswerFactory Tags

Tag API Parameters

Parameter Data Type Parameter Type Description Required?
columnId String Path The column identification in the table of the vector item. Required
itemId String Path The vector id. Required
projectId String Path The ID of the project. Note: ID, not name. Required
recipeId String Path The ID of the recipe. Note: ID, not name. Required
rowId String Path The row identification in the table of the vector item. This is the AOI name. Required
tagName String Path The word(s) used in the tag. For example, thumbs-up or test. Required

Associated API Calls for AnswerFactory Tags

Add Item to Tagged Cell
Create Tagged Cell
Remove Item to Tagged Cell
Retrieve Items for Cell
Retrieve Items for Cell and Tag
Retrieve Tags for AnswerFactory Project
Retrieve Tags for AnswerFactory Project and Recipe

 
Suggest Edits

Add Item to Tagged Cell

 

Header Auth

 Authentication is required for this endpoint.
puthttps://vector.geobigdata.io/answer-factory-recipe-service/api/tags/projectId/recipeId/rowId/columnId/tagName/itemId

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

The ID of the recipe.

rowId
string
required

The row identification in the table of the vector item.

columId
string
required

The column identification in the table of the vector item.

tagName
string
required

The tag word(s).

itemId
string
required

The vector id.

 
Setup:
Request:
PUT /answer-factory-recipe-service/api/tags/:projectId/:recipeId/:rowId/:columnId/:tagName/:itemId

Headers:
  Authorization: Bearer {token}

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column
  tagName: the name of the tag
  itemId: the ID of the item to add


Response (success):
202 OK


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/tags/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/US%20Naval%20Research/e3b96bb1-f174-4597-bc54-21f73bcbd5db/thumbs-up/aadea006-02a5-4578-96ca-f5352ac4a540
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Create Tagged Cell

 

Header Auth

 Authentication is required for this endpoint.
puthttps://vector.geobigdata.io/answer-factory-recipe-service/api/tags/projectId/recipeId/rowId/columnId/tagName

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

The ID of the recipe.

rowId
string
required

The row identification in the table of the vector item.

columId
string
required

The column identification in the table of the vector item.

tagName
string
required

The tag word(s).

 
Setup:
Request:
PUT /answer-factory-recipe-service/api/tags/:projectId/:recipeId/:rowId/:columnId/:tagName

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column
  tagName: the name of the tag

Headers:
  Authorization: Bearer {token}


Response (success):
202 OK


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/tags/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/US%20Naval%20Research/e3b96bb1-f174-4597-bc54-21f73bcbd5db/test
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Remove Item to Tagged Cell

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://vector.geobigdata.io/answer-factory-recipe-service/api/tags/projectId/recipeId/rowId/columnId/tagName/itemId

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

The ID of the recipe.

rowId
string
required

The row identification in the table of the vector item.

columId
string
required

The column identification in the table of the vector item.

tagName
string
required

The tag word(s).

itemId
string
required

The vector id.

 
Setup:
Request:
DELETE /answer-factory-recipe-service/api/tags/:projectId/:recipeId/:rowId/:columnId/:tagName/:itemId

Headers:
  Authorization: Bearer {token}

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column
  tagName: the name of the tag
  itemId: the ID of the item to remove


Response (success):
202 OK


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/tags/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/US%20Naval%20Research/e3b96bb1-f174-4597-bc54-21f73bcbd5db/thumbs-up/aadea006-02a5-4578-96ca-f5352ac4a540
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results
 
Suggest Edits

Retrieve Items for Cell

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/tags/projectId/recipeId/rowId/columnId

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

The ID of the recipe.

rowId
string
required

The row identification in the table of the vector item.

columId
string
required

The column identification in the table of the vector item.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/tags/:projectId/:recipeId/:rowId/:columnId

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
202 OK

Body:
  [
    {
      "tagId": "unique identifier for cell tag",
      "projectId": "unique identifier for project",
      "recipeId": "unique identifier for recipe",
      "rowId": "row identifier",
      "columnId": "column identifier",
      "cellId": "cell identifier",
      "tagName": "name of user specified tag",
      "items": [
        "item id (typically vector id) 1",
        "item id (typically vector id) 2",
        "..."
      ]
    },
    {
      ...
    }
  ]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/tags/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/US%20Naval%20Research/e3b96bb1-f174-4597-bc54-21f73bcbd5db
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "tagId": "10528198ce7065e1e3fb839bf3acf4137b930287",
    "cellId": "e45c0bdb39f59fb8f759da118b3968df92f4bab5",
    "projectId": "ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc",
    "recipeId": "openskynet-aircraft-detection",
    "rowId": "US Naval Research",
    "columnId": "e3b96bb1-f174-4597-bc54-21f73bcbd5db",
    "tagName": "thumbs-down",
    "items": [
      "e83a5bcc-e424-4906-9e75-c0f604d8f6ec"
    ]
  },
  {
    "tagId": "14f41012886707a32ef5f5881237205cdb608588",
    "cellId": "e45c0bdb39f59fb8f759da118b3968df92f4bab5",
    "projectId": "ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc",
    "recipeId": "openskynet-aircraft-detection",
    "rowId": "US Naval Research",
    "columnId": "e3b96bb1-f174-4597-bc54-21f73bcbd5db",
    "tagName": "thumbs-up",
    "items": [
      "aadea006-02a5-4578-96ca-f5352ac4a540"
    ]
  }
]
 
Suggest Edits

Retrieve Items for Cell and Tag

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/tags/projectId/recipeId/rowId/columnId/tagName

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

The ID of the recipe.

rowId
string
required

The row identification in the table of the vector item.

columId
string
required

The column identification in the table of the vector item.

tagName
string
required

The tag word(s).

 
Setup:
Request:
GET /answer-factory-recipe-service/api/tags/:projectId/:recipeId/:rowId/:columnId/:tagName

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column
  tagName: the name of the tag

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
202 OK

Body:
  {
    "tagId": "unique identifier for cell tag",
    "projectId": "unique identifier for project",
    "recipeId": "unique identifier for recipe",
    "rowId": "row identifier",
    "columnId": "column identifier",
    "cellId": "cell identifier",
    "tagName": "name of user specified tag",
    "items": [
      "item id (typically vector id) 1",
      "item id (typically vector id) 2",
      "..."
    ]
  }


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/tags/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection/US%20Naval%20Research/e3b96bb1-f174-4597-bc54-21f73bcbd5db/thumbs-up
Request:
GET /answer-factory-recipe-service/api/tags/:projectId/:recipeId/:rowId/:columnId/:tagName

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe
  rowId: the ID of the row
  columnId: the ID of the column
  tagName: the name of the tag

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
202 OK

Body:
  {
    "tagId": "unique identifier for cell tag",
    "projectId": "unique identifier for project",
    "recipeId": "unique identifier for recipe",
    "rowId": "row identifier",
    "columnId": "column identifier",
    "cellId": "cell identifier",
    "tagName": "name of user specified tag",
    "items": [
      "item id (typically vector id) 1",
      "item id (typically vector id) 2",
      "..."
    ]
  }
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "tagId": "14f41012886707a32ef5f5881237205cdb608588",
  "cellId": "e45c0bdb39f59fb8f759da118b3968df92f4bab5",
  "projectId": "ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc",
  "recipeId": "openskynet-aircraft-detection",
  "rowId": "US Naval Research",
  "columnId": "e3b96bb1-f174-4597-bc54-21f73bcbd5db",
  "tagName": "thumbs-up",
  "items": [
    "aadea006-02a5-4578-96ca-f5352ac4a540",
    "384add84-fb33-4ba5-b857-b0d9863d8290"
  ]
}
 
Suggest Edits

Retrieve Tags for AnswerFactory Project

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/tags/projectId

Path Params

projectId
string
required

The ID of the project.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/tags/:projectId

Params:
  projectId: the ID of the project

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
202 OK

Body
  [
    "tag name 1",
    "tag name 2",
    "..."
  ]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/tags/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc
Request:
GET /answer-factory-recipe-service/api/tags/:projectId

Params:
  projectId: the ID of the project

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
202 OK

Body
  [
    "tag name 1",
    "tag name 2",
    "..."
  ]
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  "thumbs-down",
  "thumbs-up"
]
 
Suggest Edits

Retrieve Tags for AnswerFactory Project and Recipe

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/answer-factory-recipe-service/api/tags/projectId/recipeId

Path Params

projectId
string
required

The ID of the project.

recipeId
string
required

The ID of the recipe.

 
Setup:
Request:
GET /answer-factory-recipe-service/api/tags/:projectId/:recipeId

Params:
  projectId: the ID of the project
  recipeId: the ID of the recipe

Headers:
  Authorization: Bearer {token}
  Accept: application/json


Response (success):
202 OK

Body
  [
    "tag name 1",
    "tag name 2",
    "..."
  ]


Example:
https://vector.geobigdata.io/answer-factory-recipe-service/api/tags/ec9a9f8e-23ae-435e-b7e3-1aa7767e9fdc/openskynet-aircraft-detection
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  "thumbs-up"
]
 
Suggest Edits

Vector Services Index Query Reference Overview

Overview of the Index Query API

 
Table of Contents
Index Query Vector Services API Parameters
Index Query Aggregations Type Definitions
Index Query Vector Services Parameter Limits
Associated API Calls for Index Query Vector Services

These endpoints work in any application.

Index Query API Parameters

Parameter Data Type Parameter Type Description Required?
aggs String Query The aggregation definitions (see Aggregations for details). Required; aggregations only
count Integer Query Definition for index query: The number of records to return per shard per page request. Definition for index aggregation: The number of groupings to return per aggregation, used to display the top N buckets for an aggregation. Default 10. Optional
endDate String Query A convenience parameter for setting the value for the latest item_date value to be included in the set of aggregated items. Note: The date range can be specified with ISO-8601 date strings or with expressions using the term "now" to indicate the current date. The date expressions can include simple "date math" by appending "+" or "-" along with a numeral and a unit. For example, to set the start date to one day ago, the start date expression would read "now-1d". The units supported are "y" (year), "M" (month), "w" (week), "d" (day), "h" (hour), "m" (minute), and "s" (second). The date range is inclusive at both ends. If no date range is provided, then all items within the AOI will be included. Optional; Required with startDate; aggregations only
fields String Path The comma-separated list of fields to return for the items. Example: item_date,source,item_type Optional
index String Path The index to which vector items are stored. Note: All indicies follow the format vector-{user defined index name} or vector-web-{geohash}. Required
left String Query The leftmost X-coordinate for the bounding box; longitude in decimal degrees of the lower left bounding box corner. Required for bounding box calls
lower String Query The lowest Y-coordinate for the bounding box; latitude in decimal degrees of the lower left bounding box corner. Required for bounding box calls
pagingId String Form The paging session ID for which to retrieve a page. Optional; required for paging results
q String Query The Elasticsearch query string to constrain the document set. Required; query only
query String Query The Elasticsearch query string to filter the source items for the aggregations. See Query Syntax, Fields, and Type Suffixes for more detail. Optional; aggregations only
right String Query The rightmost X-coordinate for the bounding box; longitude in decimal degrees of the upper right bounding box corner. Required for bounding box calls
shape String Query GeoJSON of the aoi in GeometryCollection format. Example: {"type":"GeometryCollection","geometries":[{"type": "MultiPolygon","coordinates": [[[[-109.0283203125,36.98500309285596],[-109.0283203125,40.97989806962013],[-102.06298828125,40.97989806962013],[-102.06298828125,37.00255267215955],[-109.0283203125,36.98500309285596]]]]}]} Required for shape calls
sort String Query A convenience parameter for sorting the returned results. Defaults to ascending, but the user has the option of specifying ascending or descending order with asc and desc. Any vector fields may be used in conjunction with sort, and multiple fields may be used at once, separated by a comma. Example: sort=item_type, sort=item_date:desc, sort=ingest_source:asc,attributes.name:desc Optional
spatialRelation String Query How a provided geometry is used to filter results. Requires either bbox geometry or GeoJSON geometry, or is ignored. Defaults to intersects, but the user has the option of specifying intersects (any items that cross or touch the provided geometry in any way), contains (any items that completely cover the provided geometry), within (any items that are completely covered by the provided geometry), or disjoint (any items that do not touch the provided geometry). Optional
startDate String Query A convenience parameter for setting the value for the earliest item_date value to be included in the set of aggregated items. Note: The date range can be specified with ISO-8601 date strings or with expressions using the term "now" to indicate the current date. The date expressions can include simple "date math" by appending "+" or "-" along with a numeral and a unit. For example, to set the start date to one day ago, the start date expression would read "now-1d". The units supported are "y" (year), "M" (month), "w" (week), "d" (day), "h" (hour), "m" (minute), and "s" (second). The date range is inclusive at both ends. If no date range is provided, then all items within the AOI will be included. Optional; Required with endDate; aggregations only
upper String Query The highest Y-coordinate for the bounding box; latitude in decimal degrees of the upper right bounding box corner. Required for bounding box calls

Index Query Aggregations Type Definitions

Aggregation Query Definition
avg Computes the average of the values for the document field. The field definition is required. For example: To compute the average for the “positive sentiment” attribute value, use “avg:attributes.sentiment_positive_dbl”. Note: When using attributes, be sure to use the numeric version of the attribute, e.g. the attribute that ends with either _int or _dbl.
avg_geo_lat Computes the average latitude of the point_samples field for a set of documents.
avg_geo_lon Computes the average longitude of the point_samples field for a set of documents.
cardinality Computes the number of unique values for the document field specified. The field definition is required. For example: To compute the number of unique values for the ingest_source field, use cardinality:ingest_source.
date_hist Counts the set of documents into buckets based on the item_date field. An optional interval may be added to the aggregation definition to change the time unit for each bucket. The units supported are d (day), h (hour), m (minute), s (second), ms (millisecond), micros, nanos, year, quarter, month, week, day, hour, minute, second. Note that any duration value must be an integer, e.g. 1d, and duration values are only used on d, h, m, and s values. For example: To bucket a set of documents by minute, use date_hist:m. The default unit is d (date_hist:d).
geohash Counts the set of documents into buckets based on the geohash of the point_samples field. An optional precision may be added to the aggregation definition to change the length of the geohash for each bucket. For example: To bucket a set of documents by four-character geohashes, use geohash:4. The default precision is six characters (geohash:6).
max Computes the maximum value for a document field. The field definition is required. For example: To compute the maximum x coordinate value, use "max:max_x". Note: When using attributes, be sure to use the numeric version of the attribute, e.g. the attribute that ends with either _int or _dbl. Fields ending in _date may also be used.
min Computes the minimum value for a document field. The field definition is required. For example: To compute the minimum for the "attributes.cloudCover_int" attribute value, use "min:attributes.cloudCover_int". Note: When using attributes, be sure to use the numeric version of the attribute, e.g. the attribute that ends with either _int or _dbl. Fields ending in _date may also be used.
sum Computes the sum of the values for the document field. The field definition is required. For example: To compute the sum for the "count_int" attribute value of the Car Count vectors, use sum:attributes.count_int. Note: Sum works with numeric attributes - those ending with either _int or _dbl.
terms Counts the set of documents into buckets based on the unique values of the document field specified in the aggregation definition. The field definition is required. For example: To count documents into buckets based on unique terms in the ingest_source field, use terms:ingest_source.

Note: aggregations can be nested within each other by creating a sequence of aggregation definitions separated by semi-colons. A final “grouping” of aggregations can be at the bottom level by surrounding the final set of aggregations with parentheses and separating them by commas. For example, to group a set of documents by geohash, time range, and finally to count the total number of terms in and list the most highly-occurring values for the ingest_source field in those groups, the 'aggs' definition might look like this: geohash:4;date_hist:d;(cardinality:ingest_source,terms:ingest_source) or terms:item_type;(min:min_y, min:min_x, max:max_y, max:max_x)

Note: query aggregations can be made using either a bounding box to reference the aoi, or using polygons for a more precise aoi/multiple aois. For a bounding box, use the GET method with the upper/lower X/Y parameters. For an arbitrary polygon, use the POST method with a GeoJSON-formatted polygon definition in the body of the request.

Index Query Parameter Limits

Parameters Limits
fields Possible field options are: attributes, format, geom, geom_type, id, ingest_attributes, ingest_date, ingest_source, item_date, item_type, name, original_crs, source, text. Note: geom will always display, even if not specified.
left Between -180 and 180 degrees inclusive.
lower Between -90 and 90 degrees inclusive.
right Between -180 and 180 degrees inclusive.
upper Between -90 and 90 degrees inclusive.

Associated API Calls for Index Query Vector Services

Index Query: Aggregation by Bounding Box
Index Query: Aggregation by Shape
Index Query: Get Paging ID for Bounding Box
Index Query: Get Paging ID for Shape
Index Query: List Vector Items for Bounding Box (Returns Default Fields)
Index Query: List Vector Items for Bounding Box (Returns Selected Fields)
Index Query: List Vector Items for Shape
Retrieve Page of Vector Items

 
Suggest Edits

Check Availability of Vector Service Endpoints

Vector Service Heartbeat

 
gethttps://vector.geobigdata.io/insight-vector/api/heartbeat

The "Try it Out" feature is not available for this request.

Please use the GBDX Vector Postman Collection to try this request.

Setup:
Request:
GET /insight-vector/api/heartbeat

Response:
200 OK


Example:
https://vector.geobigdata.io/insight-vector/api/heartbeat
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
OK
 
Suggest Edits

Index Query: Aggregation by Bounding Box

Groups vector items for a given index, aggregation definition, date range, and bounding box.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://vector.geobigdata.io/insight-vector/api/index/aggregation/index

Path Params

index
string
required

The Elasticsearch index within which the desired vectors are stored.

Query Params

aggs
string
required

The aggregation definitions. Example: geohash:4;terms:ingest_source

query
string

The Elasticsearch query string to constrain the document set. Example: item_date:[now-1w TO now]

left
string
required

The west most X-coordinate for the bounding box. Example: -77.794631

right
string
required

The east most X-coordinate for the bounding box. Example: -76.429580

upper
string
required

The north most Y-coordinate for the bounding box. Example: 39.370370

lower
string
required

The south most Y-coordinate for the bounding box. Example: 38.371776

startDate
string

ISO-8601-formatted (example: 2015-09-03T12:07:16.179Z) or "now" expression formatted date string for the start of a date range; startDate runs a query against the field item_date. Note: For more information on the syntax, check the Query Syntax page. If no date range is provided, then all items within the AOI will be included.

endDate
string

ISO-8601-formatted (example: 2015-09-03T12:52:33.208Z) or "now" expression formatted date string for the end of a date range; endDate runs a query against the field item_date. Note: For more information on the syntax, check the Query Syntax page. If no date range is provided, then all items within the AOI will be included. The date range is inclusive at both ends.

count
int32

The number of buckets to return per aggregation. Example: 10

For more information on aggregations parameters and definitions, check the Vector Services Index Parameters and the Vector Services Aggregation Parameters.

For examples of how to form an aggregation query, check the Index Query Examples.

Setup:
Request:
  GET /insight-vector/api/index/aggregation/:index?aggs=:aggs&query=:query&left=:left&right=:right&upper=:upper&lower=:lower&startDate=:startDate&endDate=:endDate&count=:count

Headers:
  Authorization: Bearer {token}


Response (success):
  200 OK


Example:
https://vector.geobigdata.io/insight-vector/api/index/aggregation/vector-web-s?aggs=terms:ingest_source&query=test&left=-180&right=180&upper=90&lower=-90&startDate=now-3M&endDate=now&count=10
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "responseDate": "2017-04-26T13:36:43Z",
  "geom": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -180,
          -90
        ],
        [
          -180,
          90
        ],
        [
          180,
          90
        ],
        [
          180,
          -90
        ],
        [
          -180,
          -90
        ]
      ]
    ]
  },
  "query": "test",
  "startDate": "now-3M",
  "endDate": "now",
  "totalItems": 45,
  "aggregations": [
    {
      "name": "terms:ingest_source",
      "terms": [
        {
          "term": "HGTD-test",
          "count": 26,
          "aggregations": null
        },
        {
          "term": "REST API test source",
          "count": 18,
          "aggregations": null
        },
        {
          "term": "Vector REST API",
          "count": 1,
          "aggregations": null
        }
      ]
    }
  ]
}
 
Suggest Edits

Index Query: Aggregation by Shape

Groups vector items for a given index, aggregation definition, date range, and shape.

 
posthttps://vector.geobigdata.io/insight-vector/api/index/aggregation/index

Path Params

index
string
required

The Elasticsearch index within which the desired vectors are stored.

Query Params

aggs
string
required

The aggregation definitions. Example: geohash:4;terms:ingest_source

query
string

The Elasticsearch query string to constrain the document set. Example: ingest_date:[now-3w TO now]

startDate
string

ISO-8601-formatted (example: 2015-09-03T12:07:16.179Z) or "now" expression formatted date string for the start of a date range; startDate runs a query against the field item_date. Note: For more information on the syntax, check the Query Syntax page. If no date range is provided, then all items within the AOI will be included.

endDate
string

ISO-8601-formatted (example: 2015-09-03T12:52:33.208Z) or "now" expression formatted date string for the end of a date range; endDate runs a query against the field item_date. Note: For more information on the syntax, check the Query Syntax page. If no date range is provided, then all items within the AOI will be included. The date range is inclusive at both ends.

count
int32

The number of buckets to return per aggregation. Example: 10

Body Params

json
required

GeoJSON coordinates of the area of interest.

The "Try it Out" feature is not available for this request.

Please use the GBDX Vector Postman Collection to try this request.

For more information on aggregations parameters and definitions, check the Vector Services Index Parameters and the Vector Services Aggregation Parameters.

For examples of how to form an aggregation query, check the Index Query Examples.

Setup:
Request:
  GET /insight-vector/api/index/aggregation/:index?aggs=:aggs&query=:query&startDate=:startDate&endDate=:endDate&count=:count

Headers:
  Authorization: Bearer {token}
  Content-Type: application/json


Response (success):
  200 OK


Example:
https://vector.geobigdata.io/insight-vector/api/index/aggregation/vector-web-s?aggs=terms:ingest_source&query=test&startDate=now-3M&endDate=now&count=10

Body:
{
    "type": "Polygon",
    "coordinates": [ [ [-180, -90], [-180, 90], [180, 90], [180, -90], [-180, -90] ] ]
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}