Difference between revisions of "GetRecoms"

From Gvp-public
Jump to navigation Jump to search
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{Api_Method_Spec|
 
{{Api_Method_Spec|
−
Description=This method returns the recommendations for the user. Unify openGVP recommendations method.
+
Description= This method maps the Recom API method introduced in OpenGVP 3.0 for integration with GVP through iTaas (named GetRecoms too), in order to deprecate other methods as [[GetNodeRecommendations]], [[GetRootRecommendationsCombined]], [[GetFullView]], [[GetRootRecommendationsByView]], [[GetUserRecommendations]]. As per GVP3.2, it manages and returns exclusively movies and TV series. It means that Banners (Editorial Recommendations non-related to a content) are not returned by this method.
−
 
 
  
 
|Parameters=
 
|Parameters=
Line 12: Line 11:
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
−
ParamName=chennelId
+
ParamName=channelId
 
|ParamType=int
 
|ParamType=int
−
|ParamRequired=required
+
|ParamRequired=optional
−
|ParamDescription=Id of the channel that wants to return the object information.
+
|ParamDescription=Id of the channel that wants to return the object information. If not passed or it takes the zero value, that is, the Root channel is used. This parameter only applies to VoD recommendations, that is, when the catalogType contains TVoD+SVOD User, SVoD User, SVoD or TVoD.
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
 
ParamName=num
 
ParamName=num
 
|ParamType=int
 
|ParamType=int
−
|ParamRequired=required
+
|ParamRequired=optional
−
|ParamDescription=Quantity of recommendation wants to be returned. Each source will return the quantity specified by num parameter.
+
|ParamDescription=Quantity of recommendation that wants to be returned. Number of items desired per source/view (when groupBySource=True) or overall number of items desired (when groupBySource=False). If not passed, the default value is:
 +
::5, when groupBySource=True;
 +
::50, when groupBySource=False.
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
 
ParamName=sources
 
ParamName=sources
−
|ParamType=int
+
|ParamType=list of int
−
|ParamRequired=required
+
|ParamRequired=optional
−
|ParamDescription=Number separated by comma that represent a kind of content wants to be filter the result. (1 - MostViewed, 2 - BestRated, 3 - Personal, 4 - Editorial)
+
|ParamDescription=A comma-separated list of desired source types to get recommendations from. In this case the engine will try its best to provide recommendations for all the requested views (though it might be possible that some views return fewer items than the requested number).
 +
:If this input param is not passed, a default value is used, according to the next criteria: If the instance is associated to a VoD catalog, VoD recommendations are requested (the catalogType is different than 8) and the channelId to use is the Root channel, the default value used is 4,3,1,2.
 +
:Otherwise, the default value used is 3,1,2.
 +
:If the list of sources include the 4 value (editorial recommendation), this source is processed firstly.
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
Line 33: Line 37:
 
|ParamType=int
 
|ParamType=int
 
|ParamRequired=optional
 
|ParamRequired=optional
−
|ParamDescription=Number that indicates the content type of the recommendation
+
|ParamDescription=Code for the [[ContentType]] to filter. Default is 0.
−
    0 - Any: It returns both Movie and Series
+
 
−
    1 - Movie: Used for movies
 
−
    2 - Series: Used for TV series
 
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
 
ParamName=catalogType
 
ParamName=catalogType
−
|ParamType=int
+
|ParamType=List of int
 
|ParamRequired=optional
 
|ParamRequired=optional
−
|ParamDescription=CatalogType: Number that indicates the sub-catalog to retrieve recommendations from (Subscrition or transactional)
+
|ParamDescription=A comma-separated list of desired [[catalogType]] to get recommendations from. Some combination of catalog types are not allowed:
−
    0 - Any: Transactional or subscription (hired by the user). Default for getNodeRecommendations and GetFullView
+
:0=TVoD+SVoD User and 3=SVoD cannot be given at the same time.
−
    1 - Subscription: Contents from subscriptions rented by the user (and inside the subscription sub-catalog). Default for GetRotRecommendationsCombined and GetRootREcommendationsByView
+
:1=SVoD User and 3=SVoD cannot be given at the same time.
−
    2 - Transactional: Contents from transactional sub-catalog
 
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
Line 51: Line 52:
 
|ParamType=boolean
 
|ParamType=boolean
 
|ParamRequired=optional
 
|ParamRequired=optional
−
|ParamDescription=If the groupBySource=True, the result will contain a ViewSet If the groupBySource=False, the result will contain a ItemList.
+
|ParamDescription=If the groupBySource=True, the internal OpenGVP result will contain a ViewSet If the groupBySource=False, the internal OpenGVP result will contain a ItemList. This has no effect in UNI API response, as a List of CatalogItems is always returned.
−
Defaults in server to: false.
+
:Defaults in server to: True.
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
 
ParamName=filterType
 
ParamName=filterType
−
|ParamType=array
+
|ParamType=List of int
 
|ParamRequired=optional
 
|ParamRequired=optional
−
|ParamDescription=
+
|ParamDescription= A comma-separated list of desired [[filterType]] to apply to VoD and LinearTV recommendations. This is a new parameter added in OpenGVP 3.2. Default is 0.
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
 
ParamName=timeFilterType
 
ParamName=timeFilterType
−
|ParamType=array
+
|ParamType=List of int
 
|ParamRequired=optional
 
|ParamRequired=optional
−
|ParamDescription=
+
|ParamDescription= A comma-separated list of desired [[timeFilterType]] to apply to LinearTV recommendations.
 +
:This parameter is ignored unless the catalogType parameter does include the value 8=LinearTV (anyway, although it is ignored, it must contain a correct value).
 +
:Take into account that when this type of filtering is requested, the recommendations will be ordered by relevance as usually, they will not ordered by time.
 +
:This is a new parameter added in OpenGVP 3.2. Default is 0.
 
}}
 
}}
  
 
|Returns=
 
