The Analytics API allows you to extract your website's traffic data into several common formats, making it easy to integrate, analyze, or store your data within your own application.

The API accepts requests via standard HTTP GET, and can respond with XML, JSON, serialized PHP, and CSV.

Send requests to the following URL: http://stats.simpleisgood.ca/api/stats/4

IMPORTANT
For performance reasons, the API has restrictions on visitors-list, actions-list, and segmentation requests:
  • Max date range of 31 days
  • Max limit of 1,000 items (use the "page" parameter to get additional items, in batches of 1,000)
  • Max one simultaneous request per IP address per site ID.

Required parameters

The following parameters are required with every request to the API.

site_id

Every site has its own unique numeric ID. Your request must include the site's ID that you want to access data from. Available from your site preferences page.

sitekey

The sitekey is a 12-16 character string of random letters and numbers that is unique for every website and is assigned when you first register your website with us. Because you don't "login" to the API like you would to a normal website, every request must be authenticated by your sitekey. Available from your site preferences page.

type

The type of data you want. Note that some data types are only available with a premium account.

Tip: You can request more than one data type, just seperate them with commas: type=visitors,countries,searches.
Consolidating multiple types into one request will get you your data much faster than seperate requests for each type.

  • Popular items

    Results are ordered from most popular (e.g. most occurrences) to least popular.
    • custom - top custom data that you have logged for this site
    • pages - top content on your site. (Use type=pages&heatmap_url=1 to make the URLs append heatmap authentication to view directly)
    • pages-entrance - entrance/landing pages
    • pages-exit - exit pages (the last page someone sees on your site before leaving)
    • downloads
    • events - javascript/flash events (more info)
    • video - how many times each video that you're tracking was played (tack on video_meta=1 for extra details)
    • site-domains - how many hits each domain name received for a single site ID (only useful interesting if your site has sub-domains, or you are tracking more than one root domain with a single site ID)
    • links - incoming links (full URL)
    • links-domains - incoming links (by domain name)
    • links-outbound
    • searches - full search queries
    • searches-keywords - searches, broken down by individual keyword
    • searches-engines
    • searches-rankings - Google search rankings (ordered from best to worst)
    • searches-local
    • goals
    • split-tests
    • campaigns
    • countries
    • cities
    • regions
    • languages
    • web-browsers
    • operating-systems
    • screen-resolutions
    • hardware - mobile devices (iPad, etc)
    • hostnames - visitor hostnames, e.g. microsoft.com
    • organizations - visitor organizations, e.g. Microsoft Corp
    • engagement-actions - breakdown of visitor engagement by number of actions performed
    • engagement-times - breakdown of visitor engagement by time spent on site
    • segmentation - request specific data for a certain segment of visitors (e.g. top searches for visitors from Germany)
    • visitors-most-active - the people who have visited your site the most often, determined by IP address. If you are using custom data tracking or IP tagging to name this visitor, it will show their username instead of their IP address, but the "popularity" is still determined by IP address.
    • traffic-sources - how visitors are arriving at your site (link, search, email, advertising, etc)

  • Chronological items

    Results are ordered from newest to oldest.
    • visitors-list - a list of your visitors along with all the details about each of them. Filter by ip_address or uid to get visit history for a specific visitor.
    • actions-list - a list of the visitor actions that occured on your site. Can be filtered by session_id.
    • searches-recent - a list of the searches that led someone to your site on the requested date(s).
    • searches-unique - a list of the searches that led someone to your site for the first time ever (as far as knows).
    • links-recent - a list of the links that led someone to your site on the requested date(s).
    • links-unique - a list of the links that led someone to your site for the first time ever (as far as knows).
    • uptime - a list of uptime checks as an overview.
    • uptime-list - a list of uptime events.

  • Tallies

    • visitors - number of visitors
    • visitors-online - number of visitors currently active on your website. This value is always the "live" value; specifying a date has no effect.
    • visitors-unique - number of unique visitors
    • visitors-new - number of new (first time) visitors to your site
    • actions - number of visitor actions (sum of page views, downloads, and outbound links)
    • actions-pageviews - number of page views
    • actions-downloads - number of downloads
    • actions-outbounds - number of outbound links
    • actions-clicks - number of clicks (javascript events)
    • actions-average - average number of actions per visitor
    • time-average - average time on site per visitor, in seconds
    • time-average-pretty - average time on site per visitor, formatted like: 3m 10s
    • time-total - total amount of time spent on your site by all visitors combined, in seconds
    • time-total-pretty - total amount of time spent on your site by all visitors combined, formatted like: 6d 19h 5m
    • bounce-rate - percentage of visitors who only viewed one page

  • Alerts

    • alert_id
      When you setup alerts and get them via email, the URL will be something like: http://stats.simpleisgood.ca/a/123

      The "123" at the end is the alert ID. For automated processes, we have made it so you can pass this alert ID into the API and the API will find the session ID and return the details to you, as if you had originally sent in a type=visitors-list&session_id=... request. In this one instance, you do NOT need to specify a 'type' parameter. The only thing you need to pass in is the site_id, sitekey, and alert_id. Other parameters you could normally send in alongside a visitors-list request can be used here too, such as output=json, visitors-details=referrer_domain, etc.

      You will need to write code on your end to extract the alert ID from the end of the string before passing it to the API. You will also need to know the site ID (and hence sitekey) that this alert is associated with.

      Example:

      You get an alert with this URL: http://stats.simpleisgood.ca/a/123

      The email address that receives these alerts is unique for the site ID so you know what site ID and sitekey to pass to the API.

      You have a script that extracts the alert ID from the end of the URL. PHP example:

      <?php
      preg_match      ("#[0-9]+$#", "http://stats.simpleisgood.ca/a/123", $alert );
      // $alert[0] will now contain the alert ID.
      ?>

      Last step, take that alert ID and pass it to the API with the proper credentials:

      http://stats.simpleisgood.ca/api/stats/4?site_id=20&sitekey=30&alert_id={$alert[0]}


