Skip to main content

API Reference

tip

Refer to the Authentication Page for details on generating an authentication token (JWT)

Create Job API​

 POST /solutions/bayerAgPowered.smartBoundary:create

SentinelHub License Required

The Imagery Insights Create Job API requires a valid SentinelHub License clientId and ClientSecret Stored in your local ADMA Key Vault. Please follow the Install Instructions if those are not already configured.

Create Request​

Request Headers​

{
    "Content-Type": "application/json",
    "Authorization": "Bearer <TOKEN>"
}

Sample Request Body​

{
    "requestPath": "/v1/smart-boundary/<User Defined Unique Job ID>", # Something like 2024_08_27_18000
    "partnerRequestBody": {
        "imageEndDate": "2023-08-14",
        "imageStartDate": "2023-08-01",
        "partyId": "53b8f2b9-0000-0000-0000-9c821feb0ee2",
        "pointOnSurface": {
          "longitude": -92.9819,
          "latitude": 41.5046
        },
        "resourceId": "4b879eea-0000-0000-0000-cb608529c0f8",
        "resourceType": "Farm"
    }
}

XY Order

Note that the pointOnSurface is specified in xy-order, that is, longitude-latitude order, with negative values representing west longitude values or south latitude values. Thus, [-92.9819, 41.5046] is at 92.9819 degrees west longitude and 41.5046 north latitude.

Farm resource

The resource for this APS is a farm. The service uses the farm to create a field specifying a rectangular search region. The "search region" field is used when calling the ADMA Scenes service to acquire satellite imagery for estimating the boundary.

Request Body Parameters​

ParameterDescription
requestPath
String		The APS API path to be called with a unique ID for the job provided by the client
Example: /v1/smart-boundary/<User Defined Unique Job ID>
partnerRequestBody
String		Object with all required body parameters to create a Smart Boundary APS job
Details: See partnerRequestBody Parameters

partnerRequestBody Parameters​

Required Parameters​
ParameterDescription
imageEndDate
String		The last day (inclusive) of imagery to use in generating a Smart Boundary prediction.
Example: "2023-08-14"
imageStartDate
String		The first day of imagery, no more than 14 days before the last day.
Example: "2023-08-01"
partyId
String		The ID of the ADMA Party requesting the prediction
Example: "53b8f2b9-0000-0000-0000-9c821feb0ee2"
resourceType
String		The type of ADMA resource used for acquiring satellite imagery
Options: "Farm"
resourceId
String		The ID of the ADMA resource type used for acquiring satellite imagery
Example: "4b879eea-0000-0000-0000-cb608529c0f8"

Response​

Response Sample: 202 Accepted​

{
    "e2eId": "bd04d347c00000000000000a444b8cea",
    "id": "2024_08_27_18000",
    "jobCreatedDateTime": "2024-08-27T18:18:41Z",
    "jobLastActionDateTime": "2024-08-27T18:18:41Z",
    "message": "MESA-01001: Job queued successfully.",
    "partnerRequestBody": {
        "modelSpec": {
            "imageEndDate": "2023-08-21",
            "imageStartDate": "2023-08-08",
            "pointOnSurface": {
                "longitude": -92.9819,
                "latitude": 41.5046
            }
        },
        "partyId": "53b8f2b9-0000-0000-0000-9c821feb0ee2",
        "resourceId": "4b879eea-0000-0000-0000-cb608529c0f8",
        "resourceType": "Farm"
    },
    "status": "WAITING"
}

Error Response Sample​

{
    "error": {
        "code": "IMG-04103",
        "message": "Job JobId [<ADMA Instance URL>, 2024_08_27_18000] already exists."
    },
    "traceId": "7af4e84d-0000-0000-0000-40a0347e9752"
}

Fetch Status API​

 POST /solutions/bayerAgPowered.smartBoundary:fetch

Fetch Request​

Request Headers​

{
    "Content-Type": "application/json",
    "Authorization": "Bearer <TOKEN>"
}

See Authorization Documentation for details on generating a JWT Token

Sample Request Body​

{
    "requestPath":"/v1/smart-boundary/<User Defined Unique Job ID>", # Something like 2024_08_27_18000
}

Request Body Parameters​

ParameterDescription
requestPath
String		The APS API path to be called with an existing Job ID provided by the client
Example: /v1/smart-boundary/<User Defined Unique Job ID>

Response​

Response Sample​

{
    "e2eId": "bd04d347c00000000000000a444b8cea",
    "id": "2024_08_27_18000",
    "insightId": "468799eb-0000-0000-0000-aab05869701f",
    "jobCreatedDateTime": "2024-08-27T18:18:41Z",
    "jobLastActionDateTime": "2024-08-27T18:19:11Z",
    "jobProcessingDurationInSeconds": 28,
    "jobProcessingEndDateTime": "2024-08-27T18:19:11Z",
    "jobProcessingStartDateTime": "2024-08-27T18:18:43Z",
    "message": "Job is completed successfully.",
    "partnerRequestBody": {
        "imageEndDate": "2023-08-14",
        "imageStartDate": "2023-08-01",
        "partyId": "53b8f2b9-0000-0000-0000-9c821feb0ee2",
        "pointOnSurface": {
            "longitude": -92.9819,
            "latitude": 41.5046
        },
        "resourceId": "4b879eea-0000-0000-0000-cb608529c0f8",
        "resourceType": "Farm"
    },
    "status": "SUCCEEDED"
}

Error Response Sample​

{
    "error": {
        "code": "IMG-04101",
        "message": "Job not found JobId [<ADMA Instance URL>, 2024_08_27_18000], "
    },
    "traceId": "7af4e84d-0000-0000-0000-40a0347e9752"
}

Cancel Job API​

 POST /solutions/bayerAgPowered.smartBoundary:cancel

Cancel Request​

Request Headers​

{
    "Content-Type": "application/json",
    "Authorization": "Bearer <TOKEN>"
}

See Authorization Documentation for details on generating a JWT Token

Sample Request Body​

{
    "requestPath":"/v1/smart-boundary/<User Defined Unique Job ID>", # Something like 2024_08_27_18000
}

Request Body Parameters​

ParameterDescription
requestPath
String		Request path containing api-version, query parameters and path route to be called for partner
Example: /v1/smart-boundary/<User Defined Unique Job ID>

Response​

Response Sample​

{
    "e2eId": "bd04d347c00000000000000a444b8cea",
    "id": "2024_08_27_18000",
    "jobCreatedDateTime": "2024-08-27T18:18:41Z",
    "jobLastActionDateTime": "2024-08-27T18:19:11Z",
    "message": "MSIMAGE-02002: Job is cancelled successfully.",
    "partnerRequestBody": {
        "modelSpec": {
            "imageEndDate": "2023-08-21",
            "imageStartDate": "2023-08-08",
            "pointOnSurface": {
                "longitude": -92.9819,
                "latitude": 41.5046
            }
        },
        "partyId": "53b8f2b9-0000-0000-0000-9c821feb0ee2",
        "resourceId": "4b879eea-0000-0000-0000-cb608529c0f8",
        "resourceType": "Farm"
    },
    "status": "CANCELLED"
}

Error Response Sample​

{
    "error": {
        "code": "MSIMAGE-04102",
        "message": "Invalid job status <Job Status> for the cancel operation."
    },
    "traceId": "7af4e84d-0000-0000-0000-40a0347e9752"
}