PUT login/apps/clustering/rules
Renato.neves (Talk | contribs) (→Global Parameters) |
(→Description) |
||
Line 8: | Line 8: | ||
The clustering results for each user can be retrieved using the API [[GET login/users/:user_id/clustering/features]]. | The clustering results for each user can be retrieved using the API [[GET login/users/:user_id/clustering/features]]. | ||
− | |||
− | |||
== Resource URL == | == Resource URL == |
Revision as of 20:05, 25 August 2015
Contents |
Description
Updates login app clustering rules.
When a user logs in using his credential, these rules will be evaluated by the clustering engine, which will determine the likelihood for each feature label, according to the classifier used to evaluate the feature.
For example, the feature could be "music", and the labels could be "rock", "pop" and "blues". The clustering engine goal is to determine the user's interest likelihood for each label from a given feature. Considering the previous example, an example of likelihoods could be: rock - 0.5, pop - 0.2, blues - 0.3, that is, the user seems to be more interested on "rock" music, with 50% probability.
The clustering results for each user can be retrieved using the API GET login/users/:user_id/clustering/features.
Resource URL
PUT https://api.socialidnow.com/v1/marketing/login/apps/clustering/rules
Parameters
JSON Parameters
rules | required | a hash containing the features and parameters used in the clustering engine. |
---|---|---|
features | required | a hash containing the classifier definition for each feature. |
parameters | optional | a hash containing global parameters used by the classifiers. |
Features
Each feature is composed by the labels you want to classify the user and the classifier used to evaluate the user data.
The feature is defined as follow:
labels | required | an array of labels |
---|---|---|
name | required | a string to identify the label |
[extra] | optional | extra parameters used by the classifier. |
classifier | required | a hash containing the classifier parameters |
type | required | the classifier algorithm |
[extra] | optional | extra parameters used by the classifier. |
Classifiers
The following classifiers types are available:
likes
This classifier uses full text search on user's Facebook likes based on keywords defined for each label.
Label extra parameters:
keywords | required | an array of keywords. Each keyword defined as words are searched using OR and keywords defined as phrases are searched using AND. Example: ["rock", "roll", "surf music"] will be searched for (rock OR roll) AND "surf music". |
---|
Classifier extra parameters:
categories | required | an array of Facebook likes categories. Example: ["Musician/Band", "Music", "Music award"] |
---|---|---|
threshold | optional | requires that the number of likes from the defined categories is at least the percentage defined in the threshold, considering all likes. Ex: 0.2, that is, 20% of likes should be in the categories defined by the parameter "categories". |
Global Parameters
The following parameters can be defined in the global hash "parameters", or inside each classifier definition, in order to reduce the scope:
excluded_words | optional | an array of keywords. The keywords should be words and not phrases. Example: ["hate", "bad", "ugly"] |
---|
The parameters defined inside a classifier will replace the global ones for that classifier. Example: if excluded_words is defined in both global and classifier parameters, only the excluded_words defined in the classifier scope will be used, discarding the global one (there is no merge between global and classifier excluded words).
Authentication
This API requires Social Login App authentication. See Authentication.
Response
Response Status
ok (200) | The request was successful. |
---|---|
unauthorized (401) | The authentication is wrong. See Authentication. |
unprocessable_entity (422) | Validation error in the parameters. |
internal_server_error (500) | An unknown error happened. |
Examples
Request
Use the JSON saved on rules.json file to update the clustering rules for the login app 138:
curl -iX PUT 'https://api.socialidnow.com/v1/marketing/login/apps/clustering/rules' \ -H 'Content-type: application/json' \ --data @rules.json \ --user 138:e8b9ca24f1b590af67e6271297d6e1f7226625d61c5b5daa1b2f215464e292cf
Example for rules.json:
{ "rules": { "features": { "music": { "labels": [ { "name": "rock", "keywords": [ "rock" ] }, { "name": "pop", "keywords": [ "pop" ] }, { "name": "blues", "keywords": [ "blues" ] }, { "name": "country", "keywords": [ "country" ] } ], "classifier": { "type": "likes", "categories": [ "Musician/Band", "Music", "Music award" ], "threshold": 0.1, "excluded_words": [ "soul" ] } }, "movies": { "labels": [ { "name": "drama", "keywords": [ "drama" ] }, { "name": "comedy", "keywords": [ "comedy", "comedia" ] }, { "name": "sci-fi", "keywords": [ "sci-fi", "scifi" ] }, { "name": "horror", "keywords": [ "horror", "terror" ] }, { "name": "adventure", "keywords": [ "adventure", "aventura" ] } ], "classifier": { "type": "likes", "categories": [ "Movie", "Movie genre", "Movies/music" ], "threshold": 0 } } }, "parameters": { "excluded_words": [ "hate", "bad", "ugly" ] } } }
Response
Response Headers
HTTP/1.1 200 Ok Status: 200