Optional parameters

The following parameters are optional. If a parameter is not included in your request, or the value specificied is invalid, the default value will be used automatically.

output

What format you want your data in.

Default value: xml
Accepted values: xml, php, json, csv


limit

The maximum number of results that you want returned. If you are requesting multiple types and/or "daily" values, this limit will apply to each group of data, not the overall set.

Default value: 50
Accepted values: Any number between 1 and 1000, or "all" for up to 5000 results (capped for performance reasons).


page

Use in combination with "limit" to page through results. For example, limit=100&page=2 will return results 101 - 200.

Default value: 1
Accepted values: Any integer greater than 0.


date

The date or date range you want to access. The maximum range is 366 days for Pro users, and 31 days for everyone else. If you give an invalid date or date range (range too large, end is before start, etc), we'll automatically use "today" instead. If you are requesting a date range for a "popular" or "tally" type, the value returned for each item is the total sum of that item's values from all dates within the date range - unless you specify the "daily" option, detailed below.

Default value: today
Accepted values:
  • Specific dates
    • YYYY-MM-DD - for a specific date, e.g. 2024-11-21
    • YYYY-MM-DD,YYYY-MM-DD - for a specific date range, e.g. 2024-10-01,2024-10-31
    • YYYY-MM - for an entire month, e.g. 2024-11
    • YYYY - for an entire calendar year, e.g. 2023

  • Relative dates
    These expressions provide you with an easy way to get dates relative to "today", without having to do your own "date math" - which is about as fun as watching paint dry. The dates shown below in the examples are being calculated live with the same code the API uses, using today's date, 2024-11-21. Note that "X" needs to be replaced by an actual number in your request.
    • today - returns today's date, 2024-11-21
    • yesterday - returns yesterday's date, 2024-11-20
    • X-days-ago - returns single date, X days ago. "3-days-ago" would return 2024-11-18
    • last-X-days - returns range of last X days, including today. "last-3-days" would return 2024-11-19,2024-11-21
    • previous-X-days - returns range of previous X days, before today. "previous-3-days" would return 2024-11-18,2024-11-20
    • this-month - returns range for the entire current month. In this case, 2024-11-01,2024-11-30
    • last-month - returns range for the entire last month. In this case, 2024-10-01,2024-10-31
    • X-months-ago - returns range for an entire month, X months ago. "3-months-ago" would return 2024-08-01,2024-08-31
    • this-week - returns range for current week, Sunday - Saturday. In this case, 2024-11-17,2024-11-23
    • last-week - returns range for last week, Sunday - Saturday. In this case, 2024-11-10,2024-11-16
    • X-weeks-ago - returns range for for an entire Sunday - Saturday week, X weeks ago. "3-weeks-ago" would return 2024-10-27,2024-11-02


