ORB360 DAM DOCS
HomeLogin
  • ๐Ÿš€Getting Started
  • EMBED
    • Single 360 - Hosted
    • Multiple 360 - Hosted
    • Advanced 360 - Hosted
    • 360 Player - Custom
  • API REFERENCE
    • Introduction
    • Specification
    • Authentication
  • ENDPOINTS
    • Integration
    • Integration - JOOR
    • Tenant
    • Shoot
    • Media
    • Tag
    • Image
Powered by GitBook
On this page

Was this helpful?

  1. ENDPOINTS

Integration

PreviousAuthenticationNextIntegration - JOOR

Last updated 1 year ago

Was this helpful?

The Integrations API enables you to request 360s which were taken by our capture teams and are stored within our ORB360ยฐ Digital Asset Management Service.

It supports the ability to query for media by id or tag, and supports complex integration options.

These endpoints are intended for advanced use, please visit the quickstart guide for general use and embed assistance.

  • POSTFind By Id
  • POSTFind By Tag

Find By Id

post

The findById endpoint only allows access to media contained within a shoot which has been enabled for integration access and has been published.

Login to the ORB360 management interface to confirm your shoot's integration settings. Please contact your ORB360 account manager to request that integrations are enabled

Endpoint Remarks

  • Each request is limited to a single designer (tenant).
  • Multiple media items can be requested by passing additional media ids into the media array.
  • Media id queries are limited to a maximum of 50 unique ids per request. (Duplicates will throw a 400 validation error)

Displaying the 360s

The images array returned in the response can be passed directly to our interactive player (ORB360Embed) during initialisation to allow for hassle free display of the 360's in HTML based content.

Authorizations
Query parameters
videosV2booleanOptional

Query parameter specifies to use the new videos response version (V2), this new version includes support for multiple sources of the same width and also the inclusion of M3U8 video streams for VIDEO media types.

The query parameter provides a tempoary migration path to allow for the gradual migration to the new response type without breaking chnages.

Note: v2 response type will become the default in the future, so all new implementations should set this property to true, to avoid future breaking changes.

Default: falseExample: true
Body
tenantstringOptional

The unique identifier for the requested tenant (uuid)

Example: fdb67f2e-219d-4771-b14f-a2ddc24b812b
mediastring[]Optional

Array of unique media identifiers (min: 1, max: 50)

