Skip to main content

API Examples

Create historical weather batch Job​

  curl --location --request POST '{ADMA_INSTANCE_URL}/solutions/bayerAgPowered.historicalWeather:create?api-version=
  {ADMA_API_VERSION}' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "requestPath": "/v1/historical-weather-data/05172024-004",
  "partnerRequestBody": {
      "interval": "daily",
      "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
      "jobs": [
          {
              "resourceType": "Field",
              "resourceId": "83b8f2b9-04b3-4462-ac52-9c821feb0ee21",
              "weatherStartDate": "2018-01-01",
              "weatherEndDate": "2018-04-30",
              "temperatureUnit": "C"
          }
      ]
  }
}'

Create batch job response Sample​


{
  "batchId": "05172024-004",
  "e2eId": "426",
  "interval": "DAILY",
  "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
  "jobs": [
    {
      "jobRequestBody": {
        "jobId": "1",
        "resourceId": "83b8f2b9-04b3-4462-ac52-9c821feb0ee21",
        "resourceType": "FIELD",
        "weatherStartDate": "2018-01-01",
        "weatherEndDate": "2018-04-30",
        "temperatureUnit": "C",
        "coordinates": {
          "lat": -35.9551252,
          "lng": -62.664814
        }
      },
      "message": "HWA-01001: Job queued successfully.",
      "status": "WAITING",
      "jobCreatedDateTime": "2024-06-12T15:44:26Z",
      "jobLastActionDateTime": "2024-06-12T15:44:26Z"
    }
  ]
}

Fetch batch job status​

Clients fetch the status of their submitted batch 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.historicalWeather:fetch?api-version=2023-11-01-preview' \
--header 'Authorization: Bearer <JWT>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "requestPath":"/v1/historical-weather-data/05172024-004"
}'

Fetch batch job status response sample​

{
  "batchId": "05172024-004",
  "e2eId": "426",
  "interval": "DAILY",
  "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
  "jobs": [
    {
      "jobRequestBody": {
        "jobId": "1",
        "resourceId": "83b8f2b9-04b3-4462-ac52-9c821feb0ee21",
        "resourceType": "FIELD",
        "weatherStartDate": "2018-01-01",
        "weatherEndDate": "2018-04-30",
        "temperatureUnit": "C",
        "coordinates": {
          "lat": -35.9551252,
          "lng": -62.664814
        }
      },
      "insightId": "2e130d6c-13ae-4e2e-875b-3a8f018f1ffd",
      "message": "HWA-02001: Job is completed successfully.",
      "status": "SUCCEEDED",
      "jobCreatedDateTime": "2024-06-12T15:44:26Z",
      "jobProcessingStartDateTime": "2024-06-12T15:44:27Z",
      "jobProcessingEndDateTime": "2024-06-12T15:44:51Z",
      "jobLastActionDateTime": "2024-06-12T15:44:51Z",
      "jobProcessingDurationInSeconds": 23
    }
  ]
}

Cancel historical weather batch 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.historicalWeather:cancel?api-version=
{ADMA_API_VERSION}' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "requestPath":"/v1/historical-weather-data/05172024-004"
}'

Cancel batch job response Sample​

{
  "batchId": "05172024-004",
  "e2eId": "426",
  "interval": "DAILY",
  "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
  "jobs": [
    {
      "jobRequestBody": {
        "jobId": "1",
        "resourceId": "83b8f2b9-04b3-4462-ac52-9c821feb0ee21",
        "resourceType": "FIELD",
        "weatherStartDate": "2018-01-01",
        "weatherEndDate": "2018-04-30",
        "temperatureUnit": "C",
        "coordinates": {
          "lat": -35.9551252,
          "lng": -62.664814
        }
      },
      "insightId": "2e130d6c-13ae-4e2e-875b-3a8f018f1ffd",
      "message": "HWA-02001: Job is completed successfully.",
      "status": "CANCELLED",
      "jobCreatedDateTime": "2024-06-12T15:44:26Z",
      "jobProcessingStartDateTime": "2024-06-12T15:44:27Z",
      "jobProcessingEndDateTime": "2024-06-12T15:44:51Z",
      "jobLastActionDateTime": "2024-06-12T15:44:51Z",
      "jobProcessingDurationInSeconds": 23
    }
  ]
}

Get historical weather output​

Historical Weather APS produces the weather insights as an attachment stored in a csv format.

Insight Attachments API: Get Outputs​

