Skip to main content

API Examples

Create Imagery Insights APS Job​

  curl --location --request POST '{ADMA_INSTANCE_URL}/solutions/bayerAgPowered.imagery:create?api-version={ADMA_API_VERSION}' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "requestPath": "/v1/imagery-add-on/1234",
  "partnerRequestBody": {
      "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
      "sceneStartDateTime": "2023-01-01T00:00:00",
      "sceneEndDateTime": "2023-01-15T23:59:59",
      "collection": "sentinel-2-l2a",
      "layer": "SCOUTING_MAP",
      "resourceId": "dfa70d7c-5132-4949-bc2d-92906c838d22",
      "resourceType": "Field"
  }
}'

Create Job Response Sample​


{
  "id": "1234",
  "message": "IMG-01001: Job queued successfully.",
  "status": "WAITING",
  "jobCreatedDateTime": "2023-04-28T00:00:00Z",
  "jobLastActionDateTime": "2023-04-28T00:27:00Z",
  "e2eid": "a1853978d9ae412ccd55923ca41891c7",
  "partnerRequestBody": {
    "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
    "resourceId": "dfa70d7c-5132-4949-bc2d-92906c838d22",
    "resourceType": "Field",
    "collection": "sentinel-2-l2a",
    "layer": "SCOUTING_MAP",
    "sceneStartDateTime": "2023-01-01T00:00:00",
    "sceneEndDateTime": "2023-01-15T23:59:59"
  }
}

Fetch Imagery Insights APS Job Status​

Clients fetch the status of their submitted job using the Fetch Status endpoint. When a job is in a SUCCEEDED state, the response will provide the Insight ID which can be used to retrieve the outputs of the job. Please review Retrieve APS Outputs for details.

Possible status values are: WAITING, RUNNING, SUCCEEDED, FAILED, CANCELLED

curl --location --request POST '<ADMA Instance URL>/solutions/bayerAgPowered.imagery:fetch?api-version=2022-11-01-preview' \
--header 'Authorization: Bearer <JWT>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "requestPath":"/v1/imagery-add-on/1234"
}'

Fetch Job Status Response Sample​

{
  "id": "1234",
  "message": "IMG-02001: Job is completed successfully",
  "status": "SUCCEEDED",
  "jobCreatedDateTime": "2023-04-28T00:00:00Z",
  "jobProcessingStartDateTime": "2023-04-28T00:05:00Z",
  "jobProcessingEndDateTime": "2023-04-28T00:27:00Z",
  "jobLastActionDateTime": "2023-04-28T00:27:00Z",
  "jobProcessingDurationInSeconds": 22,
  "e2eid": "a1853978d9ae412ccd55923ca41891c7",
  "partnerRequestBody": {
    "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
    "collection": "sentinel-2-l2a",
    "layer": "SCOUTING_MAP",
    "sceneStartDateTime": "2023-01-01T00:00:00",
    "sceneEndDateTime": "2023-01-15T23:59:59",
    "resourceId": "dfa70d7c-5132-4949-bc2d-92906c838d22",
    "resourceType": "Field"
  }
}

Cancel Imagery Insights APS Job​

Jobs can only be cancelled if they are in a cancellable state: WAITING or RUNNING.

curl --location --request POST '{ADMA_INSTANCE_URL}/solutions/bayerAgPowered.imagery:cancel?api-version={ADMA_API_VERSION}' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "requestPath":"/v1/imagery-add-on/1234"
}'

Cancel Job Response Sample​

{
  "id": "1234",
  "message": "IMG-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": {
    "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
    "collection": "sentinel-2-l2a",
    "layer": "SCOUTING_MAP",
    "sceneStartDateTime": "2023-01-01T00:00:00",
    "sceneEndDateTime": "2023-01-15T23:59:59",
    "resourceId": "dfa70d7c-5132-4949-bc2d-92906c838d22",
    "resourceType": "Field"
  }
}

Insight Attachments API: Get Outputs​

The Imagery Service produces image files in TIFF format and metadata that are written to the ADMA Tenant of the job submittor. In order to download those files to a separate location, the ADMA Insight Attachment API is used.

Get the list of Insight Attachments​

Request Sample​

curl --location --request GET '{ADMA_INSTANCE_URL}/parties/{PARTY_ID}/models/bayerAgPowered.
imagery/resource-types/Field/resources/
{FIELD_ID}/insight-attachments?api-version={ADMA_API_VERSION}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {TOKEN}'

