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.

   

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)

Parameter	Description	Type	Role	Example
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
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.

• 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": {
      "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
    }
  },
  "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
    }
  },
  "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 message	Description	Solution
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 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.