daily

When you request a date range, by default the results returned are the total/sum values for the entire date range. If you would like the results to be returned on a per-day basis, then you can specify daily=1 in your request.

type=visitors&date=last-7-days
type=visitors&date=last-7-days&daily=1


Note, if all data types being requested are tally types (e.g., type=visitors,actions), and you are requesting CSV output with daily values, the output format changes so each line is "date,value".

Examples:
Tally data only: type=visitors,actions&date=last-7-days&daily=1&output=csv
Other data types: type=searches,visitors&date=last-7-days&daily=1&output=csv


hourly

For some data types, we track hourly data in addition to daily. Currently supported data types are visitors and actions. To request hourly data for a supported data type, just append hourly=1 to the request, and hourly data will be returned for all of the dates that you are requesting.

Note: if you request hourly data, the request can only contain data types that support this type of data. In other words, you can't mix hourly visitor data with daily top searches. These requests must be made seperately.

Also, when hourly data is requested, it is automatically broken down by individual days. In other words, daily=1 is automatically applied to these queries.

type=visitors
type=visitors&hourly=1
type=visitors&hourly=1&date=last-7-days


Set trends=1 to get the trend percentage returned along with the value. This is the same percent value you see in red or green next to each item in our reporting interface. The range we support is from -999 to 999. We do not return the '%' symbol with this value, so it's easier for you to manipulate on your end. If you are going to display it on your website or in a report, you'll probably want to add the '%' to the end of it so it's more clear what it is. type=searches&date=last-7-days&trends=1


item

Use this to get the stats for just a single item for the type you are requesting. This works different than the "filter" parameter below, which is a wildcard search. item is an exact match string. Sending in e.g. type=search&item=cookie will only return the results for the specific search of "cookie", whereas filter=cookie would also return results for "cookies", "oatmeal cookies", etc.

You can only specify one data type if you are also requesting item, since you can only specify one item per request.

Hot tip: Specify daily=1 to get the daily breakdown for this item, instead of just the total sum over your requested date range.

type=links-domains&date=last-7-days&item=google.com
type=links-domains&date=last-7-days&item=google.com&daily=1


heatmap_url

This works in conjuction with type=pages request. Appending &heatmap_url=1 to the request will append the heatmap viewing authentication to the end of the URL, so these links can be clicked on directly to view a heatmap for that page.

type=pages&heatmap_url=1


visitor-details

This is used in combination with type=visitors-list. There are many details associated with every visitor and by default we'll give you all of them. This is fine in most cases, but if you are requesting a large date range, or if you have a high traffic site, extracting all of those details can take a while. If you only need a few specific details about your visitors, use this to specify which ones as a comma seperated string, and the response will be much faster, and much quicker to transfer as it will be less data.

The details you specify must match the exact names of the field names that we output. Do a type=visitors-list request to see the available options you can specify here. These are singular instead of plural and use underscores instead of dashes, so be sure to keep that in mind! E.g. 'web_browser' instead of 'web-browsers'.

type=visitors-list&visitor-details=ip_address,session_id,landing_page,geolocation,web_browser


time_offset

This parameter is available for type=visitors-list and type=actions-list. It lets you specify the time range (in seconds), relative to "now", of data returned. So if you requested type=visitors-list&time_offset=3600&limit=all, you would only get back visitor sessions from the last hour. Note that the default limit will still apply unless you specify one, so we recommend doing limit=all to make sure that all of them are returned.

When this value is request, the date parameter has no effect. The largest offset you can request is 86400 (1 day).


segments

If you are requesting type=segmentation, specify the segments you want returned here as a comma-seperated string. The values you can input here are the exact same as any of the "tally" or "popular" data types. For example, segments=visitors,bounce-rate,web-browsers

This will return the number of visitors and the top web browsers for the visitors who match your filters. This type of query works exactly like type=visitors-list, in terms of how you filter down to the segment of visitors you want. For example, if you wanted to filter down to all visitors who use who arrived via google.com, you would do type=visitors-list&domain=google.com. For segmentation, you would use the same domain parameter, but just change the type to segmentation: type=segmentation&domain=google.com. However, you also need to specify the segments you want returned for these visitors.

