1. Introduction
This document explains the v2 Analytics API and the steps to use these APIs to allow the user to access Viewership Analytics, Content Analytics, Concurrent Users, Ad Analytics, Ad Content Analytics and Unique Viewers Analytics using REST call in addition to using the Analytics Dashboard to view the data.
2. Prerequisites to download a report
Required Parameters: The params which are required to run the APIs. Without this param, APIs will throw ‘Unprocessable entity’ error
Optional Parameters: The params which are used as an optional parameter to support the APIs with required params in order to get an enhanced API
API tool such as wget, Postman, cURL etc
3. Access Token Generation
Personal Access token can be generated using these steps -
Generate, Copy and Save the Personal Access Token after clicking on Generate Token.
If the token is already generated before, then Regenerate Token Button will be visible in the Dashboard.
In this case, use the existing saved token
If the token is lost, then regenerate the token by clicking on the button and then copy and save the token for future use.
Note that the token cannot be viewed again, so make sure to save it in a secure location.
This token should be passed as a header during the download API call.
4. Supported APIs
4.1. Viewership Analytics
Viewership analytics typically helps in getting data related to content viewership. It will outline various metrics that help the users in determining different viewing patterns of the viewers. Viewership Analytics can be broadly viewed into Daily and Hourly Interval Options.
4.2. Content Analytics
If EPG is enabled for the customer, users will be able to fetch the content viewing behaviour between the date range selected along with other dimensions selected. Content Analytics can be broadly viewed into Daily and Hourly Interval Options.
4.3. Concurrent Users
It is the number of users watching the streams in parallel any given time. Concurrent Users can be broadly viewed into 1 Hour, 12 Hours and 24 Hours Options
4.4. Ad Analytics
Ad Analytics will provide data related to Content Monetization and Ad viewing patterns of the viewers
4.5. Ad Content Analytics
As the name indicates, users will be able to fetch Content having Ad analytics.
4.6. Unique Viewers
Unique Viewer is calculated by taking the unique combination of IP address and User Agent which is counted as one Unique Viewer watching the content. Unique Viewers can be broadly viewed into Daily, Weekly and Monthly Options
4.7. Channel List API
This API is used to get the list of channels (both Viewership and AdAnalytics) associated with the x-access-token.
5. Process: How to get the data out of APIs
5.1. Viewership Analytics API
Viewership Analytics API has to be called with the generated token as part of the header.
This token will be used to authenticate the user
Once the validation is successful, the API will return a success response else it will return 401 error
5.1.1. Format of the URL
https://api-analytics.amagi.tv/api/v2?type=viewershipAnalytics&startDate={start date in YYYY-MM-DD format}&endDate={end date in YYYY-MM-DD format}&interval={HOURLY or DAILY}&channelId={any valid channel id from channelList API}
HTTP Method: GET
API Headers: x-access-token: <personal access token created using step1>
5.1.2. Query Parameters:
Below parameters are used in conjunction with the URL to create an API structure which the customer wants to query.
Parameter | Data Type | Example | Optional |
type | String | viewershipAnalytics | No |
startDate | String (YYYY-MM-DD Format) |
2021-07-01 |
No |
endDate | String (YYYY-MM-DD Format) |
2021-07-02 |
No |
interval | String | DAILY, HOURLY DAILY:startDate=YYYY-MM-DD&endDate=YYYY-MM-DD HOURLY:startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&startTime=00:00&endTime=23:00 | No |
channelId | String | channelId1 | Yes |
city | String | Abbott | Yes |
country | String | United States | Yes |
deviceName | String | Amazon Fire TV | Yes |
deviceType | String | Smart TV | Yes |
studioName | String | studio | Yes |
contentId | String | contentId1 | Yes |
timezone |
String |
US/Pacific | Yes (If not present will be defaulted to US/Pacific) |
Interval Options: DAILY, HOURLY
Timezone Options: US/Pacific, US/Eastern, Universal
Default Selection of Parameter: If Country, City, Device Name, Device Type, Studio Name, Content Id are not selected, the by default ‘All’ will be selected and aggregated selection would be presented
Refer End of the document for Device Name, Device Type options
5.1.3. Sample URL: Daily Viewership Analytics
https://api-analytics.amagi.tv/api/v2?type=viewershipAnalytics&startDate=2021-10-10&endDate=2021-10-21&interval=DAILY&channelId=XXXXX
5.1.4. Sample URL: Hourly Viewership Analytics
https://api-analytics.amagi.tv/api/v2?type=viewershipAnalytics&startDate=2021-10-10&endDate=2021-10-21&interval=HOURLY&channelId=XXXXX
5.1.5. Postman Snippet to fetch the Hourly Viewership Analytics Data
Create a new request
Add the API details
Select GET as request type,
Enter the URL
Add the header as mentioned above
Click on Send (or Send & Save)
Save the response in a json format
5.2. Content Analytics API
Content Analytics API has to be called with the generated token as part of the header.
This token will be used to authenticate the user
Once the validation is successful, the API will return a success response else it will return 401 error
5.2.1. Format of the URL
https://api-analytics.amagi.tv/api/v2?type=contentAnalytics&startDate={start date in YYYY-MM-DD format}&endDate={end date in YYYY-MM-DD format}&interval={HOURLY or DAILY}&channelId={any valid channel id from channelList API}
HTTP Method: GET
API Headers: x-access-token: <personal access token created using step1>
5.2.2. Query Parameters:
Below parameters are used in conjunction with the URL to create an API structure which the customer wants to query.
Parameter | Data Type | Example | Optional |
type | String | contentAnalytics | No |
startDate | String (YYYY-MM-DD Format) |
2021-07-01 |
No |
endDate | String (YYYY-MM-DD Format) |
2021-07-02 |
No |
interval | String | DAILY, HOURLY DAILY:startDate=YYYY-MM-DD&endDate=YYYY-MM-DD HOURLY:startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&startTime=00:00&endTime=23:00 | No |
page | Number | Pagination - Positive Integer | Yes |
limit | Number | Content Limit - Positive Integer | Yes |
channelId | String | channelId1 | Yes |
city | String | Abbott | Yes |
country | String | United States | Yes |
deviceName | String | Amazon Fire TV | Yes |
deviceType | String | Smart TV | Yes |
studioName | String | studio | Yes |
contentId | String | contentId1 | Yes |
timezone |
String |
US/Pacific | Yes (If not present will be defaulted to US/Pacific) |
Interval Options: DAILY, HOURLY
Timezone Options: US/Pacific, US/Eastern, Universal
Default Selection of Parameter: If Country, City, Device Name, Device Type, Studio Name, Content Id are not selected, the by default ‘All’ will be selected and aggregated selection would be presented
Refer End of the document for Device Name, Device Type options
5.2.3. Sample URL: Daily Content Analytics
https://api-analytics.amagi.tv/api/v2?type=contentAnalytics&startDate=2021-10-10&endDate=2021-10-10&interval=DAILY&channelId=XXXXX
5.2.4. Sample URL: Hourly Content Analytics
https://api-analytics.amagi.tv/api/v2?type=contentAnalytics&startDate=2021-10-10&endDate=2021-10-10&interval=HOURLY&channelId=XXXXX
5.2.5. Using Postman to fetch the Daily Content Analytics Data
Create a new request
Add the API details
Select GET as request type,
Enter the URL
Add the header as mentioned above
Click on Send (or Send & Save)
Save the response in a json format
5.3. Concurrent Viewer Analytics API
Concurrent Viewers API will always provide data of the current time(Last 1/12/24 Hours from current time) and only in UTC format
Concurrent Viewers API has to be called with the generated token as part of the header.
This token will be used to authenticate the user
Once the validation is successful, the API will return a success response else it will return 401 error
5.3.1. Format of the URL
https://api-analytics.amagi.tv/api/v2?type=concurrentUsers&hoursLimit={1 or 12 or 24}&channelId={any valid channel id from channelList API}
HTTP Method: GET
API Headers: x-access-token: <personal access token created using step1>
5.3.2. Query Parameters:
Below parameters are used in conjunction with the URL to create an API structure which the customer wants to query.
Parameter | Data Type | Example | Optional |
type | String | concurrentUsers | No |
hoursLimit | String | 24 | No |
channelId | String | channelId1 | Yes |
Hours Limit Options: 1, 12, 24
5.3.3. Sample URL: Last 1 Hour Concurrent Viewer
5.3.4. Sample URL: Last 12 Hours Concurrent Viewer
5.3.5. Sample URL: Last 24 Hours Concurrent Viewer(24 hrs is the max hour limit)
5.3.6. Using Postman to fetch Last 1 Hour Concurrent Users Data
Create a new request
Add the API details
Select GET as request type,
Enter the URL
Add the header as mentioned above
Click on Send (or Send & Save)
Save the response in a json format
5.4. Ad Analytics API
Ad Analytics API has to be called with the generated token as part of the header.
This token will be used to authenticate the user
Once the validation is successful, the API will return a success response else it will return 401 error
5.4.1. Format of the URL
https://api-analytics.amagi.tv/api/v2?type=adAnalytics&startDate={start date in YYYY-MM-DD format}&endDate={end date in YYYY-MM-DD format}&channelId={any valid channel id from channelList API}
HTTP Method: GET
API Headers: x-access-token: <personal access token created using step1>
5.4.2. Query Parameters:
Below parameters are used in conjunction with the URL to create an API structure which the customer wants to query.
Parameter | Data Type | Example | Optional |
type | String | adAnalytics | No |
startDate | String (YYYY-MM-DD Format) |
2021-07-01 |
No |
endDate | String (YYYY-MM-DD Format) |
2021-07-02 |
No |
channelId | String | channelId1 | Yes |
city | String | Abbott | Yes |
country | String | United States | Yes |
deviceName | String | Amazon Fire TV | Yes |
deviceType | String | Smart TV | Yes |
studioName | String | studio | Yes |
contentId | String | contentId1 | Yes |
adTag | String | adTag1 | Yes |
timezone |
String |
US/Pacific | Yes (If not present will be defaulted to US/Pacific) |
Timezone Options: US/Pacific, US/Eastern, Universal
Default Selection of Parameter: If Country, City, Device Name, Device Type, Studio Name, Ad Tag, Content Id are not selected, the by default ‘All’ will be selected and aggregated selection would be presented
Refer End of the document for Device Name, Device Type options
5.4.3. Sample URL: Ad Analytics
https://api-analytics.amagi.tv/api/v2?type=adAnalytics&startDate=2021-10-10&endDate=2021-10-21&channelId=XXXXX
5.4.4. Postman Snippet to fetch the Ad Analytics Data
Create a new request
Add the API details
Select GET as request type,
Enter the URL
Add the header as mentioned above
Click on Send (or Send & Save)
Save the response in a json format
5.5. Ad Content Analytics API
Ad Content Analytics API has to be called with the generated token as part of the header.
This token will be used to authenticate the user
Once the validation is successful, the API will return a success response else it will return 401 error.
5.5.1. Format of the URL
https://api-analytics.amagi.tv/api/v2?type=adContentAnalytics&startDate={start date in YYYY-MM-DD format}&endDate={end date in YYYY-MM-DD format}&channelId={any valid channel id from channelList API}
HTTP Method: GET
API Headers: x-access-token: <personal access token created using step1>
5.5.2. Query Parameters:
Below parameters are used in conjunction with the URL to create an API structure which the customer wants to query.
Parameter | Data Type | Example | Optional |
type | String | adContentAnalytics | No |
startDate | String (YYYY-MM-DD Format) |
2021-07-01 |
No |
endDate | String (YYYY-MM-DD Format) |
2021-07-02 |
No |
page | Number | Pagination - Positive Integer | Yes |
limit | Number | Content Limit - Positive Integer | Yes |
channelId | String | channelId1 | Yes |
city | String | Abbott | Yes |
country | String | United States | Yes |
deviceName | String | Amazon Fire TV | Yes |
deviceType | String | Smart TV | Yes |
studioName | String | studio | Yes |
contentId | String | contentId1 | Yes |
adTag | String | adTag1 | Yes |
timezone |
String |
US/Pacific | Yes (If not present will be defaulted to US/Pacific) |
Timezone Options: US/Pacific, US/Eastern, Universal
Default Selection of Parameter: If Country, City, Device Name, Device Type, Studio Name, Ad Tag, Content Id are not selected, the by default ‘All’ will be selected and aggregated selection would be presented
Refer End of the document for Device Name, Device Type options
5.5.3. Sample URL: Ad Content Analytics
https://api-analytics.amagi.tv/api/v2?type=adContentAnalytics&startDate=2021-10-10&endDate=2021-10-10&channelId=XXXXX
5.5.4. Using Postman to fetch the Ad Content Analytics Data
Create a new request
Add the API details
Select GET as request type,
Enter the URL
Add the header as mentioned above
Click on Send (or Send & Save)
Save the response in a json format
5.6. Unique Viewers Analytics API
Unique Viewers Analytics API has to be called with the generated token as part of the header.
The token will be used to authenticate the user
Once the validation is successful, the API will return a success response else it will return 401 error.
5.6.1. Format of the URL
https://api-analytics.amagi.tv/api/v2?type=uniqueViewersAnalytics&startDate={start date in YYYY-MM-DD format}&endDate={end date in YYYY-MM-DD format}&interval={DAILY or WEEKLY or MONTHLY}&channelId={any valid channel id from channelList API}
HTTP Method: GET
API Headers: x-access-token: <personal access token created using step1>
5.6.2. Query Parameters:
Below parameters are used in conjunction with the URL to create an API structure which the customer wants to query.
Parameter | Data Type | Example | Optional |
type | String | uniqueViewersAnalytics | No |
startDate | String (YYYY-MM-DD Format) |
2021-07-01 |
No |
endDate | String (YYYY-MM-DD Format) |
2021-07-02 |
No |
interval | String | DAILY | No |
channelId | String | channelId1 | Yes |
timezone |
String |
US/Pacific | Yes (If not present will be defaulted to US/Pacific) |
Interval Options: DAILY, WEEKLY, MONTHLY
Timezone Options: US/Pacific, US/Eastern, Universal
5.6.3. Sample URL: Daily Unique Viewers Analytics
https://api-analytics.amagi.tv/api/v2?type=uniqueViewersAnalytics&startDate=2021-10-10&endDate=2021-10-10&interval=DAILY&channelId=XXXXX
5.6.4. Sample URL: Weekly Unique Viewers Analytics
https://api-analytics.amagi.tv/api/v2?type=uniqueViewersAnalytics&startDate=2021-10-10&endDate=2021-10-16&interval=WEEKLY&channelId=XXXXX
5.6.5. Sample URL: Monthly Unique Viewers Analytics
https://api-analytics.amagi.tv/api/v2?type=uniqueViewersAnalytics&startDate=2021-10-10&endDate=2021-10-31&interval=MONTHLY&channelId=XXXXX
5.6.6. Using Postman to fetch the Unique Viewers Analytics Data
Create a new request
Add the API details
Select GET as request type,
Enter the URL
Add the header as mentioned above
Click on Send (or Send & Save)
Save the response in a json format
5.7. Channel List API
Channel List API has to be called with the generated token as part of the header.
This token will be used to authenticate the user
Once the validation is successful, the API will return a success response else it will return 401 error.
5.7.1. Request Details:
Header: x-access-token: <personal access token created using Token Generation step1>
Sample URL: https://api-analytics.amagi.tv/api/v2?type=channelList
HTTP Method: GET
5.7.2. Using Postman to fetch the Channel List
Create a new request
Add the API details
Select GET as request type,
Enter the URL
Add the header as mentioned above
Click on Send (or Send & Save)
Save the response in a json format
6. Scheduling a Report: v1 Download Scheduled Reports API
When we schedule a report, a new schedule ID will be generated for it.
Similarly, for an existing report earlier scheduled by the user, a schedule ID will be visible alongside the report in the schedule reports page in the dashboard.
To create a new scheduled report in the Schedule Reports Page -
Go to the Schedule Reports Page in the Dashboard from this link: https://analytics.amagi.tv/scheduledReports
Click on Create New Schedule to download new report
After filling in the details, click on Save Schedule
The Report will be available with a schedule ID in the Scheduled Reports Page on the basis of Report Interval type selected
If the Report Interval is selected Daily in the Create Schedule Page, then the report will be visible after 24 hours in the Scheduled Reports Page
If the Report Interval is selected Weekly in the Create Schedule Page, then the report will be visible after a week in the Scheduled Reports Page
If the Report Interval is selected Monthly in the Create Schedule Page, then the report will be visible after a month in the Scheduled Reports Page
Copy and save the Schedule ID once its generated
6.1. Process
6.1.1. API
https://api-analytics.amagi.tv/api/v1/download-reports/{scheduleId}/{from_date of the report in YYYY-MM-DD format}
Pick the Schedule ID required in the URL from the Schedule Reports Page for that particular report. It will be visible in the first column
Date has to be the from_date of the report in YYYY-MM-DD format. From_date is the date from where reports started.
If it is a Monthly report then every report will be generated on the first day of the month.If someone wants to download Dec month data from 1st Dec to 31st Dec, it will get generated on 1st Jan. So from_date in this case would be 1st Dec i.e 2021-12-01
If it is a Weekly report then every report will be generated on next Monday.If someone wants to download weekly data from 6th Dec to 12th Dec, it will get generated on 13th Dec. So from_date in this case would be 6th Dec i.e 2021-12-06
If it is a Daily report then the report will be generated on the next day.If someone wants to download a daily report of 6th Dec, it will get generated on 7th Dec. So from_date in this case would be 6th Dec i.e 2021-12-06
API Method: GET
API Headers: x-access-token: <personal access token created using step1>
Personal access token created has to be passed as an x-access-token header.
6.1.2 Sample URL
6.2. Using wget
wget--header="x-access-token:<token>" https://api-analytics.amagi.tv/api/v1/download-reports/{scheduleId}/{YYYY-MM-DD} -O "filename.csv"
6.2.1. Sample wget command
Output will be saved in the “reports.csv” file and downloaded as well. Here this downloaded file could be blank because it contains no data.
6.3. Using Postman
Create a new request
Add the API details
Select GET as request type,
Enter the URL
Add the header as mentioned above
Click on Send (or Send & Save)
Save the response in a csv file using the Save Response action.
6.4. Accessing the Report
The report can be seen in the saved csv file. Using the API above, the workflow can be automated to automatically fetch the files as required and save it to a specific location as needed, or integrate it with any custom application.
7. Sample Requests and Responses of API’s
7.1. ChannelList API Sample Request/Response
7.1.1. ChannelList API Sample Request
7.1.2. ChannelList API Sample Response
{ |
7.2. Viewership API Sample Request/Response
7.2.1. Viewership API Sample Request: Interval-Daily
7.2.2. Viewership API Sample Response: Interval-Daily
{ |
7.3. Note on using APIs
Above Viewership API Request is for interval - Daily.
Similarly for interval - Hourly, simply replace the interval type in API request
Similarly, other API requests can be derived by simply replacing the type in API request
Content Analytics API Request
Ad-Content Analytics API Request
Unique Viewers API Request
Concurrent Users
8. Device Type and Device Name Options
Device Type | Device Names |
Desktop | Apple OS X, Windows Desktop, Desktop |
Media Player | Apple iPod |
Mobile Phone | Apple iPhone, Samsung Mobile, OthersMobile |
Roku | Roku |
Smart TV | Amazon Fire TV, Google Chromecast, Samsung TV, Haier TV, Hisense TV, Philips TV, Panasonic TV, Vizio TV, LG TV, OthersTV, Amazon Fire TV Stick, Apple TV |
TV | Set Top Box TV |
Tablet | Apple iPad, Samsung Tablet, OthersTablet |
Others | Others |
9. Countries List
Afghanistan | Albania | Algeria | American Samoa | Andorra |
Angola | Anguilla | Antigua and Barbuda | Argentina | Armenia |
Aruba | Australia | Austria | Azerbaijan | Bahamas |
Bahrain | Bangladesh | Barbados | Belarus | Belgium |
Belize | Benin | Bermuda | Bhutan | Bolivia |
Bonaire Sint Eustatius and Saba | Bosnia and Herzegovina | Botswana | Brazil | British Indian Ocean Territory |
British Virgin Islands | Brunei | Bulgaria | Burkina Faso | Burundi |
Cabo Verde | Cambodia | Cameroon | Canada | Cayman Islands |
Central African Republic | Chad | Chile | China | Christmas Island |
Cocos Keeling Islands | Colombia | Comoros | Congo Republic | Cook Islands |
Costa Rica | Croatia | Cuba | Curaao | Cyprus |
Czechia | Denmark | Djibouti | Dominica | Dominican Republic |
DR Congo | East Timor | Ecuador | Egypt | El Salvador |
Equatorial Guinea | Eritrea | Estonia | Eswatini | Ethiopia |
Faroe Islands | Federated States of Micronesia | Fiji | Finland | France |
French Guiana | French Polynesia | Gabon | Gambia | Georgia |
Germany | Ghana | Gibraltar | Greece | Greenland |
Grenada | Guadeloupe | Guam | Guatemala | Guernsey |
Guinea | Guinea-Bissau | Guyana | Haiti | Honduras |
Hong Kong | Hungary | Iceland | India | Indonesia |
Iran | Iraq | Ireland | Isle of Man | Israel |
Italy | Ivory Coast | Jamaica | Japan | Jersey |
Jordan | Kazakhstan | Kenya | Kosovo | Kuwait |
Kyrgyzstan | land | Laos | Latvia | Lebanon |
Lesotho | Liberia | Libya | Liechtenstein | Lithuania |
Luxembourg | Macao | Madagascar | Malawi | Malaysia |
Maldives | Mali | Malta | Marshall Islands | Martinique |
Mauritania | Mauritius | Mayotte | Mexico | Moldova |
Mongolia | Montenegro | Montserrat | Morocco | Mozambique |
Myanmar | Namibia | Nepal | Netherlands | New Caledonia |
New Zealand | Nicaragua | Niger | Nigeria | Norfolk Island |
Northern Mariana Islands | North Macedonia | Norway | Oman | Pakistan |
Palau | Palestine | Panama | Papua New Guinea | Paraguay |
Peru | Philippines | Poland | Portugal | Principality of Monaco |
Puerto Rico | Qatar | Romania | Runion | Russia |
Rwanda | Saint Barthlemy | Saint Lucia | Cocos Keeling Islands | Saint Martin |
Saint Pierre and Miquelon | Saint Vincent and the Grenadines | San Marino | Saudi Arabia | Senegal |
Serbia | Seychelles | Sierra Leone | Singapore | Sint Maarten |
Slovakia | Slovenia | Solomon Islands | Somalia | So Tom and Prncipe |
South Africa | South Korea | South Sudan | Spain | Sri Lanka |
St Kitts and Nevis | Sudan | Suriname | Sweden | Switzerland |
Syria | Taiwan | Tajikistan | Tanzania | Thailand |
Togo | Tonga | Trinidad and Tobago | Tunisia | Turkey |
Turkmenistan | Turks and Caicos Islands | Uganda | Ukraine | United Arab Emirates |
United Kingdom | United States | Uruguay | U.S. Virgin Islands | Uzbekistan |
Vanuatu | Vatican City | Venezuela | Vietnam | Yemen |
Zambia | Zimbabwe |
|
|
|