Help with Clicky

The Clicky API allows you to extract your web site'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, PHP, JavaScript (JSON), and CSV. XML and JSON are very commonly used within Web 2.0 style applications that make heavy use of "AJAX". PHP is returned as a serialized array of your results, possibly simplyifing implementation if your application is PHP based. CSV would typically only be desired for storage purposes, but is supported for users wishing for an automated download/backup method of their data.

Send requests to the following URL: http://api.getclicky.com/api/stats/3   (note: that page will be empty until you add in the required parameters!)

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 web site and is assigned when you first register your web site with us. Because you don't "login" to the API like you would to a normal web site, every request must be authenticated by your sitekey. Available from site preferences page.

type

The type of data you want. Items in red indicate a premium-only feature.
You can request more than one type at once, simply seperate with commas. For example, For example, type=searches,links,languages.

• Popular items

  Results are ordered from most popular (e.g. most occurrences) to least popular.
  • searches - full search queries
  • searches-keywords - searches, broken down by individual keyword
  • searches-engines - search engines
  • links - incoming links (full URL)
  • links-domains - incoming links (by domain name)
  • links-outbound - outbound links
  • pages - pages on your site
  • pages-entrance - entrance/landing pages
  • pages-exit - exit pages (the last page someone sees on your site before leaving)
  • downloads
  • clicks - Ajax and Flash interactions (more info)
  • goals
  • campaigns
  • countries
  • cities
  • languages
  • web-browsers
  • operating-systems
  • screen-resolutions
  • hostnames - visitor hostnames, e.g. microsoft.com
  • organizations - visitor organizations, e.g. Microsoft Corp
  • 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 - generically speaking, how visitors are arriving at your site (link, search, email, advertising, etc)
  • feedburner-clicks - feed items, ordered by number of clickthroughs
  • feedburner-views - feed items, ordered by number of views
  • tweets - if you have setup Twitter brand monitoring with Clicky, this will return each individual search along with how many hits it's had on the selected date/range.
  
  

• 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. Can be filtered by ip_address.
  • 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 Clicky 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 Clicky knows).
  
  

• Tallies

  • site-rank - the site's current ranking amongst all other sites registered on Clicky, ranked by the number of visitor actions from the last 7 days. This value is always the site's current ranking; specifying a date has no effect.
  • visitors - number of visitors
  • visitors-unique - number of unique visitors
  • actions - number of visitor actions (sum of page views, downloads, and outbound links)
  • 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
  • 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
  • visitors-online - how many visitors are currently active on your web site. This value is always the "live" value; specifying a date has no effect.
  • feedburner-subscribers - number of subscribers to your feed
  
  

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 will be 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: 10
Accepted values: Any number between 1 and 1000, or "all" for "no limit". "all" is actually limited to 100,000 results, because of memory limitations. This means for high traffic sites, visitors-list and actions-list will probably be incomplete if you are requesting more than a single date. It is recommended that high traffic sites only request a single day at a time for these two data types.

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. 2009-11-21
  • YYYY-MM-DD,YYYY-MM-DD - for a specific date range, e.g. 2009-10-01,2009-10-31
  
  
• 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 the least fun thing in the entire world. The dates shown below in the examples are being calculated live with the same code the API uses, using today's date, 2009-11-21. Note that "X" needs to be replaced by an actual number in your request.
  • today - returns today's date, 2009-11-21
  • yesterday - returns yesterday's date, 2009-11-20
  • X-days-ago - returns single date, X days ago. "3-days-ago" would return 2009-11-18
  • last-X-days - returns range of last X days, including today. "last-3-days" would return 2009-11-19,2009-11-21
  • previous-X-days - returns range of previous X days, before today. "previous-3-days" would return 2009-11-18,2009-11-20
  • YYYY-MM - returns range for entire month. "2007-07" would return 2007-07-01,2007-07-31
  • this-month - returns range for the entire current month. In this case, 2009-11-01,2009-11-30
  • last-month - returns range for the entire last month. In this case, 2009-10-01,2009-10-31
  • X-months-ago - returns range for an entire month, X months ago. "3-months-ago" would return 2009-08-01,2009-08-31
  • this-week - returns range for current week, Sunday - Saturday. In this case, 2009-11-15,2009-11-21
  • last-week - returns range for last week, Sunday - Saturday. In this case, 2009-11-08,2009-11-14
  • X-weeks-ago - returns range for for an entire Sunday - Saturday week, X weeks ago. "3-weeks-ago" would return 2009-10-25,2009-10-31

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.

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

