Last updated: Dec 27 2017

Area: Episerver Profile Store Applies to versions: 1.3.0 and higher

Filtering, paging and sorting

This topic describes how to search for profiles and tracked events using filters, paging and sorting using the API in Episerver Profile Store.

Endpoints

Note: Replace each {x} placeholder in the following endpoints with an appropriate value.

TrackEvents

GET /api/v1.0/trackevents/?$filter={1}&$skip={2}&$top={3}&$orderBy={4}

Profiles

GET /api/v1.0/profiles/?$filter={1}&$skip={2}&$top={3}&$orderBy={4}

Usage

The querystring parameters are named according to the Microsoft Rest API Guidelines.

  1. $filter. Filters the results to be returned.
  2. $skip. Returns results from the specified offset.
  3. $top. Returns the specified number of results.
    • Together the $skip and $top parameters are used for client-driven paging.
    • Optional parameters.
    • If not specified, default values are: $skip=0 $top=100.
    • See Client-driven paging.
  4. $orderBy. Sorts the results according to the specified property.

Data structures and search

Note: Wildcard searching with * is not supported.

Note: The Payload object in TrackEvent is a dynamic object and is defined by a specific tracking implementation.

TrackEvents

{
   "DeviceId":"91687965-bc76-49a2-862c-e014441b8f6b",
   "EventType":"home",
   "Value":"Visited the start page.",
   "PageUri":"http://localhost:50244/en/",
   "RemoteAddress":"::1",
   "Headers":{},
   "Payload":{},
   "EventTime":"2017-09-15T07:16:34.7957819Z",
   "CountryCode":"Localhost"
}

Profiles

{
   "ProfileId":"df0a2b9e-4d78-4ae1-9db0-6cb0db0cda04",
   "DeviceIds":[
      "91687965-bc76-49a2-862c-e014441b8f6b"
   ],
   "Name":"John Doe",
   "UpdateTime":"2017-09-15T07:16:41.3501641Z",
   "FirstSeen":"2017-09-15T07:16:34.7957819Z",
   "LastSeen":"2017-09-15T07:16:34.7957819Z",
   "Visits":1,
   "Info":{
      "InferredCountry":"Localhost",
      "Email":"admin@example.com"
   },
   "ContactInformation":[
      "Mailable",
      "Known"
   ]
}

Segments

{
	"SegmentId": "fc68ee49-c0d0-4002-897c-9762fcfdb814",
	"Name": "Last seen within 1 week",
	"SegmentManager": "admin@example.com",
	"Created": "2018-01-31T02:58:01.3091778+00:00",
	"ModifiedBy": "admin@example.com",
	"Modified": "2018-01-31T02:58:01.3091778+00:00",
	"Archived": false,
	"AvailableForPersonalization": true,
	"LabelIds": Array[0][],
	"Labels": Array[0][],
	"FavoredBy": Array[0][],
	"ProfileFilter": {
	"$type": "EPiServer.Insight.Api.Models.ProfileRulesFilter, EPiServer.Insight.Api",
	"Rules": Array[1][
	  {
		"Date": {
		  "Field": "LastSeen",
		  "Method": "Within",
		  "Values": Array[1][
			"OneWeek"
		  ]
		}
	  }
	]
	},
	"Filter": {
	"range": {
		  "LastSeen": {
			"gt": "now-7d",
			"lt": "now"
		  }
		}
	},
	"MatchingProfiles": 1,
	"LastProfileCount": "0001-01-01T00:00:00",
	"Source": "default"
	}
}

Search specifying JSON property name

You can search anything by specifying the JSON property name as the field in the filter.

TrackEvents

EventType eq home

Profiles

Visits gt 1

Segments

SegmentName eq LastWeek

Search within nested objects

To search within nested objects, use the dot notation to build up the field name in the filter.

For example using TrackEvent, see the following Payload object example from the tracking as implemented in the Episerver Commerce Quicksilver sample site.

