Skip to main content

Visitor API reference (affinity profiles)

Learn how to make a Visitor API request to retrieve a visitor's affinity profile.

For more information about affinity profiles, see Feature: Affinity.

If you want to retrieve a visitor's affinity groups, see Visitor API reference (affinity groups).

Requests

URL

The URL for Visitor API requests is https://<platform_instance>/visitorApi, where <platform_instance> is the domain name of your Frosmo Platform instance.

To get the URL for your Frosmo Platform instance:

  1. Log in to the Frosmo Control Panel, and select your site.

  2. In the header, click your username, and select API Access.

  3. In the Visitor API section, copy the URL.

    URL for Visitor API requests

Authentication

The Visitor API does not require authentication.

Methods

The Visitor API supports the GET HTTP method for retrieving visitor affinity profiles.

Syntax

To retrieve a visitor's affinity profile, make the following GET request:

GET https://<platform_instance>/visitorApi?method=affinityScores&
origin=<site_origin>&
cookieId=<local_frosmo_id>

Parameters

Query parameters for Visitor API requests (affinity profiles)
ParameterDescriptionTypeRoleExample

method

Request type.

Use the value affinityScores.

String

Required

method=affinityScores

origin

Site origin.

To find out your site's origin, see Getting your site origin.

String

Required

origin=shop_company_com

cookieId

Frosmo ID of the visitor whose affinity profile you want to retrieve.

To get the ID, see Getting a visitor's Frosmo ID.

String

Required

cookieId=dsr77t.kstzihlx

loginId

Login ID of the visitor whose affinity profile you want to retrieve.

The ID allows the platform to get the visitor's affinity profile across multiple browsers.

note

For the login ID to work on a site, login support must be enabled for the site. To enable the feature, if it's not already enabled, contact Frosmo support.

String

Optional

loginId=3364259119087832

limit

Maximum number of affinities to return per item attribute. The API returns the top affinities by affinity score.

The minimum value is 1. The maximum value is 30.

The default value is 10.

Example

Let's assume a visitor has the following affinity profile, consisting of three brand affinities and five type affinities:

{
"brand": {
"cakita": 448000,
"grayhawk": 48000,
"wakita": 584000
},
"type": {
"hand tools/kits": 112000,
"hand tools/wrenches and pliers": 232000,
"machine tools/chain saws": 196000,
"power tools/saws": 250000,
"power tools/woodworking": 168000
}
}

If you retrieve the visitor's affinity profile without defining limit, or if you set limit to 5 or higher, the above is what the API returns.

If, instead, you set limit to 2, the API only returns the top 2 affinities per attribute, that is, the two brand and type affinities with the highest affinity scores:

{
"brand": {
"cakita": 448000,
"wakita": 584000
},
"type": {
"hand tools/wrenches and pliers": 232000,
"power tools/saws": 250000
}
}

Number

Optional

limit=5

debug

Define whether to return debugging information about the affinity profile.

warning

Use the debugging information only for development and testing purposes. Do not use the information in production, since Frosmo does not guarantee that the information structure and content will remain the same.

The debugging information for an affinity profile consists of:

  • Interaction counts per attribute value per day

  • Time range for affinity tracking (start time and end time)

  • Recency weights used for calculating the final affinity scores

The possible values are:

  • false: Do not return debugging information.

  • true: Return debugging information.

The default value is false.

Boolean

Optional

debug=true

Request examples

Example: Retrieve a visitor's affinity profile
GET https://inpref.com/visitorApi?method=affinityScores&
origin=shop_company_com&
cookieId=dsr77t.kstzihlx
Example: Retrieve a visitor's affinity profile with a custom affinity limit
GET https://inpref.com/visitorApi?method=affinityScores&
origin=shop_company_com&
cookieId=dsr77t.kstzihlx&
limit=5
Example: Retrieve a visitor's affinity profile with debugging information
GET https://inpref.com/visitorApi?method=affinityScores&
origin=shop_company_com&
cookieId=dsr77t.kstzihlx&
debug=true

Responses

Success

On a success, the Visitor API returns the requested affinity profile in a JSON object. The response status code is 200.

The response object contains the following root properties:

  • scores: Object containing the affinity profile. By default, the API returns the top 10 affinities per attribute. You can override this default limit by using the limit parameter in the request.

  • user: Object containing visitor information e.g. the visitor's decile or whether the visitor is in the comparison group.

  • created_at: Date and time when the affinity profile was created.

  • updated_at: Date and time when the affinity profile was last updated.

  • debug: Object containing the debugging information. This property is included only when the debug parameter is set to true in the request.

Response structure without debugging information
{
"scores": {<affinity profile>},
"user": {<visitor information>},
"created_at": <create date and time>,
"updated_at": <update date and time>
}
Response structure with debugging information
{
"scores": {<affinity profile>},
"user": {<visitor information>},
"created_at": <create date and time>,
"updated_at": <update date and time>,
"debug": {<debugging information>}
}

Success examples

The following two examples show the same response without and with debugging information.