Example: daea0774-275b-4e43-9d10-c2f9d5d4d5b6
Responses
200
success
application/json
Responseall of
400
bad request
application/json
401
unauthorized
application/json
403
forbidden
application/json
404
not found
application/json
post
POST /api/integrations/apiKey/findById HTTP/1.1
Host: api.orb360.tech
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "tenant": "fdb67f2e-219d-4771-b14f-a2ddc24b812b",
  "media": [
    "daea0774-275b-4e43-9d10-c2f9d5d4d5b6"
  ],
  "resolution": {
    "image": [
      {
        "width": 800
      },
      {
        "width": 1600
      }
    ]
  },
  "formats": {
    "image": {
      "type": "webp"
    }
  }
}
{
  "images": [
    {
      "media": {
        "id": "daea0774-275b-4e43-9d10-c2f9d5d4d5b6",
        "meta": {
          "boxerTenantId": "fdb67f2e-219d-4771-b14f-a2ddc24b812b",
          "from": "boxer",
          "type": "360_V2",
          "frames": 72,
          "shootId": "683606ee-9788-4d88-adb8-77119de4c6a2"
        },
        "tags": {
          "ANY_ADDITIONAL_PROPERTY": [
            "12345$BLACK"
          ]
        },
        "version": 123,
        "dateCreated": 1594988393066,
        "dateUpdated": 1594988393066
      },
      "type": "SINGLE_IMAGE",
      "baseURL": "https://cdn.orb360.tech/image/b1a213d6-8559-45f7-86da-088e6a85d86c/shoots/5b608121-c7b6-4a36-ac2a-54da43d869a2/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3/",
      "sizes": {
        "ImageWidth": {
          "urls": [
            "800_9fb29dc6a2edc54f2a9851d6bdc23e5df87220fa/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3-800.jpg?fmt=webp&w=150&s=5c1b7bbeec44a9fa61824b3f6964ece3e419b1fae73855cc97c19b2ea8977ac2"
          ]
        }
      }
    }
  ],
  "videos": [
    {
      "media": {
        "id": "daea0774-275b-4e43-9d10-c2f9d5d4d5b6",
        "meta": {
          "boxerTenantId": "fdb67f2e-219d-4771-b14f-a2ddc24b812b",
          "from": "boxer",
          "type": "360_V2",
          "frames": 72,
          "shootId": "683606ee-9788-4d88-adb8-77119de4c6a2"
        },
        "tags": {
          "ANY_ADDITIONAL_PROPERTY": [
            "12345$BLACK"
          ]
        },
        "version": 123,
        "dateCreated": 1594988393066,
        "dateUpdated": 1594988393066
      },
      "type": "360_V2",
      "formats": {
        "mp4": {
          "baseURL": "https://ordre-media-dev.s3.eu-west-1.amazonaws.com/b1a213d6-8559-45f7-86da-088e6a85d86c/shoots/5b608121-c7b6-4a36-ac2a-54da43d869a2/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3/",
          "sizes": {
            "ImageWidth": [
              {
                "filesize": 4303059,
                "file": "800_6677d7dfc0454b958c9a15b38f444885/1e81d25b-fc79-4ab0-9e3e-5476353e3e76-800.mp4",
                "url": "800_6677d7dfc0454b958c9a15b38f444885/1e81d25b-fc79-4ab0-9e3e-5476353e3e76-800.mp4",
                "durationSecs": 4,
                "resolution": {
                  "width": 800,
                  "height": 1200
                }
              }
            ]
          }
        },
        "m3u8": {
          "baseURL": "https://cdn.orb360.tech/assets/b1a213d6-8559-45f7-86da-088e6a85d86c/shoots/5b608121-c7b6-4a36-ac2a-54da43d869a2/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3/",
          "m3u8Index": "https://cdn.orb360.tech/m3u8/b1a213d6-8559-45f7-86da-088e6a85d86c/shoots/5b608121-c7b6-4a36-ac2a-54da43d869a2/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3/index.m3u8",
          "sizes": {
            "ImageWidth": [
              {
                "resolution": {
                  "width": 800
                },
                "audio": {
                  "codec": "acc"
                },
                "video": {
                  "bitRate": 3000,
                  "chunkSize": 4,
                  "codec": "h264",
                  "crf": 20,
                  "keyframe": 48,
                  "profile": "main"
                },
                "size": 4303059,
                "chunks": 4303059,
                "file": "v1_800_h264_main_crf20_c4_2675k_beaffc7602c8cba3dd970e52ee38f366cac18552/7c7cce40-beda-4963-9391-ccee12d66ec5-800.m3u8",
                "url": "https://cdn.orb360.tech/.....ccee12d66ec5-800.m3u8"
              }
            ]
          }
        }
      }
    }
  ],
  "tenant": {
    "branding": {
      "embed": true
    }
  }
}

Find By Tag

post

The findByTag endpoint only allows access to media contained within a shoot which has been enabled for integration access and has been published.

Login to the ORB360 management interface to confirm your shoot's integration settings. Please contact your ORB360 account manager to request that integrations are enabled

Endpoint Remarks

  • Each request is limited to a single designer (tenant).
  • Multiple tags can be specified by adding further { key, value } objects the tags array.
  • The tag array is limited to max 10 unique key-value pairs.
  • The condition attribute defines the evaluation of media which matches the supplied tags. Allowed options are:
    • AND: (default) returns media which contains a match against all of the supplied tags.
    • OR: return media which contains a match against at least one of the supplied tags.

Displaying the 360s

The images array returned in the response can be passed directly to our interactive player during initialisation to allow for hassle free display of the 360's in HTML based content.

Authorizations
Query parameters
videosV2booleanOptional

Query parameter specifies to use the new videos response version (V2), this new version includes support for multiple sources of the same width and also the inclusion of M3U8 video streams for VIDEO media types.

The query parameter provides a tempoary migration path to allow for the gradual migration to the new response type without breaking chnages.

Note: v2 response type will become the default in the future, so all new implementations should set this property to true, to avoid future breaking changes.

Default: falseExample: true
Body
tenantstringOptional

The unique identifier for the requested tenant (uuid)

Example: fdb67f2e-219d-4771-b14f-a2ddc24b812b
conditionstring ยท enumOptional

The condition attribute defines the evaluation of media which matches the supplied tags. Allowed options are:

  • AND: returns media which contains a match against all of the supplied tags.
  • OR: return media which contains a match against at least one of the supplied tags.