{
   "Payload":{
      "recContent":"refCodeOnly",
      "channel":"web",
      "category":"Fashion>Mens",
      "type":"category",
      "ip":"::1",
      "session":null,
      "cuid":null,
      "site":null,
      "clientToken":null,
      "lang":"en",
      "currentURI":"http://localhost:50244/en/fashion/mens/",
      "previousURI":"http://localhost:50244/en/fashion/mens/mens-shoes/p-36127195/",
      "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 
(KHTML, like Gecko) Chrome/46.0.2486.0 Safari/537.36 Edge/13.10586", "user":{ "name":"John Doe", "email":"admin@example.com" } } }

TrackEvents

When filtering based on email in a user object in Payload, use the following field name:

Payload.user.email eq admin@example.com

Profiles

When filtering based on Email in the Info object, use the following field name:

Info.Email eq admin@example.com

Responses

Responses are in JSON format. Two types of responses can be expected:

  • Successful response
    • Contains the following properties:
      • total. Total number of results on the server regardless of paging.
      • count. Number of results returned for the current request. Affected by the $top parameter.
      • items. Collection of results.
  • Error response
    • See ErrorResponse in the Microsoft Rest API Guidelines.
    • Returns the following property:
      • error which contains:
        • code. HTTP response code.
        • message. Error message or description.

Date and time format

The following standard for date and time is supported: ISO 8601 (UTC)

Examples:

  • Date: 2017-10-09
  • Combined date and time in UTC: 2017-10-09T06:22:28+00:002017-10-09T06:22:28Z

Examples

Profiles filtered by device id

GET /api/v1.0/profiles/?$filter=DeviceIds eq xxxxx

Profiles filtered by email

GET /api/v1.0/profiles/?$filter=Info.Email eq user@example.com

Sorting of profiles on Name

GET /api/v1.0/profiles/?$filter=LastSeen gt 2017-09-01&$orderBy=Name ASC
GET /api/v1.0/profiles/?$filter=FirstSeen lt 2017-09-01&$orderBy=Name DESC

Sorting of events on CountryCode

GET /api/v1.0/trackevents/?$filter=PageUri eq http://www.host.com&$orderBy=CountryCode ASC

Profiles within a time range

GET /api/v1.0/profiles/?$filter=FirstSeen gt 2017-09-01T00:00:00Z and FirstSeen lt 2017-09-30T00:00:00Z

Events within a date range belonging to a specific profile

GET /api/v1.0/trackevents/?$filter=EventTime gt 2017-09-01 and EventTime lt 2017-09-30 and ProfileId eq yyyyy

Events within a time range belonging to a specific device

GET /api/v1.0/trackevents/?$filter=EventTime gt 2017-09-18T08:15:35Z and EventTime lt 2017-09-20T08:15:35Z and DeviceId eq xxxx

Paging of events that occurred before a specific date (returns page 3 with a page size of 10 results)

GET /api/v1.0/trackevents/?$filter=EventTime le 2017-09-30&$skip=20&$top=10

Specify precedence using parentheses

If not supplied, logical operators are evaluated left to right.

GET /api/v1.0/trackevents/?$filter=Payload.value1 gt 2 or (Payload.value2 le 3 and Payload.value3 eq 3)

Total number of events for URL

GET /api/v1.0/trackevents/?$filter=PageUri eq http://www.url1.com

Get segment by name

GET /api/v1.0/segments/?$filter=SegmentName eq LastMonth

Get segment by Id

GET /api/v1.0/segments/fc68ee49-c0d0-4002-897c-9762fcfdb814

JSON response with count and total

{
total: 10,
count: 10,
items: {
{...},
{...},
...
}
}
Date: 2017-10-09
Combined date and time in UTC: 2017-10-09T06:22:28+00:00
2017-10-09T06:22:28Z
20171009T062228Z

 

Related topics

Comments