json_callback, json_var

These parameters are available for JSON output requests. You may only use one of them for any given request. These are useful for use with web service requests in client-side JavaScript. Normally web service requests using the XMLHttpRequest object run afoul of browser security restrictions that prevent files from being loaded across domains. This restriction requires you to proxy your requests on the server side or use server rewrites to trick the browser into thinking the web service data is coming from the same site as your web content.

With one of these parameters, you can place Clicky API requests inside a <script> tag, and operate on the results with a function 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. No proxy or server trickery is required. (Thanks to Yahoo! for this well-written explanation).

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

Example json_callback:

http://api.getclicky.com/api/stats/3?site_id=32020&sitekey=2e05fe2778b6&type=searches&output=json&json_callback=my_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://api.getclicky.com/api/stats/3?...output=json&json_callback=my_callback">

Example json_var:

http://api.getclicky.com/api/stats/3?site_id=32020&sitekey=2e05fe2778b6&type=searches&output=json&json_var=my_var

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

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 web site 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 web site 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.

null_values

By default, result sets exclude all fields that have "empty" or "null" values, which saves considerable bandwidth and memory. 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.

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

ip_address, search, domain, link, browser, os, resolution, country, city, language, hostname, organization, source, custom

These filters are available for visitors-list, 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 web site itself, so you can try applying filters in that interface and then copy/paste the URL variables into your API requests.

Examples: browser=internet+explorer, domain=google.com, country=the+united+states

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., 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, title, href, action_type

These filters are available for actions-list, and 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 web site itself, so you can try applying filters in that interface and then copy/paste the URL variables into your API requests.

Valid action_types are pageview, download, outbound, and click

Examples: title=contact+us, href=%2Fcontact.php, session_id=123123, action_type=download

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.

• 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)
• clicky_url - a link to view more details for this item on Clicky

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 web site, in reverse chronological order.

• time - the "raw" Unix time of the visit (for easy custom formatting)
• time_pretty - the unixtime pre-formatted like so: Sat Nov 21 2009, 9:48pm
• 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)
• 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
• 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.
• clicky_url - a link to view the details of the visitor session on Clicky

actions-list returns a list of actions that occured on your web site, in reverse chronological order.

• time - the "raw" Unix time of the visit (for easy custom formatting)
• time_pretty - the unixtime pre-formatted like so: Sat Nov 21 2009, 9:48pm
• ip_address - the visitor's IP address
• session_id - the session ID that this action belongs to
• action_type - possible values are "pageview", "download", or "outbound".
• 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.
• clicky_url - a link to view the details of the visitor session on Clicky

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 web site.

• time - the "raw" Unix time of the visit (for easy custom formatting)
• time_pretty - the unixtime pre-formatted like so: Sat Nov 21 2009, 9:48pm
• item - the search query or link
• clicky_url - a link to your Clicky 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

Examples

Some example requests are shown below, and provide a good starting point for discovering what you can do with the API. The results are from our demo traffic data, and completely real. Note that the PHP output you see below is "unserialized", so that you can see how the array is structured. Simply remove the the "&unserialize" from the URL to see how it would actually be sent to your application. Run the returned string through unserialize() to copy it to an array within PHP.

Today's visitors, actions, average actions, average time, and bounce rate

XML   JSON   PHP  

The last 30 visitors today

XML   JSON   PHP  

The last 30 visitors today who live in the US and arrived via a search

XML   JSON   PHP  

Last weeks's top pages, links, and searches

XML   JSON   PHP  

Last weeks's top pages, links, and searches, by day

XML   JSON   PHP  

Yesterday's popular searches that do NOT have the word "Clicky" in them

XML   JSON   PHP  

Limitations

Free accounts are limited to the last 30 days of history, and 100 results per request.


Back to top