For example, if you wanted to view the number of visitors and the top web browsers for people who arrived via google.com, you could do this:
type=segmentation&domain=google.com&segments=visitors,web-browsers

There is an additional data type you can specify here as well, segments=summary. This will provide you with a summary of all of the visitors who match your filters. It's the same data that you see when you apply a filter within our stats interface - total visitors, actions, average actions per visit, bounce rate, and more:
type=segmentation&domain=google.com&segments=summary,countries,web-browsers


ip_address, uid, new_visitors, returning_visitors, online, heatmap, actions, time, href, landing, exit, search, search-local, domain, link, browser, os, resolution, country, city, language, hostname, org, source, shorturl, custom, goal, campaign, split

These filters are available for type=visitors-list and type=segmentation, and should be sent URL encoded. If you are having trouble getting these to work, we suggest you go to your vistitors page and play around with the filtering functionality on that page. The API is built on the same core as the website itself, so you can try applying filters in that interface and then copy/paste the URL variables into your API requests.

ip_address and uid override all other filters. In other words, if you filter by either of these parameters, all other filters are ignored.

Examples:
type=visitors-list&online=1&returning_visitors=1 (returning visitors who are online now)
type=visitors-list&new_visitors=1&heatmap=1 (new visitors who have heatmap data available)
type=visitors-list&actions=>5 (more than 5 actions)
type=visitors-list&time=60,120 (between 60 and 120 seconds online)
type=visitors-list&browser=firefox+3.5
type=visitors-list&domain=google.com
type=visitors-list&country=us

ip_address can be a single IPv4 or IPv6 address. For IPv4, you can also specify multiple IPs and/or ranges. To specify a range, just seperate the two IP boundaries with a comma. For multiple IPs or ranges, seperate each one with a pipe, "|". Examples:
type=visitors-list&ip_address=65.0.0.0,85.0.0.0
type=visitors-list&ip_address=65.0.0.0,85.0.0.0|32.12.220.89
type=visitors-list&ip_address=65.0.0.0,85.0.0.0|32.12.220.89|150.0.0.0,155.0.0.0

The custom type is for those of you using custom data tracking or IP tagging. It is an array so you can filter by more than one type, set the keys to any of the variable names you are using (username, email, etc) and the value of each key to whatever you are looking for, e.g., type=visitors-list&custom[username]=billy&custom[email]=billy@billy.com. If you are using IP tags, you'll want to use custom[username] as your filter.


session_id, action_type, href, ip_address, uid

These filters are available for actions-list. 'href' should be sent URL encoded. If you are having trouble getting these to work, we suggest you go to your actions page and play around with the filtering functionality on that page. The API is built on the same core as the website itself, so you can try applying filters in that interface and then copy/paste the URL variables into your API requests.

NOTE: session_id can also be used with visitors-list, to return the visitor details of a specific session ID, regardless of date range set.

Valid action_types are pageview, download, outbound, event, video, and search.

Examples:
type=actions-list&href=%2Fcontact.php
type=actions-list&session_id=123
type=visitors-list&session_id=123
type=actions-list&action_type=download


custom_keys_multi_values

This parameter works with type=visitors-list and type=actions-list requests.

If you use custom visitor data and log multiple values for the same key, all of them are stored on our end, but we've always only output the last one logged. Recently we've had requests to output all of them, which is now done automatically in the web UI, but changing this in the API requires changing the structure of the output, which would break existing scripts that pull data from our API. So we added this new parameter instead, which tells the API to output all custom data values for all keys it has for each visitor session. Chances are high wou don't need to use this parameter, but if you do, it's now available.

Note that this parameter changes the structure of the output of the custom key in the output. For PHP and JSON outputs, each key will now be an array of values rather than just a single string value, even if only one value exists for any or all keys. For XML output, you may see multiple child tags with the same key (but each having a different value) in the <custom /> tree. For CSV output, all the key/value pairs have always been crammed into a single column, that remains the case, but there will now be potentially more of them.

To use this option, just add custom_keys_multi_values=1 to type=visitors-list and type=actions-list requests.


