Reporting

The following reports are available on the DataMilk Web Application User Interface in the Dashboard.

API definitions are provided in case the developer needs to access the information programmatically. The following API allows the user to retrieve reports from the system about various things including API behavior and consumption.

All reports are in table format with columns and values. The first section covers the generic reporting API followed by the specific type of reports, fields, and options.

getReportMetas

This api method provides descriptions of all the reports available in the system.

export type ReportFieldType = 'number' | 'string' | 'boolean' | 'Date';

export interface ReportFieldEnumMeta {
 name: string;
 label: string;
}

export interface ReportFieldMeta {
 name: string;
 description: string;
 type: ReportFieldType;
 enums?: ReportFieldEnumMeta[];
}

export interface ReportMeta {
 id: string;
 name: string;
 description: string;
 fields: ReportFieldMeta[];
}

export type ReportMetasGetRequest = DmRequest;

export interface ReportMetasGetResponse {
 reportMetas: ReportMeta[];
}

getReportData

Use this method to fetch report data from the system.

Request

export type AggregationPeriod = 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'ALL';

export interface ReportGetRequest {
 reportMetaId: string;
 start?: number;
 limit?: number;
 orderBy?: OrderBy[];
 aggregateBy?: AggregationPeriod;
 filterBy?: FilterItem;
}

export type ReportRecord = Record<string, any>;

export interface ReportGetResponse {
 fields: ReportFieldMeta[];
 records: ReportRecord[];
}

The response contains descriptions of the fields and records of data provided as a map from field name to value.

API Stats Report

This report allows the developer to retrieve usage statistics for one or more API endpoints. It's often useful to aggregate this data in order to get counts for periods of time such as by day, and hour.

Report Meta Example

{
 id: 'API_STATS_REPORT_META',
 name: 'Api Stats Report',
 description:
   'Information on specific api calls or aggregation of api calls over a period of time.',
 fields: [
   {
     name: 'apiInstanceId',
     type: 'string',
     description: 'Unique id of the api instance if applicable',
   },
   {
     name: 'requestType',
     type: 'string',
     description: 'Type of request',
     enums: [
       { name: 'ContentRecommendation', label: 'Personal Expected Value' },
       { name: 'EngagementCounter', label: 'Personal Bandit' },
       { name: 'OutlierDetection', label: 'Counter' },
     ],
   },
   {
     name: 'count',
     type: 'number',
     description: 'How many times the api was called.',
   },
   {
     name: 'occurred',
     type: 'Date',
     description: 'When the API call occured',
   },
   {
     name: 'request',
     type: 'string',
     description: 'Request from client in JSON format. Not aggregatable',
   },
   {
     name: 'response',
     type: 'string',
     description: 'Response from server in JSON format. Not aggregatable',
   },
 ],
}

Fields

Name	Type	Description
apiInstanceId	string	The id of the api being queried.
apiType	string	The type of API, e.g. PEV, PBandit, Counters, OutlierDetection
count	number	Number of times API call was made.
occurred	Date	When the request was made.
request	string	JSON formatted request made from the client. (Not available when aggregated)
response	string	JSON formatted response made from the server (Not available when aggregated)

Example - Number api calls per apiType for Jan 20, 2023

Request

{
 reportMetaId: 'API_STATS_REPORT_META',
 aggregateBy: AggregationPeriod.ALL,
 filterBy: {
   type: FilterItemType.Logical,
   operator: 'AND',
   value: [
     {
       type: FilterItemType.Comparison,
       name: 'occurred',
       operator: '>=',
       value: '2023-01-01T00:00:00Z',
     },
     {
       type: FilterItemType.Comparison,
       name: 'occurred',
       operator: '<',
       value: '2023-01-02T00:00:00Z',
     },
   ],
 },
}

Response

{
 fields: [
   { name: 'apiInstanceId', type: 'string', description: 'Unique id of the api instance' },
   {
     name: 'apiType',
     type: 'string',
     description: 'Type of API',
     enums: [
       { name: 'Recommendation', label: 'Personal Expected Value' },
       { name: 'EngagementCounter', label: 'Personal Bandit' },
       { name: 'OutlierDetection', label: 'Personal Bandit' },
     ],
   },
   { name: 'occurred', type: 'Date', description: 'When the API call occured' },
   { name: 'count', type: 'number', description: 'How many times the api was called.' },
 ],
 records: [
   { apiInstanceId: 'gds53gss3', apiType: 'PVR', occurred: '2023-01-01T00:00:00Z', count: '12552' },
   { apiInstanceId: 'ihi242dss', apiType: 'PVR', occurred: '2023-01-01T00:00:00Z', count: '12' },
   { apiInstanceId: 'fdsf2341', apiType: 'Counter', occurred: '2023-01-01T00:00:00Z', count: '24655' },
 ],
}

Personal Expected Value Stats Report

Name	Type	Description
title	string	Title of the page as extracted by DataMilk
url	string	The page url that was served.
imageUrl	string (optional)	Top image for collection or product pages (not applicable for search results)
percentageRecommended	number	Out of the last n API responses (n TBD), what percentage of API responses contained this item. NB. Not built yet
countRecommended	number	How many times this item was sent in a response.
averagePosition	number	The average position in the API response list of results. E.g. 2 would indicate on average this was the second item in the response.
popularityScore	number	A score representing how likely visitors are to visit this page across last n API responses
salesScore	number	Score representing how likely visitors are to convert after visiting this page across last n API responses
orderValueScore	number	Score representing the typical value of purchases after visitors visit this page across last n requests
optimizationGoalScore	number	Optimization goal score Aggregate of the personalized scores over the last n sessions Default goal is pEV later will be settable to popularity, sales or value
pageType	string	For example: ' ProductCollection', 'Product', or 'SearchResults'

Personal expected value algorithms serve content optimized for specific goals such as click through rate, AOV, and conversion rate. Developers can see the general statistical behavior of these Api instances with this report such as what items are being recommended the most, most likely to convert, have highest AOV for the shoppers that visited the site.