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:
-
In the header, click your username, and select API Access.
-
In the Visitor API section, copy the URL.
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
Parameter | Description | Type | Role | Example |
---|---|---|---|---|
| Request type. Use the value | String | Required |
|
| Site origin. To find out your site's origin, see Getting your site origin. | String | Required |
|
| 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 |
|
| 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 |
|
| Maximum number of affinities to return per item attribute. The API returns the top affinities by affinity score. The minimum value is The default value is ExampleLet's assume a visitor has the following affinity profile, consisting of three
If you retrieve the visitor's affinity profile without defining If, instead, you set
| Number | Optional |
|
| 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:
The possible values are:
The default value is | Boolean | Optional |
|
Request examples
GET https://inpref.com/visitorApi?method=affinityScores&
origin=shop_company_com&
cookieId=dsr77t.kstzihlx
GET https://inpref.com/visitorApi?method=affinityScores&
origin=shop_company_com&
cookieId=dsr77t.kstzihlx&
limit=5
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 thelimit
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 thedebug
parameter is set totrue
in the request.
{
"scores": {<affinity profile>},
"user": {<visitor information>},
"created_at": <create date and time>,
"updated_at": <update date and time>
}
{
"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.
{
"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"
}
{
"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.
Error message | Description | Solution |
---|---|---|
| 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. |
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide |
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a valid site origin as the value of the To find out your site's origin, see Getting your site origin. |
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a value that conforms to the following rules:
|
| The value of the | Provide a Frosmo ID that matches a visitor with an affinity profile as the value of the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a value that respects the minimum and maximum values for the |
| The value of the | Provide a value that respects the minimum and maximum values for the |