video_meta

This parameter only works with type=video requests. By default a type=video request will only return the number of plays for each video. There is more information available, such as average time spent watching. However if you are requesting data for "today" it can be a bit intensive to calculate for all videos, so this data is not returned by default. Just add video_meta=1 to the request and this data will be calculated and returned.


filter

This parameter only works with the "popular" data types. You can use this parameter to filter down to only the results you want. For example, if you ran a real estate website that had properties in multiple locations, you could use this to filter down your search results on a per city basis, for example, type=searches&filter=portland or type=searches&filter=seattle. You can also use "negative" filters, which will filter down the results to everything that does NOT match the filter. If your real estate website was mainly in the Portland area, but you wanted to see all the searches that did NOT include the word Portland, you do that by specifying an exclamation point in front of the filter. For example, type=searches&filter=!portland.


json_callback, json_var

Using these parameters, you can place API requests inside a <script> tag, and assign the results to a variable ($json_var) or pass the results to a function ($json_callback) elsewhere in the javascript code on the page. Using this mechanism, the JSON output from the API request is loaded when the enclosing web page is loaded.

This method of trickster cross-domain "Ajax" is no longer necessary as our API now includes a Access-Control-Allow-Origin: * header, allowing actual Ajax calls to our API to be made cross-domain. But for backwards compatibility, this method will always be available.

These values must meet standard JavaScript variable requirements: only letters, numbers, underscores, and periods are allowed.

Attention jQuery users! If you are using the $.getJSON() function, you need to declare "json_callback=?" - yes, that's a question mark!

Example json_callback:

<script>
function my_callback( data ) {
  // "data" will become the JSON object containing the entire set of API results
  alert( data );
}
</script>
<script src="http://stats.simpleisgood.ca/api/stats/4?...output=json&json_callback=my_callback">

Example json_var:

<script>
// "my_var" will become the JSON object containing the entire set of API results
var my_var;
</script>
<script src="http://stats.simpleisgood.ca/api/stats/4?...output=json&json_var=my_var">

null_values

By default, result sets exclude all fields that have "empty" or "null" values, which saves considerable bandwidth and memory. This is particularly relevant for type=visitors-list, where many of the potential fields may be empty. If this behavior is undesirable, you can disable it by specifying null_values=1 in your request, but we ask that you only do this if necessary. Your code should already be testing if a value exists and is valid before using it.

type=visitors-list&null_values=1

Default value: 0 (off)
Accepted values: 1 (on) or 0 (off)


app

If you have created an application or widget that is grabbing data from our API, we'd appreciate it if you would put the name of your program in here so that we can keep statistics on how the API is being used and what applications are most popular.

Default value: none
Accepted values: Any string up to 128 characters. (Be sure to URL-encode if it contains non-alphanumeric characters).



Responses

Popular and Tally data types

The response will be a group of items with the following keys. Popular data is ordered most popular to least popular. Tally data only returns a single item, unless the "daily" parameter is specified.

IMPORTANT: If all data types being requested are tally types (e.g., type=visitors,actions), and you are requesting CSV output with daily values, the output format changes so each line is "date,value". Example: type=visitors,actions&date=last-7-days&daily=1&output=csv

  • title - the name, title or description of the item
  • value - the item's value (typically, the number of occurences)
  • value_percent - the item's value as a percent of the total values of all other items in the same category
  • url - a URL of the item itself, if applicable (pages, incoming links, outbound links, etc)
  • stats_url - a link to view more details for this item on

