Add Layer | ArcGIS REST APIs

URL:: https://<root>/services/serviceName/addLayer
Methods:: POST
Version Introduced:: 12.0

Description

The addLayer operation adds additional layers to an existing video service. The addLayer operation is performed on a video service resource. Video services can be created manually via the portal Sharing REST API as seen in the Portal Sharing REST API documentation. Note that the created service must be set to the videoService output type and must have a value specified for the serviceName property. For example:

Use dark colors for code blocksCopy
{"serviceName":"sampleServiceName"}

Request parameters

Parameter Details

Parameter	Details
`createParameters`	Note The required `createParameters` properties for the `addLayer` operation differ depending upon the value specified for the `type` property. A JSON object specifying the properties of the newly created service. See the Properties for Create Parameters section below for more information.
`f` (Required)	The response format. The default format is `html`. Values: `html` \| `json` \| `pjson`
`token`	Users interacting programmatically with this endpoint must generate a token that must be included as a request parameter. A token can be obtained using the Generate Token operation.

createParameters

A JSON object specifying the properties of the newly created service. See the Properties for Create Parameters section below for more information.

f

(Required)

The response format. The default format is html.

Values: html | json | pjson

token

Users interacting programmatically with this endpoint must generate a token that must be included as a request parameter. A token can be obtained using the Generate Token operation.

Properties for Create Parameters

Parameter Details

Parameter	Details
`type` (Required)	The type of layer being added. The type specified by this property must match the parent service's type otherwise the request will be rejected. Values: `ondemand` \| `livestream`
`name` (Required)	The name for the new layer. The minimum requirement for the `name` property is that the provided string is not null and has a character length greater than zero. For example, the `name` property could be `sample_Service_Name`.
`mode` (Required for `livestream` layer type)	The type of livestream being added as a layer. This property is only applicable to `livestream` layer type. The `ondemand` layer type does not use this property. Values: `server` \| `client`
`streamAddress` (Required for `livestream` layer type)	The URI for the livestream being added as a layer. The format of this URI must match the format expected of the selected `mode`. For example, an RTSP livestream will begin with `rtsp://`, while a SRT livestream will begin with `srt://`. The following is an example stream address for an RTSP stream: Use dark colors for code blocksCopy `1 "rtsp://0.0.0.0:8554/live"`
`inputs` (Required)	A JSON objects that contains information about the layer's data source. The JSON object supports the following properties, the use of which depends on the layer type: `fileIds` - A comma-separated list of file IDs, used for `ondemand` layer types. The IDs can be retrieved using the Uploads operation. `streamUrl` - Specifies a livestream URL, used for `livestream` layer types. `stores` - By default, Video Server will reference data in the default data store. If referenced data is in a non-default data store, this property specifies the ID of the data store using the `dataStoreId` nested property. If a cloud store is being used, the `paths` nested property should also be used to list files that can be used to create layers. This property is optional unless a non-default data store needs to be used. `cameraInfo` - The accepted input of this property is a JSON object that contains the following sub-properties: `extent`, `position`, `heading`, `tilt`, and `fov`. These define the properties of the camera used to record a video and are used to build the footprint used by Video Server. `elevationSourceItemId` - References a portal imagery layer that is used while processing the video. This is an optional property. Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 13 "inputs":{ "fileIds": "i613add7d-0621-4842-8ea0-79b4cc2751b8", "elevationSourceItemId": "e0111c1fc4f24e3c9366120f23a2272c" "cameraInfo": { "position":{ "x": -122.9019437, "y": 47.05092872, "height": 40, "farDistance": 300, "tilt":0 } } }`
`id` (Optional)	The id of a layer. If not specified, it will default based upon the number of layers in the service.
`livebuffersize` (Optional)	A buffer time can be chosen to force a buffer period between the start time of the livestream and the real-time position of the video. For example, there can be a thirty second buffer period at the beginning of the video. This parameter expects an integer equating to the buffer time in seconds.
`start` (Optional for `livestream` layer type, unused by `ondemand`)	Defines the start mechanism for the livestream feed. This can be `auto` to start the livestream on the back-end automatically, or `request` to wait for an administrator to click Start Livestream. Values: `auto` \| `request`
`stop` (Optional for `livestream` layer type, unused by `ondemand`)	Defines the stop mechanism for the livestream feed. This can be `auto` to stop the livestream on the back-end automatically when the livestream ends, or `request` to wait for an administrator to click Stop Livestream. Values: `auto` \| `request`
`copyrightText` (Optional)	Specifies any copyright text, which will be included as part of the layer's metadata.
`description` (Optional)	A string that defines the layer's contents.
`cameraInfo` (Optional)	The `cameraInfo` property sets information relevant to the camera used to record a given video; this information is then used to build the footprint created by Video Server. The accepted input of this property is a JSON object that contains the following sub-properties: `extent` `position` `heading` `tilt` `fov` For more information on the values above, see the Update Camera endpoint documentation.
`requestedResolution` (Optional)	The desired video resolution for the layer being created. Multiple resolution options can be specified. For `ondemand` layers, the maximum available resolution will be the native resolution of the video file. `livestream` layers will automatically pull the native resolution of the incoming livestream. Values: `native` \| `sd` \| `hd` \| `fhd`
`recordStream` (Optional)	If enabled, records the livestream as it plays, allowing for the (Convert to On-Demand)[/process] operation to take place when the stream ends. Values: `true` \| `false`