Default: ANDPossible values:
Responses
200
success
application/json
Responseall of
400
bad request
application/json
401
unauthorized
application/json
403
forbidden
application/json
404
not found
application/json
post
POST /api/integrations/apiKey/findByTag HTTP/1.1
Host: api.orb360.tech
Content-Type: application/json
Accept: */*
Content-Length: 203

{
  "tenant": "fdb67f2e-219d-4771-b14f-a2ddc24b812b",
  "condition": "AND",
  "tags": [
    {
      "key": "StyleNumber",
      "value": "1234"
    }
  ],
  "resolution": {
    "image": [
      {
        "width": 800
      },
      {
        "width": 1600
      }
    ]
  },
  "formats": {
    "image": {
      "type": "webp"
    }
  }
}
{
  "images": [
    {
      "media": {
        "id": "daea0774-275b-4e43-9d10-c2f9d5d4d5b6",
        "meta": {
          "boxerTenantId": "fdb67f2e-219d-4771-b14f-a2ddc24b812b",
          "from": "boxer",
          "type": "360_V2",
          "frames": 72,
          "shootId": "683606ee-9788-4d88-adb8-77119de4c6a2"
        },
        "tags": {
          "ANY_ADDITIONAL_PROPERTY": [
            "12345$BLACK"
          ]
        },
        "version": 123,
        "dateCreated": 1594988393066,
        "dateUpdated": 1594988393066
      },
      "type": "SINGLE_IMAGE",
      "baseURL": "https://cdn.orb360.tech/image/b1a213d6-8559-45f7-86da-088e6a85d86c/shoots/5b608121-c7b6-4a36-ac2a-54da43d869a2/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3/",
      "sizes": {
        "ImageWidth": {
          "urls": [
            "800_9fb29dc6a2edc54f2a9851d6bdc23e5df87220fa/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3-800.jpg?fmt=webp&w=150&s=5c1b7bbeec44a9fa61824b3f6964ece3e419b1fae73855cc97c19b2ea8977ac2"
          ]
        }
      }
    }
  ],
  "videos": [
    {
      "media": {
        "id": "daea0774-275b-4e43-9d10-c2f9d5d4d5b6",
        "meta": {
          "boxerTenantId": "fdb67f2e-219d-4771-b14f-a2ddc24b812b",
          "from": "boxer",
          "type": "360_V2",
          "frames": 72,
          "shootId": "683606ee-9788-4d88-adb8-77119de4c6a2"
        },
        "tags": {
          "ANY_ADDITIONAL_PROPERTY": [
            "12345$BLACK"
          ]
        },
        "version": 123,
        "dateCreated": 1594988393066,
        "dateUpdated": 1594988393066
      },
      "type": "360_V2",
      "formats": {
        "mp4": {
          "baseURL": "https://ordre-media-dev.s3.eu-west-1.amazonaws.com/b1a213d6-8559-45f7-86da-088e6a85d86c/shoots/5b608121-c7b6-4a36-ac2a-54da43d869a2/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3/",
          "sizes": {
            "ImageWidth": [
              {
                "filesize": 4303059,
                "file": "800_6677d7dfc0454b958c9a15b38f444885/1e81d25b-fc79-4ab0-9e3e-5476353e3e76-800.mp4",
                "url": "800_6677d7dfc0454b958c9a15b38f444885/1e81d25b-fc79-4ab0-9e3e-5476353e3e76-800.mp4",
                "durationSecs": 4,
                "resolution": {
                  "width": 800,
                  "height": 1200
                }
              }
            ]
          }
        },
        "m3u8": {
          "baseURL": "https://cdn.orb360.tech/assets/b1a213d6-8559-45f7-86da-088e6a85d86c/shoots/5b608121-c7b6-4a36-ac2a-54da43d869a2/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3/",
          "m3u8Index": "https://cdn.orb360.tech/m3u8/b1a213d6-8559-45f7-86da-088e6a85d86c/shoots/5b608121-c7b6-4a36-ac2a-54da43d869a2/5dfc5b5e-bc9b-4fde-9af4-e4904ce212a3/index.m3u8",
          "sizes": {
            "ImageWidth": [
              {
                "resolution": {
                  "width": 800
                },
                "audio": {
                  "codec": "acc"
                },
                "video": {
                  "bitRate": 3000,
                  "chunkSize": 4,
                  "codec": "h264",
                  "crf": 20,
                  "keyframe": 48,
                  "profile": "main"
                },
                "size": 4303059,
                "chunks": 4303059,
                "file": "v1_800_h264_main_crf20_c4_2675k_beaffc7602c8cba3dd970e52ee38f366cac18552/7c7cce40-beda-4963-9391-ccee12d66ec5-800.m3u8",
                "url": "https://cdn.orb360.tech/.....ccee12d66ec5-800.m3u8"
              }
            ]
          }
        }
      }
    }
  ],
  "tenant": {
    "branding": {
      "embed": true
    }
  }
}