Today we're announcing a new feature at Mouseflow.com, API access, that lets you extract recording data, page analysis data and statistics through our API. You can integrate Mouseflow data in your existing products, create services that analyze or monitor your recording data or create widgets/apps that use information from your Mouseflow account.
A new way of reselling Mouseflow services
Many of our customers are bureaus that sell Mouseflow services to their client base as a part of their service toolbox. With this new feature you can now let your clients access Mouseflow data directly without giving access to other websites or your account information. You can even integrate the Mouseflow data in your existing software or mobile apps and thereby giving your clients a unique user experience.
The feature is enabled for Medium or larger subscriptions and can be found on the Account page under the section Account Users.
User guide
In order to use the API you'll need an API token that can be found under the Account page on mouseflow.com. The API token is in the API section in the bottom left corner of the screen.
The API is called with HTTP GET's and outputs the data in either XML or JSON format.
Here's a list of the API functions:
http://mouseflow.com/api/getwebsites
http://mouseflow.com/api/getrecordings
http://mouseflow.com/api/getpageviews
http://mouseflow.com/api/getpagelist
Each of the API methods are described in detail below:
1. Getwebsites
Retrieves a list of registered websites on your Mouseflow account
Required parameters:
email=[your email, required]
token=[your API token, required]
Optional parameters:
result=["xml" / "json"] [optional, default: json]
Output:
WebsiteList: The element containing Website elements
Website: The container element for one website
Id: The internal ID for the website. Is used in other API calls to reference the website
Name: The description you have given the website
Recordings: The number of recorded sessions on the website
RecordingStatus: The current recording status. Can be "Recording", "Paused", "Stopped" and "NotInstalled"
Domains: The domain(s) that have been registered with the website
Alignment: The alignment of the website (left, center, right, flexible)
Width: The width of the website in pixels
PageIdentifiers: The list of page identifiers
ExcludedIpAddresses: The list of excluded IP addresses or IP ranges
Examples:
http://mouseflow.com/api/getwebsites?email=my@email.com&token=F8V6389G19DV210
2. Getrecordings
Retrieves a list of recorded sessions, based on your input criteria
Required parameters:
email=[your email, required]
token=[your API token, required]
website=[the website ID, required]
Optional parameters:
timezone=the timezone you want the date/time values represented in [minutes compared to UTC. Default: UTC]
datefrom=show recordings from this date [yyyy-mm-dd]
dateto=show recordings to this date [yyyy-mm-dd]
pagesmin=minimum number of visited pages
pagesmax=maximum number of visited pages
visitmin=minimum visit length in seconds
visitmax=maximum visit length in seconds
entrypage=the URL of the landing page
country=the country code of the visitor (two-character code)
browser=filter by browser name
os=filter by operating system
referrer=filter by a specific referrer
screenres=filter by a specific screen resolution [ex: 800x600]
result=["xml" / "json"] [optional, default: json]
Output:
RecordingList: The element containing Recording elements
Recording: The container element for one recording
Id: The internal ID for the recording. Is used in other API calls to reference the website
LastUpdated: The latest date/time when there was recorded activity
IP: The IP address of the visitor
Country: The visitor's origin country
Language: The visitor's language/culture (in Language Culture code, e.g. en-GB)
EntryUrl: The URL of the landing page
PageCount: The number of visited pages in the recorded session
VisitLength: The total visit length in seconds
Browser: The visitor's browser
UserAgent: The complete UserAgent string
OS: The visitor's operating system
Referrer: The visitor's referring URL
Examples:
http://mouseflow.com/api/getrecordings?email=my@email.com&token=F8V6389G19DV210&website=30ad142c-91ce-4592-b96f-e879596b9365
3. Getpageviews
Retrieves a list of single pageviews, based on your input criteria
Required parameters:
email=[your email, required]
token=[your API token, required]
website=[the website ID, required]
session=[the recording ID, required]
Optional parameters:
timezone=the timezone you want the date/time values represented in [minutes compared to UTC. Default: UTC]
datefrom=show pageviews from this date [yyyy-mm-dd]
dateto=show pageviews to this date [yyyy-mm-dd]
clicksmin=minimum number of clicks
clicksmax=maximum number of clicks
visitmin=minimum visit length in seconds
visitmax=maximum visit length in seconds
country=the country code of the visitor (two-character code)
browser=filter by browser name
os=filter by operating system
referrer=filter by a specific referrer
screenres=filter by a specific screen resolution [ex: 800x600]
result=["xml" / "json"] [optional, default: json]
Output:
PageViewList: The element containing PageView elements
PageView: The container element for one pageview
Id: The internal ID for the pageview.
Session: The recording ID
PageId: The internal ID for the page
StartTime: The date/time of the first registered activity on the page
EndTime: The date/time of the last registered activity on the page
PageTitle: The title of the page
URL: The URL of the page
QueryString: The querystring parameters used on the page
FormInteraction: The form interaction on the page
MaxScrolledPercentage: The maximum scroll in percent compared to the page height
IP: The IP address of the visitor
Country: The visitor's origin country
Language: The visitor's language/culture (in Language Culture code, e.g. en-GB)
VisitLength: The total visit length in seconds
VisitLength: The total visit length without pauses in seconds
Browser: The visitor's browser
UserAgent: The complete UserAgent string
OS: The visitor's operating system
Referrer: The visitor's referring URL
Examples:
http://mouseflow.com/api/getpageviews?email=my@email.com&token=F8V6389G19DV210&website=30ad142c-91ce-4592-b96f-e879596b9365&session=40dd442c-91ce-4592-b96f-e879595b9b63
4. Getpagelist
Retrieves a list of the pages of your website along with statistical information
Required parameters:
email=[your email, required]
token=[your API token, required]
website=[the website ID, required]
Optional parameters:
limit=the maximum number of elements you want to retrieve
result=["xml" / "json"] [optional, default: json]
Output:
PageList: The element containing Page elements
Page: The container element for one page
Id: The internal ID for the page. Is used in other API calls to reference the website
Title: The page title
Views30Days: The number of recorded pageviews the last 30 days
AvgVisitLengthSec: The average visit length in seconds
AvgInteractionTimeSec: The average visit length without pauses
BounceRate: The percentage of hard bounces (where the visitor leaves the page immediately)
ClicksPerPageView: The average number of clicks per page view
LoadTimeMS: The average time it takes to render the page in the browser, in milliseconds
GrabTimeMS: The average time it takes to fetch the page contents from the server, in milliseconds
AvgScrollPercentage: The average value of maximum scroll reach in percent
PageHeight: The height of the page in pixels
HtmlSizeKB: The HTML size in KB.
Examples:
http://mouseflow.com/api/getpagelist?email=my@email.com&token=F8V6389G19DV210&website=30ad142c-91ce-4592-b96f-e879596b9365
ba5645f2-3be1-4ec6-a599-356070b1ff64|1|5.0