type

(Required)

The type of layer being added. The type specified by this property must match the parent service's type otherwise the request will be rejected.

Values: ondemand | livestream

name

(Required)

The name for the new layer. The minimum requirement for the name property is that the provided string is not null and has a character length greater than zero. For example, the name property could be sample_Service_Name.

mode

(Required for livestream layer type)

The type of livestream being added as a layer. This property is only applicable to livestream layer type. The ondemand layer type does not use this property.

Values: server | client

streamAddress

(Required for livestream layer type)

The URI for the livestream being added as a layer. The format of this URI must match the format expected of the selected mode. For example, an RTSP livestream will begin with rtsp://, while a SRT livestream will begin with srt://. The following is an example stream address for an RTSP stream:

Use dark colors for code blocksCopy
  "rtsp://0.0.0.0:8554/live"

inputs

(Required)

A JSON objects that contains information about the layer's data source. The JSON object supports the following properties, the use of which depends on the layer type:

fileIds - A comma-separated list of file IDs, used for ondemand layer types. The IDs can be retrieved using the Uploads operation.
streamUrl - Specifies a livestream URL, used for livestream layer types.
stores - By default, Video Server will reference data in the default data store. If referenced data is in a non-default data store, this property specifies the ID of the data store using the dataStoreId nested property. If a cloud store is being used, the paths nested property should also be used to list files that can be used to create layers. This property is optional unless a non-default data store needs to be used.
cameraInfo - The accepted input of this property is a JSON object that contains the following sub-properties: extent, position, heading, tilt, and fov. These define the properties of the camera used to record a video and are used to build the footprint used by Video Server.
elevationSourceItemId - References a portal imagery layer that is used while processing the video. This is an optional property.

Use dark colors for code blocksCopy
"inputs":{
  "fileIds": "i613add7d-0621-4842-8ea0-79b4cc2751b8",
  "elevationSourceItemId": "e0111c1fc4f24e3c9366120f23a2272c"
  "cameraInfo": {
        "position":{
        "x": -122.9019437,
        "y":  47.05092872,
        "height": 40,
        "farDistance": 300,
        "tilt":0
      }
  }
}

id

(Optional)

The id of a layer. If not specified, it will default based upon the number of layers in the service.

livebuffersize

(Optional)

A buffer time can be chosen to force a buffer period between the start time of the livestream and the real-time position of the video. For example, there can be a thirty second buffer period at the beginning of the video. This parameter expects an integer equating to the buffer time in seconds.

start

(Optional for livestream layer type, unused by ondemand)

Defines the start mechanism for the livestream feed. This can be auto to start the livestream on the back-end automatically, or request to wait for an administrator to click Start Livestream.

Values: auto | request

stop

(Optional for livestream layer type, unused by ondemand)

Defines the stop mechanism for the livestream feed. This can be auto to stop the livestream on the back-end automatically when the livestream ends, or request to wait for an administrator to click Stop Livestream.

Values: auto | request

copyrightText

(Optional)

Specifies any copyright text, which will be included as part of the layer's metadata.

description

(Optional)

A string that defines the layer's contents.

cameraInfo

(Optional)

The cameraInfo property sets information relevant to the camera used to record a given video; this information is then used to build the footprint created by Video Server. The accepted input of this property is a JSON object that contains the following sub-properties:

extent
position
heading
tilt
fov

For more information on the values above, see the Update Camera endpoint documentation.

requestedResolution

(Optional)

The desired video resolution for the layer being created. Multiple resolution options can be specified. For ondemand layers, the maximum available resolution will be the native resolution of the video file. livestream layers will automatically pull the native resolution of the incoming livestream.