Historical Weather APS produces weather insights in csv format and its metadata in json format that are written to the ADMA Tenant of the batch job requester. 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.
historicalWeather/resource-types/Field/resources/
{FIELD_ID}/insight-attachments?api-version={ADMA_API_VERSION}&insightIds=${INSIGHT_ID}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {TOKEN}'

The PARTY_ID and FIELD_ID parameters are the same as the ones used when requesting the image in the PUT request and the 'INSIGHT_ID' is received in the Fetch response. This endpoint will return a list of Insight Attachments with the following format:

Response Sample​

{
  "value": [
    {
      "insightId": "4e010964-2af7-4113-9e33-24f5abed6e6c",
      "modelId": "bayerAgPowered.historicalWeather",
      "resourceType": "Field",
      "resourceId": "83b8f2b9-04b3-4462-ac52-9c821feb0ee21",
      "originalFileName": "hwa-data.csv",
      "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
      "id": "a7b0e278-3a54-4d38-a2d1-c1bf3d6e42d6",
      "createdDateTime": "2024-06-18T05:25:14Z",
      "modifiedDateTime": "2024-06-18T05:25:14Z",
      "createdBy": "b71af71a-da8a-4d3d-95de-615bc1c6ef1f",
      "modifiedBy": "b71af71a-da8a-4d3d-95de-615bc1c6ef1f",
      "eTag": "3b04aa4b-0000-0100-0000-66711a3a0000"
    },
    {
      "insightId": "4e010964-2af7-4113-9e33-24f5abed6e6c",
      "modelId": "bayerAgPowered.historicalWeather",
      "resourceType": "Field",
      "resourceId": "83b8f2b9-04b3-4462-ac52-9c821feb0ee21",
      "originalFileName": "hwa-metadata.json",
      "partyId": "53b8f2b9-04b3-4462-ac52-9c821feb0ee2",
      "id": "d7185e88-ce47-49c3-a755-901cac6ecc39",
      "createdDateTime": "2024-06-18T05:25:15Z",
      "modifiedDateTime": "2024-06-18T05:25:15Z",
      "createdBy": "b71af71a-da8a-4d3d-95de-615bc1c6ef1f",
      "modifiedBy": "b71af71a-da8a-4d3d-95de-615bc1c6ef1f",
      "eTag": "3b04d54b-0000-0100-0000-66711a3b0000"
    }
  ]
}

There will be two attachments (hwa-data.csv : csv file containing the weather data and hwa-metadata.json : json file containing the metadata).

Get the generated weather data csv attachment​

The id property from the previous step that corresponds to the file "hwa-data.csv" will be used to get the weather data generated. CSV file column names : avgAtmosPressure,avgWindSpeed,maxAtmosPressure,maxTemp,maxWindSpeed,minAtmosPressure,minTemp,minWindSpeed,totalPrecipitation,weatherDate

Request Sample​

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

Get the generated Metadata json attachment​

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

Request Sample​

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

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

Response Sample​

{
  "weatherStartDate": "2018-01-01",
  "weatherEndDate": "2018-04-30",
  "temperatureUnit": "C",
  "interval": "DAILY",
  "coordinates": {
    "lat": -35.9551252,
    "lng": -62.664814
  },
  "historicalWeatherDataAttributes": [
    {
      "avgAtmosPressure": {
        "description": "Average atmospheric pressure registered for that day",
        "unit": "Millibars (mb)",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "avgWindSpeed": {
        "description": "Average wind speed registered for that day",
        "unit": "Meters per hour (mph)",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "maxAtmosPressure": {
        "description": "Maximum atmospheric pressure registered for that day",
        "unit": "Millibars (mb)",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "maxTemp": {
        "description": "Maximum temperature registered for that day",
        "unit": "Celsius degrees",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "maxWindSpeed": {
        "description": "Maximum wind speed registered for that day",
        "unit": "Meters per hour (mph)",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "minAtmosPressure": {
        "description": "Minimum atmospheric pressure registered for that day",
        "unit": "Millibars (mb)",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "minTemp": {
        "description": "Minimum temperature registered for that day",
        "unit": "Celsius degrees",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "minWindSpeed": {
        "description": "Minimum wind speed registered for that day",
        "unit": "Meters per hour (mph)",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "totalPrecipitation": {
        "description": "Total precipitation registered during the day",
        "unit": "Millimeters (mm)",
        "availability": "Always (for Daily intervals)"
      }
    },
    {
      "weatherDate": {
        "description": "Date of this weather data",
        "unit": "Date",
        "availability": "Always (for Daily intervals)"
      }
    }
  ]
}