Liveplano

Example API Call

The data used in the following explanations comes from this API call

https://survey-api.csiolabs.me/?projectid=4963d1e1-0776-48c6-6690-83a76a7c7b5f&pageid=9178c8b3-1dc1-444d-65c0-8e5e142b7e50&respondentid=hn12345

This API call returns data on a Page basis. Each page may have multiple questions represented in the questions array

questions array

The outer level of the main data is an array called questions holding one JSON object for each individual question the respondent saw.

It typically has the following fields

{
	questionID: "2d6cdef9-d707-4e94-95cb-17eb89ee1944",		// unique questionID
	questionTitle: "q2",									// question human title
	duration: "1970-01-01T00:00:22.253Z",					// how long respondent took for this question
	endTime: "2016-07-31T08:22:37.981Z",					// end time for this question
	startTime: "2016-07-31T08:22:15.728Z",					// time respondent starts to see question
	eventStream: [],										// raw events
	qResponseData: {}										// sections of event data — exact contents vary by question type and response actions
}

Time data

All time fields are named as follows and occur multiple times in the data for different sections and events recorded.

startTime — Time a section or event started
endTime — Time a section or event ended
duration — diff between start and end times

productViewEvents array — Product click (view or select events)

This is where the respondent interacted with a product in some way other than just hovering the mouse pointer — they clicked the product on the shelf.

productViewEvents array is found within a given questions qResponseData object and typically looks like this: (Exact fields vary by client and product, null field values to be expected)

{
	description: "",
	duration: "1970-01-01T00:00:05.395Z",					// how long respondent viewed product
	startTime: "2016-07-31T08:22:22.420Z",					// time product was clicked
	endTime: "2016-07-31T08:22:27.815Z",					// time product was de-selected
	priceParams: {
		basePrice: 65,										// normal price of single product item
		priceLabelSetupID: "",
		priceLogicID: ""
	}
	productID: "4c58541c-61b9-4db5-6f2a-c3e1a7216d69",		// unique system productID
	productInstanceID: 247,
	title: "Rexona Roll on Motionsense Sexy Bou50",			// display title
	userMeta: {
		UPC: "4800888191212",								// client supplied productID
		claimText: "",
		offer: "",
		packSize: "50 Ml"
	},
	weightDescription: "50 Ml"
}

basketContent array — Products placed into shopping basket

Holds an object for every product placed into the virtual shopping basket along with data on qty in basket, price and so on:

{
	meta: {
		height: 11.5,
		width: 4.6
	},
	priceParams: {
		basePrice: 65,										// base price of a single product
		priceLabelSetupID: "",
		priceLogicID: ""
	},
	productID: "4c58541c-61b9-4db5-6f2a-c3e1a7216d69",
	quantity: 2,											// number of product items placed in basket
	title: "Rexona Roll on Motionsense Sexy Bou50",
	userMeta: {
		UPC: "4800888191212",
		claimText: "",
		offer: "",
		packSize: "50 Ml"
	},
	weightDescription: "50 Ml"
},

Note! This is the final contents of the basket. It does not indicate order or placing items in and taking items out of the basket.

basketEvents array — fine details on what was added and removed from the basket

This holds one object per interaction with the basket which is adding or removing a product from the basket or changing the quantity in basket for a given product.

{
	eventName: "ProductQtyChangedInCart",					// what happened (can be also ProductAddedToCart)
	newQty: 1,												
	oldQty: 0,
	priceParams: {
		basePrice: 65,
	},
	productID: "4c58541c-61b9-4db5-6f2a-c3e1a7216d69",
	quantity: 1,
	startTime: "2016-07-31T08:22:24.890Z",
	title: "Rexona Roll on Motionsense Sexy Bou50",
	userMeta: {
		UPC: "4800888191212",
		claimText: "",
		offer: "",
		packSize: "50 Ml"
	},
	weightDescription: "50 Ml"
},

Note! For every ProductAddedToCart event there is always at least one ProductQtyChangedInCart because technically adding a first product changes the qty in cart from zero to 1. If a user adds that product a second time only the ProductQtyChangedInCart event is triggered changing qty from 1 to 2.

Start time of survey (which is also start time of page on single page survey sessions)

The base start time for the page is in the startTime field at the outer level of the data:

{
	projectID: "93857dab-8b56-4a1c-b8a6-0d4bbdf4e2aa",
	respondentID: "davidtest",									
	startTime: "2016-07-31T08:21:57.942Z",						// start time of page
	endTime: "2016-07-31T08:22:37.981Z",						// end time of page
	duration: "1970-01-01T00:00:40.039Z",						// time spent on page
	PageID: "2c8800f4-5a53-4457-abaf-2286bcbd3adb",
	questions: []
}

Time to first product selection

The first product selection is the first time a respondent clicks a product on the shelf. This can be found by sorting the records in the productViewEvents array by startTime and taking the earliest.

The actual elapsed time to first product selection is thus:

    first_product_selected_startTime - pageStartTime

Time to first product in basket

The first product placed in the basket can be found by:

filtering the basketEvents array for ProductAddedToCart events
sorting the added to cart events on startTime and taking the earliest

The actual elapsed time to first product placed in basket is thus:

    earliest_productAddedToBasket_startTime - pageStartTime

Products in basket in order of selection

Products placed in basket do not have to have all their qty added in a single go. That's why we have both a ProductAddedToCart and ProductQtyChangedInCart events.

If one does not care about split adds, that is a sequence such as:

    productA added once -> productB added -> productA added a second time

Then the answer should be productA, productB and can be found in the basketEventsArray as follows:

Filter for only ProductAddedToCart events and sort by startTime
cross check with the entries in the basketContent array and remove product that is not in both (this accounts for product that was added to cart and then removed later)

If one needs to account for split adds; so the expected answer in the example above would be: productA, productB, productA then the answer is found in the basketEventsArray as follows:

Filter for only ProductQtyChangedInCart events and sort by startTime
cross check with the entries in the basketContent array and remove product that is not in both (this accounts for product that was added to cart and then removed later)

Note! use the productID field for the above cross checks.

Time to checkout

This is found by looking for the FinishShopping event in the eventStream array and using the startTime

Knowledge Base