Skip to main content
All CollectionsProduct Manuals
Amagi Analytics API - version 2
Amagi Analytics API - version 2

Access your data using API

Suyash Chandra avatar
Written by Suyash Chandra
Updated over 2 years ago

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

  1. Required Parameters: The params which are required to run the APIs. Without this param, APIs will throw ‘Unprocessable entity’ error

  2. 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

  1. API tool such as wget, Postman, cURL etc

3. Access Token Generation

Personal Access token can be generated using these steps -

  1. Generate, Copy and Save the Personal Access Token after clicking on Generate Token.

    1. If the token is already generated before, then Regenerate Token Button will be visible in the Dashboard.

      1. In this case, use the existing saved token

      2. If the token is lost, then regenerate the token by clicking on the button and then copy and save the token for future use.

    2. Note that the token cannot be viewed again, so make sure to save it in a secure location.

  2. 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

  1. Viewership Analytics API has to be called with the generated token as part of the header.

  2. This token will be used to authenticate the user

  3. 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

5.1.4. Sample URL: Hourly Viewership Analytics

5.1.5. Postman Snippet to fetch the Hourly Viewership Analytics Data

  1. Create a new request

  2. Add the API details

  1. Select GET as request type,

  2. Enter the URL

  3. Add the header as mentioned above

  1. Click on Send (or Send & Save)

  2. Save the response in a json format

5.2. Content Analytics API

  1. Content Analytics API has to be called with the generated token as part of the header.

  2. This token will be used to authenticate the user

  3. 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

5.2.4. Sample URL: Hourly Content Analytics

5.2.5. Using Postman to fetch the Daily Content Analytics Data

  1. Create a new request

  2. Add the API details

  1. Select GET as request type,

  2. Enter the URL

  3. Add the header as mentioned above

  1. Click on Send (or Send & Save)

  2. Save the response in a json format

5.3. Concurrent Viewer Analytics API

  1. Concurrent Viewers API will always provide data of the current time(Last 1/12/24 Hours from current time) and only in UTC format

  2. Concurrent Viewers API has to be called with the generated token as part of the header.

  3. This token will be used to authenticate the user

  4. 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

  1. Create a new request

  2. Add the API details

  1. Select GET as request type,

  2. Enter the URL

  3. Add the header as mentioned above

  1. Click on Send (or Send & Save)

  2. Save the response in a json format

5.4. Ad Analytics API

  1. Ad Analytics API has to be called with the generated token as part of the header.

  2. This token will be used to authenticate the user

  3. 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

5.4.4. Postman Snippet to fetch the Ad Analytics Data

  1. Create a new request

  2. Add the API details

  1. Select GET as request type,

  2. Enter the URL

  3. Add the header as mentioned above

  1. Click on Send (or Send & Save)

  2. Save the response in a json format

5.5. Ad Content Analytics API

  1. Ad Content Analytics API has to be called with the generated token as part of the header.

  2. This token will be used to authenticate the user

  3. 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

5.5.4. Using Postman to fetch the Ad Content Analytics Data

  1. Create a new request

  2. Add the API details

    1. Select GET as request type,

    2. Enter the URL

    3. Add the header as mentioned above

  3. Click on Send (or Send & Save)

  4. Save the response in a json format

5.6. Unique Viewers Analytics API

  1. Unique Viewers Analytics API has to be called with the generated token as part of the header.

  2. The token will be used to authenticate the user

  3. 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

5.6.4. Sample URL: Weekly Unique Viewers Analytics

5.6.5. Sample URL: Monthly Unique Viewers Analytics

5.6.6. Using Postman to fetch the Unique Viewers Analytics Data

  1. Create a new request

  2. Add the API details

    1. Select GET as request type,

    2. Enter the URL

    3. Add the header as mentioned above

  3. Click on Send (or Send & Save)

  4. Save the response in a json format

5.7. Channel List API

  1. Channel List API has to be called with the generated token as part of the header.

  2. This token will be used to authenticate the user

  3. Once the validation is successful, the API will return a success response else it will return 401 error.

5.7.1. Request Details:

5.7.2. Using Postman to fetch the Channel List

  1. Create a new request

  2. Add the API details

  1. Select GET as request type,

  2. Enter the URL

  3. Add the header as mentioned above

  1. Click on Send (or Send & Save)

  2. 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 -

  1. Go to the Schedule Reports Page in the Dashboard from this link: https://analytics.amagi.tv/scheduledReports

  2. Click on Create New Schedule to download new report

  3. After filling in the details, click on Save Schedule

  4. The Report will be available with a schedule ID in the Scheduled Reports Page on the basis of Report Interval type selected

    1. 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

    2. 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

    3. 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

  5. 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

  1. Create a new request

  2. Add the API details

  1. Select GET as request type,

  2. Enter the URL

  3. Add the header as mentioned above

  1. Click on Send (or Send & Save)

  2. 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

{
"viewershipChannels": [
{
"channelName": "Star Sports",
"channelId": "star111-sports-hd"
},
{
"channelName": "Start Flix",
"channelId": "star122-flix-hd"
}

],
"adAnalyticsChannels": [
{
"channelName": "Star Sports",
"channelId": "star111-sports-hd"
},
{
"channelName": "Start Flix",
"channelId": "star122-flix-hd"
}
]
}

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

{
"dateRange": {
"startDate": "2021-09-01",
"endDate": "2021-09-01",
"interval": "DAILY",
"startTime": "00:00",
"endTime": "23:00"
},
"viewershipAnalytics": [
{
"time": "2021-09-01 00:00:00",
"uniqueViewers": 6404,
"numberOfSession": 9445,
"viewershipMinutes": 248539
}
],
"totalSessions": 9445,
"totalViewershipMinutes": 248539,
"aggregatedViewers": 6404,
"dailyAverageNumberOfViewers": 6404,
"dailyAverageSessionCount": 9445,
"dailyAverageViewershipMinutes": 248539,
"avgSessionDuration": 26.31,
"avgSessionPerViewer": 1.47
}

7.3. Note on using APIs

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

Did this answer your question?