API Integration - Categories and Teams

API Integration - Categories and Teams

About Pixellot

Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, Pixellot’s AI technology solution streamlines production workflow by deploying an unmanned multicamera system in a fixed location, with additional angles as required, to cover the entire field, offering a stitched panoramic image. Advanced algorithms enable automatic coverage of the flow of play and generate highlights. Pixellot systems are deployed by broadcasters, production companies, clubs, federations, universities, high schools, sports portals, and coaching solution providers around the globe.

For more information visit: www.pixellot.tv


Legal Notice

This document contains proprietary and confidential material of Pixellot Ltd. Any unauthorized reproduction, use, or disclosure of this material, or any part thereof, is strictly prohibited. This document is solely for the use of Pixellot employees and authorized Pixellot customers.

The material furnished in this document is believed to be accurate and reliable. However, no responsibility is assumed by Pixellot Ltd. for the use of this document or any material included herein. Pixellot Ltd. reserves the right to make changes to this document or any material included herein at any time and without notice. 

For more information visit: www.pixellot.tv 

Copyright © 2024 Pixellot Ltd.

All Rights Reserved.


Pixellot API

Pixellot provides its partners with a dedicated Partner API for creating new entities, updating and retrieving them. In addition, a partner can subscribe to Pixellot webhooks to get notification about different significant occurrences.

The idea is that a partner can, for instance, ask for a list of events on startup. When the partner subscribes to the webhooks service, it will get notifications about every significant change (including creation and deletion) and will update its own database. This will omit the need to repeatedly ask for the full list of events to get new events and updates to existing events. The updates can, in this way, be done passively in a push method instead of pull.


RestAPI documentation

Explore Partner API through our official documentation. This resource provides essential information for integrating our services seamlessly into your applications. Find detailed API endpoints, request methods, authentication guides, and error handling instructions.

For more information, visit our REST API documentation at https://app.swaggerhub.com/apis/Pixellot/partner_api/


How to use the API?

Pixellot API is a RESTful HTTP API. All requests, except the login, require an access token. If no access token will be provided in the API request, 401 Unauthorized will be returned to the client.


Environments

Pixellot supports 2 environments for 3rd party companies: staging and production. Initially, 3rd party company integrates with the staging environment to verify that the integration is correct. Once E2E staging works correctly, the integration moves to production.

Available environments:

[Base URL] = api.pixellot.tv/v1 (PROD) - production workloads
[Base URL] = api.stage.pixellot.tv/v1 (STAGE) - tests and integration


Authorization

All API requests, except for login, require the “Authorization” header to be present. Authorization is based on the JWT method. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties.

To obtain authorization data, use the POST /login endpoint - https://app.swaggerhub.com/apis/Pixellot/partner_api/1.28.18#/default/login

Typical authenticated request would be having the following look:

  1. curl https://api.stage.pixellot.tv/v1/venues -H "Authorization: eyJ0eX..."


About API Integration - Categories & Teams

  
The Pixellot API Reference covers all API elements vis-a-vis Pixellot CMS. 
This document is specific to - CATEGORIES & TEAMS.


CATEGORIES

 1. General

Categories serve to allow managing the content across the users of certain tenants, by distributing it within two levels, the main category and sub-category. Main and sub-categories can be mixed with each other, which means that two main categories could have the same sub-category. It's not allowed for events to have a main category only or subcategory only. Currently, categories can be created and edited only in CMS.

Main categories will be shown as tabs above in OTT, but category will appear there only if some events were assigned to it.

1.1  Main categories in CMS:





1.2  Main categories in OTT:




1.3  Sub-category images will be shown on the tabs of the select sub-category page:




2. Both main and sub-categories have several parameters:

  • id - unique category identifier (string, 24 characters of digits and letters)

  • isArchived - flag showing if the category was archived (boolean)

  • name - category name (string, 2 - 50 characters)

  • type - defines main or sub category (string, "main"/"sub")

  • tenant - shows tenant affiliation (string)

  • permission - category access (string, "public"/"private")

  • color - hex color code

  • hidden - display or hide category in OTT (string, "yes"/"no")

  • logo - category image (cloudfront file link)

  • createdAt - datetime when category created (yyyy-MM-ddThh:mm:ss.fffZ)

  • updatedAt - datetime of last changes (yyyy-MM-ddThh:mm:ss.fffZ)

Popular use cases:

  • Changing sub-category in CMS during live and upcoming events changes the category in both CMS and OTT

  • Changing the main category in CMS will remove the event from the “Old” category and will store it under the “New” one

  • Archiving the category during the live event may not have any effect up until event becomes VOD

  • Only GET requests are allowed for categories. Create and update operations can be done in CMS.

  • Scheduling an event with categories requires adding both category name and ID

  • The archived category still exists but is not displayed in CMS (still you can access it by ID and unmark the Archived checkmark)