|Returns=
−
Returns a JSON object containing a JSON with the recommendations.
+
Returns a JSON object containing a list of Catalog Items:
  
 
'''Example:'''
 
'''Example:'''
Line 74: Line 78:
  
 
{
 
{
−
:    <span style="color: #a11;">"Content"</span>: {
+
:    <span style="color: #a11;">"Content"</span>: [
−
::      <span style="color: #a11;">"ViewSet"</span>: {
+
::             Array of [[CatalogItem]] objects
−
:::          <span style="color: #a11;">"1"</span>: [
+
:: ]
−
::::              Array of [[SimpleItem]] (OpenGVP Type) objects
 
−
:::          ]
 
−
:::          <span style="color: #a11;">"2"</span>: [
 
−
::::              Array of [[SimpleItem]] (OpenGVP Type) objects
 
−
:::          ]
 
−
:::          <span style="color: #a11;">"3"</span>: [
 
−
::::              Array of [[SimpleItem]] (OpenGVP Type) objects
 
−
:::          ]
 
−
:::          <span style="color: #a11;">"4"</span>: [
 
−
::::              Array of [[SimpleItem]] (OpenGVP Type) objects
 
−
:::          ]
 
−
::      }
 
−
:    }
 
 
}
 
}
  
 +
'''Full Example:'''
 +
{
 +
:  "StatusCode": 0,
 +
:  "Severity": 1,
 +
:  "StatusMessage": "OK",
 +
:  "Content": [
 +
:    {
 +
::      "CatalogItemId": 1388,
 +
::      "CatalogItemType": 1,
 +
::      "Title": "Gladiator",
 +
::      "Keywords": null,
 +
::      "Cast": "Connie Nielsen,Joaquin Phoenix,Ridley Scott,Russell Crowe",
 +
::      "IsAdult": false,
 +
::      "AgeRating": "12",
 +
::      "T9Title": "452342867",
 +
::      "Genres": "Documental,EN - Vacaciones",
 +
::      "ResizableImages": [
 +
::        {
 +
:::          "ID": 1,
 +
:::          "Url": "http://media-ottcert.labs.gvp.telefonica.com/storagearea0/IMAGES/00/00/02/23792_17F5254C9235CA8C.jpg",
 +
:::          "Width": 1280,
 +
:::          "Height": 800,
 +
:::          "Type": 1,
 +
:::          "Ext": ".jpg"
 +
::        }
 +
::      ],
 +
::      "ExtraMetadata": {
 +
:::        "Stars": 2.2,
 +
:::        "Audience": 613,
 +
:::        "Distributor": "MCA-PROV-PLAYLIST",
 +
:::        "CommercializationType": 5,
 +
:::        "Subscriptions": [
 +
::::          1275,
 +
::::          1501,
 +
::::          1525
 +
:::        ],
 +
:::        "Source":1,
 +
:::        "Trailers": []
 +
::      },
 +
::      "StartDate": 946677600,
 +
::      "EndDate": 1633907340,
 +
::      "ShortDescription": "Maximus is a powerful Roman general, loved by the people and the aging Emperor...",
 +
::      "ProductType": 2,
 +
::      "Quality": 1,
 +
::      "StatusDate": 1443442098
 +
:    },
 +
:  {
 +
::  ...
 +
:  }
 +
:  ]
 +
}
  
  
 
|Exceptions=
 
|Exceptions=
−
<span style="color: #a11;">TO BE COMPLETED</span>
+
<span style="color: #a11;"></span>
−
 
+
TBC
  
 
|Cache=
 
|Cache=
−
This method is not cached.
+
This method is cached for anonymous users.
  
 
|KnownIssues=
 
|KnownIssues=
Line 105: Line 147:
  
 
|VersionHistory=
 
|VersionHistory=
−
<span style="color: #a11;">TO BE COMPLETED</span>
+
{{{!}} border="2" style="width:800px;" cellpadding="5" cellspacing="0"
 +
{{!}}-  style="background:#88ccff;font-size:110%"
 +
! API Version Number
 +
! Change description
 +
! Changes author
 +
{{!}}- valign="top"
 +
! 3.2
 +
{{!}} Initial method design
 +
{{!}} Alberto Los Santos
 +
{{!}}}
  
 
|SeeAlso=
 
