Analytics Metadata

Analytics metadata allows you to attach additional context to your Public Query requests and Event reports. This metadata is then available in Analytics for filtering and segmentation, helping you better understand how different user segments interact with your search.

Automatically tracked metadata

LupaSearch server automatically extracts the following metadata from incoming requests:

Key	Description	Example
`country`	Country derived from the request IP address	`"US"`
`deviceType`	Device type derived from the `User-Agent` header	`"desktop"`
`browser`	Browser name derived from the `User-Agent` header	`"Chrome"`
`language`	Language derived from the `Accept-Language` header	`"en"`
`platform`	Operating system derived from the `User-Agent` header	`"Windows"`

Note: Automatically tracked values may be inaccurate if the request passes through a proxy, CDN, or similar intermediary that modifies headers or masks the client IP address or original request headers.

Custom metadata

In addition to automatically tracked values, you can send your own custom metadata keys. Custom metadata is combined with the automatically tracked values, and can be used for more granular analytics segmentation.

Custom metadata values must be strings. You can send up to 10 custom keys per request.

Sending metadata with Public Query

Include the analyticsMetadata field in your Public Query request body:

{
  "searchText": "television",
  "limit": 10,
  "analyticsMetadata": {
    "storeId": "store-123",
    "abTestVariant": "B",
    "customerSegment": "premium"
  }
}

Sending metadata with Events

Include the metadata field in your Event request body:

{
  "queryKey": "ax2q422v8f7z",
  "name": "itemClick",
  "searchQuery": "television",
  "itemId": "66419592",
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1",
  "metadata": {
    "storeId": "store-123",
    "abTestVariant": "B"
  }
}

Limitations

Custom metadata object can contain a maximum of 10 keys per request.
All custom metadata values must be strings (or string arrays for multiple values)
Custom keys that conflict with automatically tracked keys (country, deviceType, browser, language, platform) will override the automatically detected values.