3. Categories API calls:

Get all categories in API user’s tenant with all the above parameters:

  1. GET {{PAPI_BASE_URL}}/categories


Get a category specified by ID (!even if it has a different tenant!) with all the above parameters:

  1. GET {{PAPI_BASE_URL}/categories/{{categoryID}}
 

A parameter schema that allows adding categories in event scheduling API call, if used in POST create event body:


  1.  "categories": { 
  2.              "main": { 
  3.                 "name": "MainCategoryName", 
  4.                 "id": "{{MainCategoryID}}" 
  5.             }, 
  6.             "secondaries": [ 
  7.                 { 
  8.                     "name": "SubCategoryName", 
  9.                     "id": " {{SubCategoryID}}" 
  10.                 } 
  11.             ] 
  12.         } 


TEAMS

 1.  General

The Teams feature is used to display home and guest teams participating in the event, they will be indicated on the event’s preview (CMS/OTT) and chosen scoreboard. Teams can be created and edited in CMS (Pixellot - club.pixellot.tv ), where you can set Team Name, Team Short Name, Team Color, and Logo. Currently, teams can be created and edited only in CMS.

Teams' colors and logos on the event preview tab in OTT:

Live:


VOD:

1.1  Teams Parameters:

Teams have next parameters:

  • id - unique team identifier (string, 24 characters of digits and letters)

  • name - team name (string, 2 to 50 characters)

  • shortName - the name used for scoreboard (string, doesn't have characters cap)

  • color - hex color code

  • tenant - shows tenant affiliation (string)

  • images - list of different size images

  • isArchived - shows if the team was archived (boolean)

  • vidSwap - shows if the team is assigned to VidSwap league/s

Popular use cases:

  • Short team name doesn’t have characters cap and tip for min-max characters in CMS

  • Only GET methods allowed for teams via API. Create and update operations can be done in CMS.

  • It’s possible to mix event scheduling with teams specified by ID and name. For example, “homeTeam” and “awayTeamId”


2.  Teams API calls:

Get a list of teams assigned to API user’s tenant:
  1. GET {{PAPI_BASE_URL}}/teams

Get a list of teams assigned to API user’s tenant:
  1. GET {{PAPI_BASE_URL}}/teams/{{id}}

A parameter schema that allows adding teams by names in event scheduling POST API call:
  1.  "scoreboardData": { 
  2.             "homeTeam": "{{TeamName_1}}", 
  3.             "awayTeam": "{{TeamName_2}}", 
  4.             "enable": true 
  5.         }

A parameter schema that allows adding teams by IDs in event scheduling POST API call:
  1. "scoreboardData": { 
  2.             "homeTeamId": "{{TeamID_1}}", 
  3.             "awayTeamId": "{{TeamID_2}}", 
  4.             "enable": true 
  5.         }


3.  The flow of creating an event within the selected Teams and Categories through API:

3.1  First, we need to create the Main and Sub categories inside the tenant that we want to use for event:

A.  Open Categories tab on the left side of CMS and click on the Create button on the left bottom corner:


B.   Fill in all required parameters, choose the color and add a logo:


C.  Do the same procedure for Sub-category:



3.2  Next step will be creating teams:

A.  Go to Teams tab and click Create button, similar to what you did with Categories


B.  For each non-practice event, you will need to have two teams, create them by filling in all the parameters and selecting the color and logo. It is important to select a color and logo since it will be shown on the event’s preview and scoreboard.


3.3  Now let’s create an event with the categories and teams that we have created:

A.  Make sure that you have a venue assigned to the specific club and their ID. Club and Venue ID you can get by sending an API call:

  1. GET {{PAPI_BASE_URL}}/clubs

  1. Response Body:
  2. {
  3.     "_id": "62d547b526b934348455da4d",
  4.     "name": "AlphaClub",
  5.     "venues": [
  6.         {
  7.             "_id": "62d7aadcfada9a1fd0aa446e",
  8.             "name": "Pixellot-S1"
  9.         }
  10.     ],
  11.     "admins": [
  12.         {
  13.             "id": "5ee236f4b4f2c20009b587a3",
  14.             "fullName": "Max Verstappen"
  15.         }
  16.     ],
  17.     "prerolls": []
  18. }



B.  Now let’s get unique IDs for categories and teams that we’ve created before.
  1. GET {{PAPI_BASE_URL}}/categories

  1. Response Body:
  2. [    
  3.     {
  4.         "_id": "62e102182f501d3b4f038aaa",
  5.         "isArchived": false,
  6.         "name": "TestMain",
  7.         "type": "main",
  8.         "tenant": "Pixellot",
  9.         "permission": "public",
  10.         "color": "#21426d",
  11.         "hidden": "no",
  12.         "logo": "https://d2o79pah7uyou5.cloudfront.net/categories/logo-addbfe6733e3ac1e1ee007a12ca9b1a8a72e922ffa843ed7.png",
  13.         "createdAt": "2022-07-27T09:15:04.406Z",
  14.         "updatedAt": "2022-07-27T09:15:04.406Z"
  15.     },
  16.     {
  17.         "_id": "62e1024d7ae9f914a899abae",
  18.         "isArchived": false,
  19.         "name": "TestSub",
  20.         "type": "sub",
  21.         "tenant": "Pixellot",
  22.         "permission": "public",
  23.         "color": "#4e8c53",
  24.         "hidden": "no",
  25.         "logo": "https://d2o79pah7uyou5.cloudfront.net/categories/logo-1cdc15a5f7e6acb69ce713ff520db2dbfdac91806012591d.jpeg",
  26.         "createdAt": "2022-07-27T09:15:57.192Z",
  27.         "updatedAt": "2022-07-27T09:15:57.192Z"
  28.     }
  29. ]


  1. GET {{PAPI_BASE_URL}}/teams


  1. Response Body:
  2. [
  3.     {
  4.         "_id": "62e104167ae9f976af99abd0",
  5.         "name": "TestAway",
  6.         "shortName": "TA",
  7.         "color": "#ff0505",
  8.         "tenant": "Pixellot",
  9.         "images": {
  10.             "logo": {
  11.                 "small": {
  12.                     "width": 320,
  13.                     "height": -1,
  14.                     "fileKey": "teams/62e104167ae9f976af99abd0/logo.0c8e86a8b3d33ac57811efd784c14cff88730863969fa332-320x-1.png",
  15.                     "url": "https://d2o79pah7uyou5.cloudfront.net/teams/62e104167ae9f976af99abd0/logo.0c8e86a8b3d33ac57811efd784c14cff88730863969fa332-320x-1.png"
  16.                 },
  17.                 "medium": {
  18.                     "width": 480,
  19.                     "height": -1,
  20.                     "fileKey": "teams/62e104167ae9f976af99abd0/logo.0c8e86a8b3d33ac57811efd784c14cff88730863969fa332-480x-1.png",
  21.                     "url": "https://d2o79pah7uyou5.cloudfront.net/teams/62e104167ae9f976af99abd0/logo.0c8e86a8b3d33ac57811efd784c14cff88730863969fa332-480x-1.png"
  22.                 },
  23.                 "big": {
  24.                     "width": 720,
  25.                     "height": -1,
  26.                     "fileKey": "teams/62e104167ae9f976af99abd0/logo.0c8e86a8b3d33ac57811efd784c14cff88730863969fa332-720x-1.png",
  27.                     "url": "https://d2o79pah7uyou5.cloudfront.net/teams/62e104167ae9f976af99abd0/logo.0c8e86a8b3d33ac57811efd784c14cff88730863969fa332-720x-1.png"
  28.                 },
  29.                 "large": {
  30.                     "width": 1280,
  31.                     "height": -1,
  32.                     "fileKey": "teams/62e104167ae9f976af99abd0/logo.0c8e86a8b3d33ac57811efd784c14cff88730863969fa332-1280x-1.png",
  33.                     "url": "https://d2o79pah7uyou5.cloudfront.net/teams/62e104167ae9f976af99abd0/logo.0c8e86a8b3d33ac57811efd784c14cff88730863969fa332-1280x-1.png"
  34.                 }
  35.             }
  36.         },
  37.         "isArchived": false,
  38.         "vidSwap": {}
  39.     },
  40.     {
  41.         "_id": "62e103717ae9f93b0899abc4",
  42.         "name": "TestHome",
  43.         "shortName": "TH",
  44.         "color": "#16a1e6",
  45.         "tenant": "Pixellot",
  46.         "images": {
  47.             "logo": {
  48.                 "small": {
  49.                     "width": 320,
  50.                     "height": -1,
  51.                     "fileKey": "teams/62e103717ae9f93b0899abc4/logo.9ca487f306bb8b8d5fe292ec8b5424195dcf7b9aafdac2dc-320x-1.png",
  52.                     "url": "https://d2o79pah7uyou5.cloudfront.net/teams/62e103717ae9f93b0899abc4/logo.9ca487f306bb8b8d5fe292ec8b5424195dcf7b9aafdac2dc-320x-1.png"
  53.                 },
  54.                 "medium": {
  55.                     "width": 480,
  56.                     "height": -1,
  57.                     "fileKey": "teams/62e103717ae9f93b0899abc4/logo.9ca487f306bb8b8d5fe292ec8b5424195dcf7b9aafdac2dc-480x-1.png",
  58.                     "url": "https://d2o79pah7uyou5.cloudfront.net/teams/62e103717ae9f93b0899abc4/logo.9ca487f306bb8b8d5fe292ec8b5424195dcf7b9aafdac2dc-480x-1.png"
  59.                 },
  60.                 "big": {
  61.                     "width": 720,
  62.                     "height": -1,
  63.                     "fileKey": "teams/62e103717ae9f93b0899abc4/logo.9ca487f306bb8b8d5fe292ec8b5424195dcf7b9aafdac2dc-720x-1.png",
  64.                     "url": "https://d2o79pah7uyou5.cloudfront.net/teams/62e103717ae9f93b0899abc4/logo.9ca487f306bb8b8d5fe292ec8b5424195dcf7b9aafdac2dc-720x-1.png"
  65.                 },
  66.                 "large": {
  67.                     "width": 1280,
  68.                     "height": -1,
  69.                     "fileKey": "teams/62e103717ae9f93b0899abc4/logo.9ca487f306bb8b8d5fe292ec8b5424195dcf7b9aafdac2dc-1280x-1.png",
  70.                     "url": "https://d2o79pah7uyou5.cloudfront.net/teams/62e103717ae9f93b0899abc4/logo.9ca487f306bb8b8d5fe292ec8b5424195dcf7b9aafdac2dc-1280x-1.png"
  71.                 }
  72.             }
  73.         },
  74.         "isArchived": false,
  75.         "vidSwap": {}
  76.     }
  77. ]

C.  Once you have Venue, Club, Categories (main and sub), and two teams' IDs, use POST create event API call to schedule an event:
  1. POST {{PAPI_BASE_URL}}/clubs/62d547b526b934348455da4d/events

D.  The request body of such API call should be within the next schema:

  1. {
  2.   "eventName": "OTT_Test",
  3.   "start$date": "2022-07-27T10:15:00.000Z",
  4.   "end$date": "2022-07-27T11:00:00.000Z",
  5.   "status": "active",
  6.   "venue": {
  7.     "_id": "62d7aadcfada9a1fd0aa446e"
  8.   },
  9.   "permission": "all",
  10.   "productionType": "soccer",
  11.   "scoreboardData": {
  12.             "homeTeamId": "62e103717ae9f93b0899abc4",
  13.             "awayTeamId": "62e104167ae9f976af99abd0",
  14.             "enable" : true
  15.         },
  16.   "categories": {
  17.             "main": {
  18.                 "name": "TestMain",
  19.                 "id": "62e102182f501d3b4f038aaa"
  20.             },
  21.             "secondaries": [
  22.                 {
  23.                     "name": "TestSub",
  24.                     "id": "62e1024d7ae9f914a899abae"
  25.                 }
  26.             ]
  27.         }
  28. }


E.  Once the command will be sent, you should receive a response with 200 Status code and a Response body that contains info about the created event:
  1. {
  2.     "_id": "62e109869384472b4b08095f",
  3.     "eventName": "OTT_Test",
  4.     "start$date": "2022-07-27T10:15:00Z",
  5.     "end$date": "2022-07-27T11:00:00Z",
  6.     "status": "active",
  7.     "venue": {
  8.         "_id": "62d7aadcfada9a1fd0aa446e"
  9.     }
  10. }



F.  Once the event is created, depending on the activity of the category it may appear on the list of categories tab at the top side of the page, depending on the activity of the categories. If you choose the Category, the list of sub-categories will be shown:




G.  Inside the Sub-category you will see your scheduled event showing up as Upcoming:




H.  By clicking on event info, you will access the event’s preview page, where you can see the Event Name, Teams, Date of the event, and Time remaining until the event will be Live:




Notes
Notice that preview colors and logos depend on the Teams' colors and logos that you chose during their creation.



    • Related Articles

    • API Integration - Events and Clubs

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...

    • API Integration - Advanced Breakdown

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...

    • API Integration - Troubleshooting and Q&A

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...

    • API Integration - Onboarding and Best practices

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...

    • API Integration - Events Monitoring and Hooks

      About Pixellot Pixellot offers automated sports production solutions that provide affordable alternatives to traditional video capture, production, and distribution systems for professional and semi-professional sports events. Founded in 2013, ...