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.cwum:create

SentinelHub License Required

The Crop Water Use Maps 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/cwum-add-on/<User Defined Unique Job ID>", # Something like 12_04_23_1000
  "partnerRequestBody": {
    "partyId": "e08336e5-bf4a-40ca-bf01-8e0377b9ed9f",
    "resourceId": "078fa953-de3a-4169-bf08-29155110545e",
    "resourceType": "Field",
    "collection": "sentinel-2-l1c",
    "sceneStartDateTime": "2023-10-10T00:00:00",
    "sceneEndDateTime": "2023-10-15T23:59:59"
  }
}

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/cwum-add-on/<User Defined Unique Job ID>
partnerRequestBody
String		Object with all required body parameters to create an APS job
Details: See partnerRequestBody Parameters

partnerRequestBody Parameters​

Required Parameters​
ParameterDescription
partyId
String		The ID of the ADMA Party resource associated with the Field Resource used in the request
Example: "53b8f2b9-04b3-4462-ac52-9c821feb0ee2"
resourceType
String		The type of ADMA resource being used to request cwum.
Options: "Field"
resourceId
String		The ID of the ADMA resource type (ie. "Field") used to request cwum.
Example: "4b879eea-1c04-45c5-8669-cb608529c0f8"
collection
String		The STAC collection to source Sentinel Imagery from SentinelHub.
Options: sentinel-2-l1c
sceneStartDateTime
String		Start datetime (inclusive) for ADMA scene search.
Example: "2023-01-01T00:00:00"
sceneEndDateTime
String		End datetime (inclusive) for ADMA scene seach. Cannot be more than 2 weeks after sceneStartDateTime
Example: "2023-01-10T00:00:00"

Response​

Response Sample: 202 Accepted​

{
  "id": "1234",
  "jobCreatedDateTime": "2024-02-26T21:46:23Z",
  "jobLastActionDateTime": "2024-02-26T21:46:23Z",
  "message": "CWUM-01001: Job queued successfully.",
  "status": "WAITING",
  "e2eId": "e3634dc2f8b5aa61bb922520408c5a50",
  "partnerRequestBody": {
    "solutionId": "bayerAgPowered.cwum",
    "partyId": "e08336e5-bf4a-40ca-bf01-8e0377b9ed9f",
    "resourceType": "Field",
    "resourceId": "078fa953-de3a-4169-bf08-29155110545e",
    "sceneStartDateTime": "2023-10-10T00:00:00Z",
    "sceneEndDateTime": "2023-10-15T23:59:59Z"
  }
}

Error Response Sample​

{
  "error": {
    "code": "CWUM-04103",
    "message": "Job JobId [<ADMA Instance URL>, 1234] already exists"
  },
  "traceId": "7af4e84d-aac0-43a3-ba69-40a0347e9752"
}

Fetch Status API​

 POST /solutions/bayerAgPowered.cwum: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/cwum-add-on/<User Defined Unique Job ID>", # Something like 12_04_23_1000
}

Request Body Parameters​

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

Response​

Response Sample​

{
  "id": "1234",
  "jobCreatedDateTime": "2024-02-26T21:46:23Z",
  "jobLastActionDateTime": "2024-02-26T21:46:29Z",
  "jobProcessingStartDateTime": "2024-02-26T21:46:24Z",
  "jobProcessingEndDateTime": "2024-02-26T21:46:29Z",
  "jobProcessingDurationInSeconds": 5,
  "message": "CWUM-02001: Job is completed successfully.",
  "status": "SUCCEEDED",
  "e2eId": "e3634dc2f8b5aa61bb922520408c5a50",
  "partnerRequestBody": {
    "solutionId": "bayerAgPowered.cwum",
    "partyId": "e08336e5-bf4a-40ca-bf01-8e0377b9ed9f",
    "resourceType": "Field",
    "resourceId": "078fa953-de3a-4169-bf08-29155110545e",
    "sceneStartDateTime": "2023-10-10T00:00:00Z",
    "sceneEndDateTime": "2023-10-15T23:59:59Z"
  }
}

Error Response Sample​

{
  "error": {
    "code": "CWUM-04101",
    "message": "Job not found JobId [<ADMA Instance URL>, 1234], "
  },
  "traceId": "7af4e84d-aac0-43a3-ba69-40a0347e9752"
}

Cancel Job API​

 POST /solutions/bayerAgPowered.cwum: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/cwum-add-on/<User Defined Unique Job ID>", # Something like 12_04_23_1000
}

Request Body Parameters​

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

Response​

Response Sample​

{
  "id": "1234",
  "message": "CWUM-02002: Job is cancelled successfully.",
  "status": "CANCELLED",
  "jobCreatedDateTime": "2023-04-28T00:00:00Z",
  "jobLastActionDateTime": "2023-04-28T00:27:00Z",
  "jobProcessingStartDateTime": "2023-04-28T00:05:00Z",
  "jobProcessingEndDateTime": "2023-04-28T00:27:00Z",
  "jobProcessingDurationInSeconds": 22,
  "e2eid": "a1853978d9ae412ccd55923ca41891c7",
  "partnerRequestBody": {
    "solutionId": "bayerAgPowered.cwum",
    "partyId": "e08336e5-bf4a-40ca-bf01-8e0377b9ed9f",
    "resourceType": "Field",
    "resourceId": "078fa953-de3a-4169-bf08-29155110545e",
    "sceneStartDateTime": "2023-10-10T00:00:00Z",
    "sceneEndDateTime": "2023-10-15T23:59:59Z"
  }
}

Error Response Sample​

{
  "error": {
    "code": "CWUM-04102",
    "message": "Invalid job status <Job Status> for the cancel operation."
  },
  "traceId": "7af4e84d-aac0-43a3-ba69-40a0347e9752"
}