API call to update the lookalike configuration for a segment.
The user must be authenticated and have write permissions to the site group.
An audience segment can be enabled for lookalike modeling by setting the lookalike configuration to active using this API. When activating lookalike modeling, a predictive model will be trained, and new visitors on the site group will be classified with respect to how similar they are to the members of the audience segment. By default, the top 1 % of new users which are most similar to the segment members will be classified as so-called lookalikes. *This percentage can be adjusted with the *fraction field, assumed to be a double between 0 and 1.
Negative segment
By default, the predictive lookalike model will be trained with training data consisting of users within and outside of the audience segment. One can optionally specify one or more negative segments, if together with the original segment they create a natural split of the audience into several parts that do not overlap. For example, if the audience segment in question consists of females, it would be beneficial to train this model against training data from a male segment. This can be achieved by specifying the segment id for the negative segment. If the audience segment is 30-50 year olds, then the negatives can be a list, containing a <30 year olds segment, and a >50 year olds segment. Typical use cases for negatives are segments based on gender, age, income level, and similar properties.
A negative must be an existing segment you can read, other than the segment itself, and must not be listed twice. A negative that is not stored for the segment yet must also:
-
belong to the same site group as the segment
-
belong to the same segment group as the segment. A segment that is not in a segment group cannot get new negatives.
Otherwise the request fails with HTTP 400, or HTTP 403 for a segment you cannot read, and nothing is stored. Negatives that are already stored are not checked against the site group and the segment group, so they can be sent again or removed, and an empty list removes all of them.
Request
The request object has the following fields:
|
Name |
Type |
Required |
Description |
|---|---|---|---|
|
id |
String |
Yes |
The identifier for the audience segment. |
|
active |
Boolean |
No |
Enable or disable lookalike modeling for the segment. Note that the segment must also be active, see /segment/read. |
|
fraction |
Double |
No |
The fraction of the population in the site group which should be annotated as lookalikes. The value must be higher than 0 and below 1. |
|
negatives |
Array of String |
No |
Array of segment ids representing the opposite of this segment, which we should train the model against. |
Response
The response object has the following fields:
|
Name |
Type |
Description |
|---|---|---|
|
id |
String |
The identifier for the audience segment. |
|
siteGroupId |
String |
The site group identifier to which this audience segment belongs. |
|
active |
Boolean |
True if the segment has enabled lookalike modelling. |
|
fraction |
Double |
The fraction of the population in the site group which should be annotated as lookalikes. |
|
negatives |
Array of String |
Array of segment ids representing the opposite of this segment, which we should train the model against. Included in response only if it was specified to non empty value. |
Examples
$ python cx.py /segment/lookalike/update '{"id":"1234", "fraction":"0.09"}'
{
"id": "1234",
"siteGroupId": "5678",
"active": true,
"fraction": 0.09,
"negatives": ["3456"]
}
$ python cx.py /segment/lookalike/update '{"id":"1234", "negatives":["6789"]}'
{
"id": "1234",
"siteGroupId": "5678",
"active": true,
"fraction": 0.09,
"negatives": ["6789"]
}
$ python cx.py /segment/lookalike/update '{"id":"1234", "negatives":["6789", "101112"]}'
{
"id": "1234",
"siteGroupId": "5678",
"active": true,
"fraction": 0.09,
"negatives": ["6789", "101112"]
}