Security, Privacy, AI and CSR information for all Piano products now lives in one place. Explore our Compliance Center.
Audience
English French
English French

/segment/lookalike/update

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

Bash
$ 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"]
}

Last updated: