The Analytics Tracking API allows you to track users interactions with UGC content through our widgets.

These interactions can be tracked as events. Media views, video plays, product checkouts are examples of events you might want to track.

Currently the API supports the following events on widgets:

Render: When a widget is rendered
Move: Clicks on slider move or new page loaded
Upload click: Clicks on the upload photo button
Filter click: Clicks on the filter button
View all: Clicks on the button that opens a Gallery widget from a Carousel widget

Also supports the following events on media:

Render: When the media thumbnail is seen in the browser viewport
View: When the media is opened in the modal (viewer)
Move: When you move to the next/prev media
Click: Clicks on media
Close: Media close clicks
Shop this product: Click on ‘Shop this product’ link on media (which redirects the user to the PDP)
Play click: Play clicks on media

Finally, we also should track the purchase events:

Checkout: Track when a product is purchased by a user in the customer website.

In some cases, you need to know whether an event was successfully sent to the Tracking API. If you have your browser’s developers tools open when you load a page that uses Olapic widgets, you can see the events being sent in the network tab. Look for requests sent to data.photorank.me. For more information, see the sections Request and Response format.

Once you have successfully implemented the Analytics tracking, it may take up to 24 hours for data appear in your Analytics reports.

Request

All tracking endpoints use the GET method.

GET / HTTP/1.1 
Host: data.photorank.me
 Accept: application/json

Authentication

Tracking methods require a public token to be accessible.

GET /?auth_token=5df38d HTTP/1.1
 Host: data.photorank.me

Response format

All the HTTP responses include a metadata section and all non-error responses also contains data sections.

The metadata section includes the HTTP status code, the messages associated to the status code, and the version.

The data section contains the timestamp and the analytics_id used to track the event.

{
 metadata: {
 code: 200,
 message: "OK",
 version: "v1.0"
 },
 data:
 {
 "timestamp": "2014-06-25 15:19:08.3000",
 "analytics_id": "12345"
 }
 }

Status Codes

Any of the following status codes should be expected for the API client.

Status	Message	Description
200	OK	This is the standard response for successful requests.
302	Found	A response with this status code will additionally provide a URL in the Location header field where the user should be redirected.
304	Not Modified	The server responses with this status code when the client has performed a conditional GET. It indicates the content the client previously received is still valid.
400	Bad Request	The request cannot be fulfilled due to bad formed URI or a missing parameter. The request should not be repeated without modifications.
403	Forbidden	The servers refuses to return the content due an Authentication issue. The client should not repeat the request unless proper credentials are used.
404	Not Found	The server has not found any resource matching the Request-URI or the resource is currently unavailable. The request could be repeated.
409	Conflict	The request could not be completed due to a conflict with the current state of the resource.
500	Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request. It could be a temporary issue.
503	Service Unavailable	The server is currently unable to handle the request due a programed maintenance. The inactivity period will be informed with proper advance via other channels.

Widget track

CATEGORY WIDGET ACTION

Track an action over a category widget, available actions are:

render : When the widget renders
move : Clicks on widget slider move or next page request
upload_click : Clicks on the upload photo button
filter_click : Clicks on the filter button
view_all : Clicks on the button that opens the Gallery widget from a Carousel widget

GET	`/track/widget/{instance_id}/category/{category_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}`

Example URI

GET /track/widget/instance_id/category/category_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
category_id	`int` (required) The id of the category
action	`string` (required) The action to track, the available options are: `render`, `move`, `upload_click`, `filter_click` or `view_all`
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 }
 }

Response 400

Headers

Content-Type: application/json

Body

[
 {
 "error": "Invalid params"
 }
 ]

STREAM WIDGET ACTION

Track an action over a stream widget, available actions are:

render : When the widget renders
move : Clicks on widget slider move or next page request
upload_click : Clicks on the upload photo button
filter_click : Clicks on the filter button
view_all : Clicks on the button that opens the Gallery widget from a Carousel widget

GET	`/track/widget/{instance_id}/stream/{stream_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}`

Example URI

GET /track/widget/instance_id/stream/stream_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
stream_id	`int` (required) The id of the stream
action	`string` (required) The action to track, the available options are: `render`, `move`, `upload_click`, `filter_click` or `view_all`
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 }
 }

Response 400

BEST PHOTOS WIDGET ACTION

Track an action over a best photos widget, available actions are:

render : When the widget renders
move : Clicks on widget slider move or next page request
upload_click : Clicks on the upload photo button
filter_click : Clicks on the filter button
view_all : Clicks on the button that opens the Gallery widget from a Carousel widget

GET	`/track/widget/{instance_id}/best/{action}{format}{?analytics_id,pics,ab_testing,segments}`

Example URI

GET /track/widget/instance_id/best/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
action	`string` (required) The action to track, the available options are: `render`, `move`, `upload_click`, `filter_click` or `view_all`
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 }
}

Response 400

STREAM NOT FOUND WIDGET RENDER

Track a stream widget render event where the stream couldn’t be found (this usually means the widget get rendered without any picture on it)

GET	`/track/widget/{instance_id}/stream/not_found/render{format}{?analytics_id,ab_testing,segments}`

Example URI

GET /track/widget/instance_id/stream/not_found/render.json?analytics_id=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 } 
}

Response 400

Media Track

CATEGORY WIDGET MEDIA ACTION

Track the following action over a media in a category widget:

render : When the media thumbnail is seen in the browser viewport
view : When the media is opened in the modal (viewer)
move : When you move to the next/prev media
click : Clicks on media
close : Media close clicks
play_click : Play clicks on media

GET	`/track/widget/{instance_id}/category/{category_id}/media/{media_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}`

Example URI

GET /track/widget/instance_id/category/category_id/media/media_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
category_id	`int` (required) The id of the category
media_id	`int` (required) The id of the media
action	`string` (required) The action to track, the available options are: `render`, `view`, `move`, `click`, `close` or `play_click`
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value], 
"analytics_id": [analytics_id]
 } 
}

Response 400

STREAM WIDGET MEDIA ACTION

Track the following action over media in a stream widget:

render : When the media thumbnail is seen in the browser viewport
view : When the media is opened in the modal (viewer)
move : When you move to the next/prev media
click : Clicks on media
close : Media close clicks
play_click : Play clicks on media

GET	`/track/widget/{instance_id}/stream/{stream_id}/media/{media_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}`

Example URI

GET /track/widget/instance_id/stream/stream_id/media/media_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
stream_id	`int` (required) The id of the stream
media_id	`int` (required) The id of the media
action	`string` (required) The action to track, the available options are: `render`, `view`, `move`, `click`, `close` or `play_click`
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 } 
}

Response 400

BEST PHOTOS WIDGET MEDIA ACTION

Track the following action over media in a best photos widget:

render : When the media thumbnail is seen in the browser viewport
view : When the media is opened in the modal (viewer)
move : When you move to the next/prev media
click : Clicks on media
close : Media close clicks
play_click : Play clicks on media

GET	`/track/widget/{instance_id}/best/media/{media_id}/{action}{format}{?analytics_id,pics,ab_testing,segments}`

Example URI

GET /track/widget/instance_id/best/media/media_id/action.json?analytics_id=&pics=&ab_testing=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
media_id	`int` (required) The id of the media
action	`string` (required) The action to track, the available options are: `render`, `view`, `move`, `click`, `close` or `play_click`
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 } 
}

Response 400

CATEGORY WIDGET "SHOP THIS PRODUCT" CLICK

Track clicks on ‘Shop this product’ links on a media from a category widget

GET	`/track/widget/{instance_id}/category/{category_id}/media/{media_id}/shop{format}{?analytics_id,pics,ab_testing,redirect_url,segments}`

Example URI

GET /track/widget/instance_id/category/category_id/media/media_id/shop.json?analytics_id=&pics=&ab_testing=&redirect_url=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
category_id	`int` (required) The id of the category
media_id	`int` (required) The id of the media
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
redirect_url	`string` (optional) URL of the page it’s going to be redirected (the status code of this response will be 302 and a Location header is going to be added to redirect the user). If this parameter if omitted the status code of the response will be 200.
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 } 
}

Response 400

Response 302

Headers

Content-Type: application/json

STREAM WIDGET "SHOP THIS PRODUCT" CLICK

Track clicks on ‘Shop this product’ links on media from a stream widget

GET	`/track/widget/{instance_id}/stream/{stream_id}/media/{media_id}/shop{format}{?analytics_id,pics,ab_testing,redirect_url,segments}`

Example URI

GET /track/widget/instance_id/stream/stream_id/media/media_id/shop.json?analytics_id=&pics=&ab_testing=&redirect_url=&segments=segments[]=country:US&segments[]=section:abc

URI ParametersHide

instance_id	`string` (required) Hash identifying the current widget instance
stream_id	`int` (required) The id of the stream
media_id	`int` (required) The id of the media
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
redirect_url	`string` (optional) URL of the page it’s going to be redirected (the status code of this response will be 302 and a Location header is going to be added to redirect the user). If this parameter if omitted the status code of the response will be 200.
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 } 
}

Response 400

Response 302

Headers

Content-Type: application/json

BEST PHOTOS WIDGET "SHOP THIS PRODUCT" CLICK

Track clicks on ‘Shop this product’ links on media from a ‘best photos’ widget

GET	`/track/widget/{instance_id}/best/media/{media_id}/shop{format}{?analytics_id,pics,ab_testing,redirect_url,segments}`

Example URI

GET /track/widget/instance_id/best/media/media_id/shop.json?analytics_id=&pics=&ab_testing=&redirect_url=&segments=segments[]=country:US&segments[]=section:abc

URI Parameters

instance_id	`string` (required) Hash identifying the current widget instance
media_id	`int` (required) The id of the media
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
pics	`int` (required) Number of media the widget is displaying
ab_testing	`int` (optional) AB Testing experiment number. Do not include this param if AB testing is disabled
redirect_url	`string` (optional) URL of the page it’s going to be redirected (the status code of this response will be 302 and a Location header is going to be added to redirect the user). If this parameter if omitted the status code of the response will be 200.
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc `key:value` pairs will be used to group and display the analytics results (segmentation), you can send as many pairs as needed, Only one value for each key is allowed

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 } 
}

Response 400

Response 302

Headers

Content-Type: application/json

Purchase Track

CHECKOUT

Track checkouts, this requires a transaction id and an array of products and their amount.

GET	`/track/transaction/{transaction_id}/checkout{format}{?analytics_id,products,segments,currency_code,referrer}`

Example URI

GET /track/transaction/transaction_id/checkout.json?analytics_id=&products=products[]=product-123:120.50&segments=segments[]=country:US&segments[]=section:abc&currency_code=EUR&referrer=referrer=https:/domain.com/checkout

URI Parameters

transaction_id	`string` (required) The Id of the transaction, all products in the same checkout should have the same transaction
format	`string` (optional) Example: .json The content type of the response, it can be either `.json` or `.gif` depending if you prefer a JSON or a 1x1 GIF as response
analytics_id	`string` (required) Value identifying the current user
products	`array` (required) Example: products[]=product-123:120.50 Array containing the products purchased in the transaction and the amount for each product. The format is `product_id:amount`.
segments	`array` (optional) Example: segments[]=country:US&segments[]=section:abc Segmentation information, `key:value` pairs will be used to group and display the results, you can send ad many pairs as needed, Only one value for each key is allowed
currency_code	`string` (optional) Default: USD Example: EUR The ISO 4217 Alphabetic code of the currency.
referrer	`string` (optional) Example: referrer=https://domain.com/checkout The URL of the checkout confirmation page

Response 200

Headers

Content-Type: application/json

Body

{
 "metadata": {
 "code": 200,
 "message": "OK",
 "version": "v1.0"
 },
 "data": {
 "timestamp": [timestamp_value],
 "analytics_id": [analytics_id]
 } 
}

Response 400