The partyId and fieldId parameters are the same as the ones used when requesting the image in the PUT request. This endpoint will return a list of Insight Attachments with the following format:

Response Sample​

{
  "value": [
    {
      "insightId": "2110_461",
      "modelId": "bayerAgPowered.imagery",
      "originalFileName": "SCOUTING_MAP-aa1aa11a-u579-0e3k-w13k-89pr45gv45j2.png",
      "id": "a5bf6ad6-f378-47d0-929c-9ba437322c8e",
      ...
    },
    {
      "insightId": "2110_461",
      "modelId": "bayerAgPowered.imagery",
      "originalFileName": "SCOUTING_MAP-metadata-aa1aa11a-u579-0e3k-w13k-89pr45gv45j2.json",
      "id": "44a2c120-3ce2-4533-a4fe-a7791efb358f",
      ...
    },
    ...
  ]
}

The insightId matches the provided job id in the PUT request described above. Associated with an insightId there are attachment ids (named simply id). There is one attachment id for the png file, and one attachment id for the json file containing the metadata.

This endpoint returns all the insight attachments available for the specified field, even the ones generated by old job executions. If there are more than 50 attachments the endpoint will return only the first page with 50, and it will include a "nextLink" attribute that can be used to fetch the next page.

If you want to retrieve only the insight attachments created by a specific job execution, you can add the job id in the insightIds query parameter.

Insight attachments requests can include any number of jobs.

Get the Generated Image​

Request Sample​

curl --location --request GET '{ADMA_INSTANCE_URL}/parties/{PARTY_ID}/models/bayerAgPowered.
imagery/resource-types/Field/resources/
{FIELD_ID}/insight-attachments/{ID}/file?api-version={ADMA_API_VERSION}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {TOKEN}'

The id property from the previous step that corresponds to the file "{IMAGERY_LAYER}-{FIELD_ID}.png" will be used to get the final image.

Get the Generated Metadata​

Request Sample​

curl --location --request GET '{ADMA_INSTANCE_URL}/parties/{PARTY_ID}/models/bayerAgPowered.
imagery/resource-types/Field/resources/
{FIELD_ID}/insight-attachments/{ID}/file?api-version={ADMA_API_VERSION}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {TOKEN}'

Similar to the previous step, the id property that corresponds to the file "{IMAGERY_LAYER}-metadata-{FIELD_ID}.json" will be used to get the metadata file.

As a result of this endpoint call, the customer will get a metadata file like this:

Response Sample​

{
  "metadata": {
    "legend": [
      {
        "value": 0.5234718000675448,
        "unit": "percentage",
        "color": "f40000",
        "rank": 1,
        "biomass": "Lowest"
      },
      {
        "value": 14.396881684115726,
        "unit": "percentage",
        "color": "fff685",
        "rank": 2,
        "biomass": ""
      },
      {
        "value": 14.264606551840595,
        "unit": "percentage",
        "color": "befc98",
        "rank": 3,
        "biomass": ""
      },
      {
        "value": 11.402397838568051,
        "unit": "percentage",
        "color": "00cb00",
        "rank": 4,
        "biomass": ""
      },
      {
        "value": 5.060227400652932,
        "unit": "percentage",
        "color": "006400",
        "rank": 5,
        "biomass": "Highest"
      }
    ],
    "totalArea": {
      "value": 152,
      "unit": "Acre"
    },
    "cloudFreePercentage": 100,
    "satelliteImageryDate": "2022-10-11",
    "satelliteImageryCollection": "SENTINEL_2_L1C",
    "sceneId": "716a0b03-dc23-4d9e-8e33-69e2ea7fde10",
    "areasSplit": [
      {
        "zone": 1,
        "rank": 1,
        "area": 0.7956771361026681,
        "percentage": 0.5234718000675448
      },
      {
        "zone": 2,
        "rank": 2,
        "area": 21.8832601598559,
        "percentage": 14.396881684115726
      },
      {
        "zone": 3,
        "rank": 3,
        "area": 21.682201958797705,
        "percentage": 14.264606551840595
      },
      {
        "zone": 4,
        "rank": 4,
        "area": 17.331644714623437,
        "percentage": 11.402397838568051
      },
      {
        "zone": 5,
        "rank": 5,
        "area": 7.691545648992458,
        "percentage": 5.060227400652932
      }
    ],
    "totalZones": 5
  }
}