Example: Response with affinity profile only
{
"scores": {
"brand": {
"airio": 164000,
"cakita": 448000,
"comper": 12000,
"grayhawk": 48000,
"powerux": 12000,
"squeezer": 80000,
"wakita": 584000
},
"type": {
"hand tools/kits": 112000,
"hand tools/wrenches and pliers": 232000,
"machine tools/chain saws": 196000,
"machine tools/large tools": 44000,
"other/compressors": 224000,
"other/plumbing": 68000,
"power tools/drills": 180000,
"power tools/saws": 250000,
"power tools/woodworking": 168000
}
},
"user": {
"cookieId": "dsr77t.kstzihlx",
"loginId": "",
"decile": 8,
"isInComparisonGroup": false,
"source": "cookieId"
},
"created_at": "2023-06-26T15:05:42+03:00",
"updated_at": "2023-06-26T15:11:18+03:00"
}
Example: Response with affinity profile and debugging information
{
"scores": {
"brand": {
"airio": 164000,
"cakita": 448000,
"comper": 12000,
"grayhawk": 48000,
"powerux": 12000,
"squeezer": 80000,
"wakita": 584000
},
"type": {
"hand tools/kits": 112000,
"hand tools/wrenches and pliers": 232000,
"machine tools/chain saws": 196000,
"machine tools/large tools": 44000,
"other/compressors": 224000,
"other/plumbing": 68000,
"power tools/drills": 180000,
"power tools/saws": 250000,
"power tools/woodworking": 168000
}
},
"user": {
"cookieId": "dsr77t.kstzihlx",
"loginId": "",
"decile": 8,
"isInComparisonGroup": false,
"source": "cookieId"
},
"created_at": "2023-06-26T15:05:42+03:00",
"updated_at": "2023-06-26T15:11:18+03:00",
"debug": {
"days": [
{
"start": "2023-06-26T00:00:00+03:00",
"end": "2023-06-26T15:11:16+03:00",
"counts": {
"brand": {
"airio": {
"viewed": 8,
"addedToCart": 1,
"converted": 1
},
"cakita": {
"viewed": 26,
"addedToCart": 2,
"converted": 2
},
"comper": {
"viewed": 1
},
"grayhawk": {
"viewed": 4
},
"powerux": {
"viewed": 1
},
"squeezer": {
"viewed": 1,
"addedToCart": 1,
"converted": 1
},
"wakita": {
"viewed": 26,
"addedToCart": 4,
"converted": 4
}
},
"type": {
"hand tools/kits": {
"viewedItemList": 2,
"viewed": 3,
"addedToCart": 1,
"converted": 1
},
"hand tools/wrenches and pliers": {
"viewedItemList": 6,
"viewed": 6,
"addedToCart": 2,
"converted": 2
},
"machine tools/chain saws": {
"viewedItemList": 5,
"viewed": 9,
"addedToCart": 1,
"converted": 1
},
"machine tools/large tools": {
"viewedItemList": 2,
"viewed": 3
},
"other/compressors": {
"viewedItemList": 3,
"viewed": 12,
"addedToCart": 1,
"converted": 1
},
"other/plumbing": {
"viewedItemList": 2,
"viewed": 5
},
"power tools/drills": {
"viewedItemList": 3,
"viewed": 14
},
"power tools/saws": {
"viewedItemList": 2,
"viewed": 8,
"addedToCart": 2,
"converted": 2
},
"power tools/woodworking": {
"viewedItemList": 4,
"viewed": 7,
"addedToCart": 1,
"converted": 1
}
}
}
}
],
"rangeStart": "2023-04-27T15:14:40+03:00",
"rangeEnd": "2023-06-26T15:14:40+03:00",
"weights": {
"today": 8,
"last7Days": 5,
"last14Days": 3,
"last30Days": 2,
"last60Days": 1
}
}
}

Error

On an error, the Visitor API returns the response status code 400 or 404 and an error message.

Visitor API error messages (affinity profiles)
Error messageDescriptionSolution
affinity is not enabled for origin '<origin>'

The affinity feature is not enabled for the site, meaning the Frosmo Platform does not track affinities for visitors of the site.

Have Frosmo enable the affinity feature for the site. Contact Frosmo support.

parameter 'method' missing

The method query parameter is missing from the request URL.

Provide the method query parameter.

parameter 'method' contains an empty value

The value of the method query parameter is missing.

Provide a non-empty value for the method query parameter.

invalid method '<parameter_value>'

The value of the method query parameter, <parameter_value>, is invalid.

Provide affinityScores as the value of the method query parameter.

parameter 'origin' missing

The origin query parameter is missing from the request URL.

Provide the origin query parameter.

parameter 'origin' contains an empty value

The value of the origin query parameter is missing.

Provide a non-empty value for the origin query parameter.

invalid origin parameter '<parameter_value>'

The value of the origin query parameter, <parameter_value>, is invalid.

Provide a valid site origin as the value of the origin query parameter.

To find out your site's origin, see Getting your site origin.

parameter 'cookieId' or `loginId` missing

The cookieId or loginId query parameter is missing from the request URL.

Provide the cookieId or loginId query parameter.

parameter 'cookieId' contains an empty value
parameter 'loginId' contains an empty value

The value of the cookieId or loginId query parameter is missing.

Provide a non-empty value for the cookieId or loginId query parameter.

parameter 'cookieId' has invalid format

The value of the cookieId query parameter has an invalid format.

Provide a value that conforms to the following rules:

  • The length of the value is 1-24 characters.

  • The value contains only the following ASCII characters (in any combination):

    • Letters: A to Z (upper case) and a to z (lower case)

    • Numbers: 0 to 9

    • Special characters: . (period), _ (underscore), + (plus sign), - (hyphen)

user not found

The value of the cookieId query parameter does not match a visitor with an affinity profile. Either the visitor does not exist or the platform has yet to create an affinity profile for the visitor.

Provide a Frosmo ID that matches a visitor with an affinity profile as the value of the cookieId query parameter.

parameter 'limit' contains an empty value

The value of the limit query parameter is missing.

Provide a non-empty value for the limit query parameter.

parameter 'limit' invalid, expected value greater than 0

The value of the limit query parameter is not a positive integer.

Provide a value that respects the minimum and maximum values for the limit query parameter.

parameter 'limit' invalid, expected value less than or equal to 30

The value of the limit query parameter is greater than the maximum allowed value.

Provide a value that respects the minimum and maximum values for the limit query parameter.