The "goals" type will also have a few additional keys that only apply to this data type:
  • incompleted - If this goal has a funnel, this value will be how many visitors went through the funnel but did not complete the goal.
  • conversion - The conversion rate percentage (how many people completed this goal, relative to either how many people total went through this goals' funnel [if applicable], or the total number of visitors for the requested date/range).
  • revenue - The total revenue for this goal
  • cost - The total cost for this goal


Chronological data types

Each type has its own unique needs and hence their response structures are all different.

visitors-list returns a list of visitors to your website, in reverse chronological order.
  • time - the "raw" Unix time of the visit (for easy custom formatting)
  • time_pretty - the unixtime pre-formatted like so: Thu Nov 21 2024, 1:45a
  • time_total - the amount of time in seconds that this visitor was / has been on you site
  • ip_address - the visitor's IP address
  • session_id - the session_id for this visit
  • actions - the number of actions performed (page views, downloads, outbound links clicked)
  • total_visits - how many times this visitor has visited your site
  • first_visit - details of their first visit, stored in two sub-keys: time (unixtime of first visit), and session_id
  • web_browser - the visitor's web browser, e.g. "Firefox"
  • operating_system - the visitor's operating system, e.g. "Windows"
  • screen_resolution - the visitor's screen resolution, e.g. "1024x768"
  • javascript - does this user have javascript enabled? 1 (yes), or 0 (no)
  • language - the spoken language of the visitor
  • referrer_url - if the visitor followed a link to your site, this is where they came from
  • referrer_domain - the domain of the referrer, if applicable
  • referrer_search - the search term used to get to your site, if applicable
  • referrer_type - the type of referrer - search, advertising, social media, etc. Only present if there is a referrer for this visitor.
  • geolocation - the visitor's location in City, Country format (City, State, Country for US locations)
  • latitude - the visitor's latitude
  • longitude - the visitor's longitude
  • hostname - the visitor's hostname (top and second level domain name) (premium members only)
  • organization - the visitor's organization, e.g. Microsoft Corp (premium members only)
  • campaign - if the visitor arrived via a campaign, this will be the campaign name (Pro members only)
  • goals - if the visitor completed any goals or went through any goal funnels, this object will exist, with the following hierarchy. (Goals are a Pro-only feature).
    • goals_completed
      • goal [value = goal name]
      • ...
    • goals_incompleted
      • goal [value = goal name]
      • ...
    • revenue
    • cost
  • custom - if any custom data has been logged for this visitor (username, etc), this object will contain a group of sub-objects for each key/value pair.
  • stats_url - a link to view the details of the visitor session on


actions-list returns a list of actions that occured on your website, in reverse chronological order.
  • time - the "raw" Unix time of the visit (for easy custom formatting)
  • time_pretty - the unixtime pre-formatted like so: Thu Nov 21 2024, 1:45a
  • ip_address - the visitor's IP address
  • session_id - the session ID that this action belongs to
  • action_type - possible values are pageview, outbound, download, click (events), search (for internal searches), video_play, video_pause, video_seek, and video_end.
  • action_title - for page views, this is the HTML title of the page. For downloads and outbound links, this is the text of the link that the user clicked to initiate the action. If it's a graphical link, we grab the "alt" or "title" attribute if available. Otherwise we fall back on the URL of the image itself.
  • action_url - the URL of the page view, download, or outbound link
  • referrer_url - if this action was the result of an external link or search, this is where the action came from. (Only applicable to "pageview" action types)
  • referrer_domain - the domain of the referrer, if applicable
  • referrer_search - the search term used to get to your site, if applicable
  • custom - if any custom data has been logged for this action (username, etc), this object will contain a group of sub-objects for each key/value pair.
  • stats_url - a link to view the details of the visitor session on


searches-recent, searches-unique, links-recent, and links-unique return a list of the most recent or most recent unique searches and links that occured on your website.
  • time - the "raw" Unix time of the visit (for easy custom formatting)
  • time_pretty - the unixtime pre-formatted like so: Thu Nov 21 2024, 1:45a
  • item - the search query or link
  • stats_url - a link to your visitor list with the appropriate search or link filter applied to view more details on the people who arrived at your site via this item


uptime returns a list of uptime checks with overview information.
  • name - the name of the check to which the event belongs
  • endpoint - the endpoint of the check to which the event belongs
  • interval - the interval at which the check is performed
  • type - what type of check it is
  • is_down - whether the check is currently down
  • event_count - the number of downtime events that occurred
  • total_seconds_down - the total amount of downtime for the check, in seconds
  • uptime_percentage - the uptime percentage for the date range


uptime-list returns a list of uptime events that occured on the endpoints that you're monitoring, in reverse chronological order.
  • name - the name of the check to which the event belongs
  • endpoint - the endpoint of the check to which the event belongs
  • interval - the interval at which the check is performed
  • type - what type of check it is
  • down_at - when the check was identified as offline
  • up_at - when the check came back online
  • seconds_down - how long the check was down for