Values: native | sd | hd | fhd

recordStream

(Optional)

If enabled, records the livestream as it plays, allowing for the (Convert to On-Demand)[/process] operation to take place when the stream ends.

Values: true | false

Importing an existing feature layer from portal

ArcGIS Video Server has the ability to import the data from an existing feature layer located on a portal. This allows users to utilize data from feature layers which may already be involved in workflows on the portal, while simultaneously utilizing the benefits of a video service.

Create parameter properties for importing a feature layer

Parameter	Details
`featureService` (Required)	This is the primary property required for importing a feature layer. It will need to be nested inside of an `inputs` parameter, as shown in the below examples. All following properties will be located inside the `featureService` JSON object.
`itemId` (Required)	The item ID of the feature service. This can be found in the item's Item Details page in the portal, or by viewing the item in the Portal Directory API.
`layerId` (Required)	This is the layer ID of the specific layer within the related feature service being imported.
`objectIds` (Required)	A comma delimited list of object IDs within the imported feature service. Use dark colors for code blocksCopy `1 "objectIds": "0,1,3,4",`
`where` (Required)	The `where` parameter is utilized as a query to determine which layers are being imported. For example, `height < 40` would check the height field, compare to the input value, and only import fields with a height value lower than 40. Additional information regarding queries can be found in the layer-level Query.
`fieldMap` (Required)	The `fieldMap` property is utilized to map the fields found in a feature layer to the appropriate fields for a video service's `cameraInfo`. For example, if we want to have a field titled "name" and we need it to be based off of a `location` field in the original feature layer, it would be specified as `"name":"location"`.

Example `addLayer` JSON

The following are sample createParameters JSON objects that can be included in a request to the addLayer operation. Because the provided properties vary based on the type of layer, the following samples cover the two types.

Publishing on-demand layers can be done using files uploaded locally via the Uploads endpoint or a cloud store registered with the Video Server. The first example uses an uploaded file ID, while the second uses the file ID of a video stored on a registered cloud store.

Use dark colors for code blocksCopy
{
  "type" : "ondemand",
  "name" : "on_demand_sample",
  "requestedResolutions" : "sd, hd, fhd",
  "inputs" : {
     "fileIds" : "i96f7ddf8-5b1a-420d-991e-83d50a65e23a",
    }
}

Use dark colors for code blocksCopy
{
  "name": "sample_data_store_layer",
  "type": "ondemand",
  "inputs" : {
     "stores" : [
        {
           "datastoreId" : "03938eda57c44b0aa859e4cb9a29e5d3",
           "paths" : [
     "filename.ts"
           ]
        }
]
  }
}

Note that the stores property uses a JSON array that specifies the appropriate cloud stores. TheDescribe endpoint can be used to view the directories and find the values for the datastoreId and paths properties.

Use dark colors for code blocksCopy
{
       "mode": "server",
       "name": "RTSP_Server_Mode_Layer",
       "recordStream": true,
       "start": "auto",
       "stop": "auto",
       "type": "livestream"
       "bufferSize": 10,
  "inputs": {
        "streamUrl":"rtsp://225.10.10.10:8554/out",
		"cameraInfo": {
        "x": -122.9019437,
        "y":  47.05092872,
        "height": 40,
        "farDistance": 300,
        "tilt":0
        },
        "elevationSourceItemId": "1234",
        "protocol": "rtsp"
     }
}

Use dark colors for code blocksCopy
{
       "mode": "server",
       "name": "RTSP_Server_Mode_Layer",
       "recordStream": true,
       "start": "auto",
       "stop": "auto",
       "bufferSize": 10,
       "type":"livestream",
  "inputs": {
          "ip": "224.0.0.0",
          "port": 8554,
          "protocol": "rtsp"
     }
}

Use dark colors for code blocksCopy
{
       "mode": "server",
       "name": "UDP_Multicast_Layer",
       "recordStream": true,
       "start": "auto",
       "stop": "auto",
       "type": "livestream"
       "bufferSize": 10,
 "inputs": {
		"cameraInfo": {
        "x": -122.9019437,
        "y":  47.05092872,
        "height": 40,
        "farDistance": 300,
        "tilt":0
        },
          "elevationSourceItemId": "1234",
          "ip": "224.0.0.0",
          "port": 54876,
          "protocol": "udp"
   }
}

