Pages

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

Table: Query parameters for Visitor API requests (affinity profiles)

ParameterDescriptionTypeRoleExample
method

Request type.

Use the value affinityScores.

StringRequired
method=affinityScores
origin

Site origin.

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

StringRequired
origin=shop_company_com
cookieIdLocal Frosmo ID of the visitor whose affinity profile you want to retrieve.StringRequired
cookieId=dsr77t.kstzihlx
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": 20,
    "Dawelt": 135,
    "Wakita": 328
  },
  "type": {
    "Hand Tools/Pliers": 123,
    "Hand Tools/Wrenches": 17,
    "Power Tools/Accessories": 68,
    "Power Tools/Drills": 170,
    "Power Tools/Saws": 15
  }
}

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": {
    "Dawelt": 135,
    "Wakita": 328
  },
  "type": {
    "Hand Tools/Pliers": 123,
    "Power Tools/Drills": 170
  }
}
NumberOptional
limit=5
debug

Define whether to return debugging information about the affinity profile.

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.

BooleanOptional
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.
  • 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>},
  "created_at": <create date and time>,
  "updated_at": <update date and time>
}
Response structure with debugging information
{
  "scores": {<affinity profile>},
  "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": {
      "Cakita": 96,
      "Wakita": 128
    },
    "type": {
      "Machine Tools/Chain Saws": 16,
      "Machine Tools/Large Tools": 48,
      "Other/Compressors": 32,
      "Power Tools/Drills": 16,
      "Power Tools/Woodworking": 112
    }
  },
  "created_at": "2022-03-03T11:55:13+02:00",
  "updated_at": "2022-03-03T12:05:05+02:00"
}
Example: Response with affinity profile and debugging information 
{
  "scores": {
    "brand": {
      "Cakita": 96,
      "Wakita": 128
    },
    "type": {
      "Machine Tools/Chain Saws": 16,
      "Machine Tools/Large Tools": 48,
      "Other/Compressors": 32,
      "Power Tools/Drills": 16,
      "Power Tools/Woodworking": 112
    }
  },
  "created_at": "2022-03-03T11:55:13+02:00",
  "updated_at": "2022-03-03T12:05:05+02:00",
  "debug": {
    "days": [
      {
        "start": "2022-03-03T00:00:00+02:00",
        "end": "2022-03-03T12:05:04+02:00",
        "counts": {
          "brand": {
            "Cakita": {
              "viewed": 8,
              "converted": 1
            },
            "Wakita": {
              "viewed": 8,
              "converted": 2
            }
          },
          "type": {
            "Machine Tools/Chain Saws": {
              "viewed": 2,
              "converted": 0
            },
            "Machine Tools/Large Tools": {
              "viewed": 2,
              "converted": 1
            },
            "Other/Compressors": {
              "viewed": 4,
              "converted": 0
            },
            "Power Tools/Drills": {
              "viewed": 2,
              "converted": 0
            },
            "Power Tools/Woodworking": {
              "viewed": 6,
              "converted": 2
            }
          }
        }
      }
    ],
    "start": "2022-01-02T12:05:12+02:00",
    "end": "2022-03-03T12:05:12+02: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.

Table: Visitor API error messages

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' missing
The cookieId query parameter is missing from the request URL.Provide the cookieId query parameter.
parameter 'cookieId' contains an empty value
The value of the cookieId query parameter is missing.Provide a non-empty value for the cookieId 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 local 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.