Situational Awareness (Get Media)

The Situational Awareness API provides a link from which you can view a video or image captured by an asset (camera). This API is also referred to as the 'Get Media' API call.
There are two ways to retrieve media directly from the node:
  • By AssetUid for Image, or Video
  • By LocationUid for Image, or Video

Retrieve Media from Node by AssetUid for an Image or Video (Get Media)

When retrieving media directly from the node:
  1. Submit the HTTPS request. You will receive an imagePollURL or videoPollURL.
  2. Submit the imagePollURL or videoPollURL.
    • The message “Success” displays if the media file you requested is in the database.
    • If the requested file is not in the database, it will retrieve the file directly from the node.
      Note: The timestamp needs to match the request exactly, up to the millisecond.
    • The message "InProgress" displays if the media file is not in the database; there is no timeout or error message. The recommendation is setting the application with a timeout of five minutes, but you have the flexibility to choose whatever timeout period you want.
      Note: Media is retained by the node and available for seven days. If the requested media is older than seven days and is found in the cloud database, the PollURL provides the requested media.
METHOD GET
URI {{mediaurl}}/ondemand/assets/{assetUid}/media?mediaType={mediaType1}&timestamp={timestamp}&page={int}&size={int}&sortBy={string}&sortDir={string}&duration={int}
Sample Request URI {{mediaurl}}/ondemand/assets/CAMERA-STG-HYP1071-CAM-F/media?mediaType=VIDEO&timestamp=1459816592758&page=0&size=100&sortBy=mediaLogId&sortDir=DESC&duration=15

Query Parameters

Parameter Description Required? Filter Values
assetUid GE identifier for the media device Yes Unique identifiers such as CAMERA-STG-HYP1071-CAM-F for Image or Video.
mediaType Filter by type of media.
Note: 'Get Media' only works when you have access to Situational Awareness.
Yes See the enumeration codes for mediaType in the Glossary for Intelligent Cities.
timeStamp Time of the event, recorded in EPOCH format. Yes Numerical value, such as 1453772603879.
sortBy The value to sort the content of the response by. No See the enumeration codes for sortBy in the Glossary for Intelligent Cities.
size Maximum number of records to return per page; if none specified, the default value of 2 is used automatically. No Numerical value, such as 20.
page Indicates the page number; default is 0. No Numerical value, such as 1.
sortDir Indicates whether to sort in ascending or descending order No Numerical value.
duration Indicates duration of the event. No Numerical Value.

Retrieve Media from Node by LocationUid for an Image or Video

METHOD GET
URI {{mediaurl}}/v2/mediastore/ondemand/locations/{locationUid}/media?mediaType={mediaType1}&timestamp={timestamp}&page={int}&size={int}&sortBy={string}&sortDir={string}&duration={int}
Sample Request URI {{mediaurl}}/v2/mediastore/ondemand/locations/LOCATION-STG-282/media?mediaType=IMAGE&timestamp=1459816592756&page=0&size=100&sortBy=mediaLogId&sortDir=DESC&duration=15

Query Parameters

Parameter Description Required? Filter Values
locationUid A unique identifier established by a customer or external resource for a specific location within the monitored area Yes Unique identifier such as LOCATION-STG-282.
mediaType Filter by type of media.
Note: 'Get Media' only works when you have access to Situational Awareness.
Yes See the enumeration codes for mediaType in the Glossary for Intelligent Cities.
timeStamp Time of the event, recorded in EPOCH format. Yes Numerical value, such as 1453772603879.
sortBy The value to sort the content of the response by. No See the enumeration codes for sortBy in the Glossary for Intelligent Cities.
size Maximum number of records to return per page; if none specified, the default value of 2 is used automatically. No Numerical value, such as 20.
page Indicates the page number; default is 0. No Numerical value, such as 1.
sortDir Indicates whether to sort in ascending or descending order No Sort value.

Retrieve Media from Node by AssetUid for an Image or Video

METHOD GET
URI <production url>/v2/mediastore/ondemand/assets/{assetUid}?mediaType={type}(timestamp,sort order,sort direction)
Sample Request URI <production url>/v2/mediastore/ondemand/assets/CAMERA-HYP1083-CAM-L?mediaType=IMAGE&timestamp=1459816592756&page=0&size=100&sortBy=mediaLogId&sortDir=DESC

Sample Response


{
  "imagepollUrl": "https://ic-media-service.run.asv-pr.ice.predix.io/v2/mediastore/ondemand/getMedia/34bad361-d59a-47f1-aa59-be17e8bc643a?page=0&size=100&sortBy=mediaLogId&sortDir=DESC"
}

Query Parameters

Parameter Description Required? Filter Values
assetUid GE identifier for the media device. Yes Unique identifier such as CAMERA-HYP1083-CAM-L.
mediaType Filter by type of media.
Note: 'Get Media' only works when you have access to Situational Awareness.
No See the enumeration codes for mediaType in the Glossary for Intelligent Cities.
timestamp Time of the event, recorded in EPOCH format. No Numerical value, such as 1453772603879.
sortBy The value to sort the content of the response by. No See the enumeration codes for sortBy in the Glossary for Intelligent Cities.
sortDir Indicates whether to sort in ascending or descending order No Numerical value.
Table 1. Response Parameters
Parameter Data Type Description
status String The status of the response, either INPROGRESS or SUCCESS.
listOfEntries String
mediaLogId
The ID of each entry in the list.
mediaUUId
The unique ID of the specific type of node.
mediaType
Either Image, or Video.
mediaFileName
The filename of the captured media.
mediaTimestamp
The time the media was captured from the node.
assetUid
The ID of the asset that captured the media.
externalRefId
The ID of the external reference.
entryTimestamp
The time the captured media was entered in the database.
url String URL Link to the stored media file in its captured format. For example, file types include: JPEG, PNG, MP4.

Sample Response



{
  "status": "INPROGRESS",
  "listOfEntires": null
}

{
  "status": "SUCCESS",
  "listOfEntires": {
    "content": [
      {
        "mediaLogId": 13,
        "mediaUUId": "GRC-NODE",
        "mediaType": "IMAGE",
        "mediaFileName": "CAMERA-HYP1083-CAM-L_CAMERA-HYP1083-CAM-L_1459816592756_IMAGE",
        "mediaTimestamp": 1459816592756,
        "assetUid": "CAMERA-HYP1083-CAM-L",
        "externalRefId": "CAMERA-HYP1083-CAM-L",
        "entryTimestamp": 1473294438424,
        "url": "https://ic-media-service.run.asv-pr.ice.predix.io/v2/mediastore/file/CAMERA-HYP1083-CAM-L_CAMERA-HYP1083-CAM-L_1459816592756_IMAGE.jpg"
      }
    ],
    "last": true,
    "totalPages": 1,
    "totalElements": 1,
    "first": true,
    "numberOfElements": 1,
    "sort": [
      {
        "direction": "DESC",
        "property": "mediaLogId",
        "ignoreCase": false,
        "nullHandling": "NATIVE",
        "ascending": false
      }
    ],
    "size": 100,
    "number": 0
  }
}