Use dark colors for code blocksCopy
{
       "mode": "Multicast",
       "name": "UDP_Multicast_Layer",
       "recordStream": true,
       "start": "auto",
       "stop": "auto",
       "type": "livestream",
       "bufferSize": 10,
 "inputs": {
		"cameraInfo": {
        "x": -122.9019437,
        "y":  47.05092872,
        "height": 40,
        "farDistance": 300,
        "tilt":0
        },
         "streamUrl":"udp://225.10.10.10:9000"
   }
}

To import existing feature layers from a portal, create a new video service using the Portal Directory API's Create Service operation. The itemId of the feature layer can be acquired from the item's Item Details page in the portal. The where property can be used to specify which layers are imported, along with the layerId property. Use the fieldMap property to adjust fields to the appropriate names as needed.

Use dark colors for code blocksCopy
{
  bufferSize: 10,
  inputs: {
    "featureService": {
      "itemId": "d026d19fe83743e89c9fa4e8210c022e",
      "layerId": "0",
      "where": "Camera_Height < 50",
      "fieldMap": {
        "fov": {"fieldName": "Camera_HFOV"},
        "heading": {"fieldName": "Camera_Direction"},
        "height": {"fieldName": "Camera_Height"},
        "tilt": {"fieldName": "Camera_Angle"},
"streamUrl": {"fieldName":"url"}
      }
    }
  },
  mode: "client",
  name: "My Cameras Layer",
  recordStream: false,
  start: "auto",
  stop: "auto",
  type: "livestream"
}

Use dark colors for code blocksCopy
{
  "mode": "client",
  "name": "sample_feature_layer_import",
  "recordStream": false,
  "start": "auto",
  "stop": "auto",
  "type": "livestream"
  "bufferSize": 10,
  "inputs": {
    "elevationSourceItemId": "1234",
    "featureService": {
      "itemId": "xyzAb123",
      "layerId": "0",
      "objectIds": "1,20,22,25",
      "where": "height > 50",
      "fieldMap": {
        "streamUrl": {"fieldName": "streamUrl"},
        "farDistance": {"fieldName": null},
        "fov": {"fieldName": "Camera_HFOV"},
        "heading": {"fieldName": "Camera_Direction"},
        "height": {"fieldName": "Camera_Height"},
        "tilt": {"fieldName": "Camera_Angle"}
      }
    }
  }
}

Use dark colors for code blocksCopy
{
  "mode": "client",
	"name": "sample_livestream_layer",
	"recordStream": true,
        "start": "auto",
        "stop": "auto"
	"type": "livestream",
	"bufferSize": 10,
	"inputs": {
		"cameraInfo": {
        "x": -122.9019437,
        "y":  47.05092872,
        "height": 40,
        "farDistance": 300,
        "tilt":0
        },
		"streamUrl": "https://test-url.com/m3u8"
	}
}

Use dark colors for code blocksCopy
{
       "name": "external_MP4_url_test",
       "type": "livestream",
       "mode": "client",
       "inputs": {
        "streamUrl": "https://webserver/files/videos/myvideo.mp4"
       },
       "cameraInfo": {
       "position":{
        "x": -122.9019437,
        "y":  47.05092872,
        "height": 40,
        "farDistance": 300,
        "tilt":0
        },
       },
              "elevationSourceItemId": "1234",
 }

Example usage

The following is a sample POST request for the addLayer operation:

Use dark colors for code blocksCopy
POST /rest/services/sampleService/VideoServer/addLayer HTTP/1.1
Host: organization.example.com:21443
Content-Type: application/x-www-form-urlencoded
Content-Length: [ ]

createParameters={
  "name": "TestODLayer_01",
  "type": "ondemand",
  "inputs": {
    "fileIds": "i9bc97626-b628-4bcc-9fe3-6314bb50c760",
    "cameraInfo": {
      "height": 45,
      "position": {"x":39.0256459,"y":-76.4362445},
      "heading": 17,
      "tilt": 50,
      "fov": 90,
      "farDistance": 45
    }
  }
}&f=pjson&token=<token>

JSON Response syntax

Use dark colors for code blocksCopy
{
    "jobId": "<jobId>",
    "success": <true | false>
    "error": { //only if success is false
      "code": <code>,
      "description": <description>
      }
}

JSON Response example

Use dark colors for code blocksCopy
{
    "jobId": "<jobId>",
    "success": <true>
}

Description

Request parameters

Properties for Create Parameters

Importing an existing feature layer from portal

Create parameter properties for importing a feature layer

Example addLayer JSON

Example usage

JSON Response syntax

JSON Response example

Example `addLayer` JSON