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/2   (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.

• Popular items

  Results are ordered from most popular (e.g. most occurrences) to least popular.
  • searches - full search queries
  • searches-keywords - search keywords
  • 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 pages
  • pages-exit - exit pages
  • downloads - file downloads (pictures, zip files, etc)
  • clicks - Ajax and Flash interactions (more info)
  • countries - countries that your visitors are from
  • cities - cities
  • languages - languages
  • web-browsers - web browsers
  • operating-systems - operating systems
  • screen-resolutions - screen resolutions
  • hostnames - visitor hostnames
  • organizations - visitor organizations
  • 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
  
  

• 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, js, csv

limit

The maximum number of results that will be returned.

Default value: 10
Accepted values: Any number between 1 and 1000, or "all" for "no limit". "all" is actually limited to 200,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 31 days. If you give an invalid date or date range (more than 31 days, 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. Note that most "tally" data types only give meaningful results when requested for a single date.

Default value: today
Accepted values:

• Specific dates
  • YYYY-MM-DD - for a specific date
  • YYYY-MM-DD,YYYY-MM-DD - for a specific date range
  
  
• Relative dates
  These expressions provide you with an easy way to get dates relative to "today", without having to do date math internally. (Unless you find date math particularly enjoyable, in which case we encourage you to indulge). 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

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 absolutely necessary. Why?

Say you request your last 500 visitors for today in XML format, and only 50 of those visitors came to you from an external site or seach engine. For the other 450 visitors, we would be sending you the following data 450 times:

<referer_url></referer_url>
<referer_domain></referer_domain>
<referer_search></referer_search>

That's about 100 bytes of data, x 450 visitors is 45 KB of empty data per request we're sending to you that you don't need. Say you request it once per hour, every day. That's over 1 MB per day, or 30 MB per month, that is being wasted. Say there 1,000 other people doing the same thing. That's 30 GB per month. Bandwidth is cheap but it's not free!

This aside, your code should already be testing if a value is valid before using it. A common test in PHP is to run a value through empty() before doing anything with it, which will return false both if the value is empty/null, or if the value is not even set. By doing this, having some values not returned to your code should cause no problems. Important note: empty() returns true for a value of "0" which is typically undesirable.

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).

ip_address, search, domain, link, browser, os, resolution, country, city, language, hostname, organization, 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

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 value.

• 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

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, 8:37pm
• 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
• referer_url - if the visitor followed a link to your site, this is where they came from
• referer_domain - the domain of the referrer, if applicable
• referer_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)
• 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, 8:37pm
• 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
• referer_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)
• referer_domain - the domain of the referrer, if applicable
• referer_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, 8:37pm
• 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.

The last 30 visitors today

XML   JS   PHP  

The last 30 visitors today who live in the United States and arrived via google.com

XML   JS   PHP  

The most active visitors from the last 3 days

XML   JS   PHP  

Top 50 searches from the last 10 days

XML   JS   PHP  

The 100 newest unique incoming links from the last 7 days

XML   JS   PHP  

Notes etc.

Limitations

All users have access to the API, but full functionality is reserved for our "Pro" users only. (Pro is our upper-tier premium package, you can upgrade here). Non-Pro users are limited to "today" and "yesterday", and a maximum of 100 results per request.




Back to top