|SeeAlso=
 
* [[GetNodeRecommendations]]
 
* [[GetNodeRecommendations]]
 
* [[GetRootRecommendationsCombined]]
 
* [[GetRootRecommendationsCombined]]
 +
* [[GetFullView]]
 +
* [[GetRootRecommendationsByView]]
 
* [[GetUserRecommendations]]
 
* [[GetUserRecommendations]]
 
}}
 
}}

Latest revision as of 10:02, 3 October 2015

Description

This method maps the Recom API method introduced in OpenGVP 3.0 for integration with GVP through iTaas (named GetRecoms too), in order to deprecate other methods as GetNodeRecommendations, GetRootRecommendationsCombined, GetFullView, GetRootRecommendationsByView, GetUserRecommendations. As per GVP3.2, it manages and returns exclusively movies and TV series. It means that Banners (Editorial Recommendations non-related to a content) are not returned by this method.

Parameters

  • token (String, required)
A valid token for identifying the API session context. The token can be anonymous or logged.
  • channelId (int, optional)
Id of the channel that wants to return the object information. If not passed or it takes the zero value, that is, the Root channel is used. This parameter only applies to VoD recommendations, that is, when the catalogType contains TVoD+SVOD User, SVoD User, SVoD or TVoD.
  • num (int, optional)
Quantity of recommendation that wants to be returned. Number of items desired per source/view (when groupBySource=True) or overall number of items desired (when groupBySource=False). If not passed, the default value is:
5, when groupBySource=True;
50, when groupBySource=False.
  • sources (list of int, optional)
A comma-separated list of desired source types to get recommendations from. In this case the engine will try its best to provide recommendations for all the requested views (though it might be possible that some views return fewer items than the requested number).
If this input param is not passed, a default value is used, according to the next criteria: If the instance is associated to a VoD catalog, VoD recommendations are requested (the catalogType is different than 8) and the channelId to use is the Root channel, the default value used is 4,3,1,2.
Otherwise, the default value used is 3,1,2.
If the list of sources include the 4 value (editorial recommendation), this source is processed firstly.
  • contentType (int, optional)
Code for the ContentType to filter. Default is 0.
  • catalogType (List of int, optional)
A comma-separated list of desired catalogType to get recommendations from. Some combination of catalog types are not allowed:
0=TVoD+SVoD User and 3=SVoD cannot be given at the same time.
1=SVoD User and 3=SVoD cannot be given at the same time.
  • groupBySource (boolean, optional)
If the groupBySource=True, the internal OpenGVP result will contain a ViewSet If the groupBySource=False, the internal OpenGVP result will contain a ItemList. This has no effect in UNI API response, as a List of CatalogItems is always returned.
Defaults in server to: True.
  • filterType (List of int, optional)
A comma-separated list of desired filterType to apply to VoD and LinearTV recommendations. This is a new parameter added in OpenGVP 3.2. Default is 0.
  • timeFilterType (List of int, optional)
A comma-separated list of desired timeFilterType to apply to LinearTV recommendations.
This parameter is ignored unless the catalogType parameter does include the value 8=LinearTV (anyway, although it is ignored, it must contain a correct value).
Take into account that when this type of filtering is requested, the recommendations will be ordered by relevance as usually, they will not ordered by time.
This is a new parameter added in OpenGVP 3.2. Default is 0.


Returns

Returns a JSON object containing a list of Catalog Items:

Example:


{

"Content": [
Array of CatalogItem objects
]

}

Full Example: {

"StatusCode": 0,
"Severity": 1,
"StatusMessage": "OK",
"Content": [
{
"CatalogItemId": 1388,
"CatalogItemType": 1,
"Title": "Gladiator",
"Keywords": null,
"Cast": "Connie Nielsen,Joaquin Phoenix,Ridley Scott,Russell Crowe",
"IsAdult": false,
"AgeRating": "12",
"T9Title": "452342867",
"Genres": "Documental,EN - Vacaciones",
"ResizableImages": [
{
"ID": 1,
"Url": "http://media-ottcert.labs.gvp.telefonica.com/storagearea0/IMAGES/00/00/02/23792_17F5254C9235CA8C.jpg",
"Width": 1280,
"Height": 800,
"Type": 1,
"Ext": ".jpg"
}
],
"ExtraMetadata": {
"Stars": 2.2,
"Audience": 613,
"Distributor": "MCA-PROV-PLAYLIST",
"CommercializationType": 5,
"Subscriptions": [
1275,
1501,
1525
],
"Source":1,
"Trailers": []
},
"StartDate": 946677600,
"EndDate": 1633907340,
"ShortDescription": "Maximus is a powerful Roman general, loved by the people and the aging Emperor...",
"ProductType": 2,
"Quality": 1,
"StatusDate": 1443442098
},
{
...
}
]

}


Exceptions

TBC


Caching

This method is cached for anonymous users.


Known issues

  • None


Version history

API Version Number Change description Changes author
3.2 Initial method design Alberto Los Santos


See also

Retrieved from "https://wikis.tid.es/gvp-public/index.php?title=GetRecoms&oldid=1622"