Help with Clicky

The Clicky API allows you to extract a wide range of data from your web site traffic to analyze, store, manipulate, or display within your own application. Nearly every piece of data that you see using our web site can also be accessed via the API.

The API accepts requests via standard HTTP GET, and can respond with XML, JSON (JavaScript), or PHP. 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.

Where do you send requests? Please visit your user homepage and click the new "info" link next to any of your sites. This will provide you with your site's base API URL, which already includes your site_id and sitekey. Simply slap on the last required parameter, "type", and you're gold.

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.

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 on Clicky. Because you don't "login" to the API like you would to a normal web site, every request must be authenticated by your sitekey. This helps ensure that only authorized users have access to your data.

type

The type of data you want. Each "group" below has a different response structure, as the needs are vastly different. The structures are detailed further down, along with some examples. Note that FeedBurner data is only available if you have it configured on Clicky. Also, FeedBurner does not provide "live" data. This means the latest available data for any FeedBurner responses is "yesterday".

• Visitors

• visitors-list - a list of your visitors along with all the juicy deets (location, IP, referrer, search, custom data, etc)



• Popular items

  • links - most popular incoming links (full URL)
  • links-domains - most popular incoming links, by domain name
  • links-outbound - most popular outbound links
  • pages - most popular pages
  • pages-entrance - most popular entrance pages
  • pages-exit - most popular exit pages
  • downloads - most popular downloads
  • searches - most popular searches
  • searches-keywords - most popular search keywords
  • searches-engines - most popular search engines
  • countries - most popular countries that your visitors are from
  • cities - most popular cities
  • languages - most popular languages
  • web-browsers - most popular web browsers
  • operating-systems - most popular operating systems
  • screen-resolutions - most popular screen resolutions
  • feedburner-clicks - most popular feed items, by number of clickthroughs (requires FeedBurner Pro account)
  • feedburner-views - most popular feed items, by number of views (requires FeedBurner Pro account)
  
  

• Daily values

  • 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. The returned result is its current ranking, the date parameter (below) has no effect on the result.
  • visitors - number of visitors
  • visitors-unique - number of unique visitors
  • actions - number of visitor actions (sum of page views, downloads, and outbound link clicks)
  • avg-time - average time on site per visitor
  • feedburner-subscribers - number of subscribers to your feed
  
  

Optional parameters

The following parameters are optional. For each one, the default value will be used if the parameter is not included in your request, or the value specificied is invalid.

output

The data format you would like to receive.
Default value: xml
Accepted values: xml, php, js

limit

The maximum number of results that will be returned.
Default value: 10
Accepted values: Any number between 1 and 500. For visitors-list, this can also be set to "all", which will return every visitor that meets your criteria. Be advised that the result set for "all" may be gigantic. Please only use it when necessary.

date

The date or date range you want to access. The maxmimum range is 31 days. If you give an invalid range (more than 31 days, end is before start, etc), it will instead just use today's date for your results. Excluding visitors-list, if you are requesting data from more than one date, the results returned are the total summed values for each item from that date range. This means that the results from visitors-unique, avg-time, and feedburner-subscribers may not be accurate or logical.

Default value: "Today"
Accepted values:

• YYYY-MM-DD for a single date
• YYYY-MM-DD,YYYY-MM-DD for a date range.

ip_address

This parameter is only available for the visitors-list type. If included within your request, the response set will only contain visits from that IP address within the specified date range. This could be very useful to integrate into your own web site to see if a visitor has visited your site before within the last X days (up to 31). How you would use that data is up to you, but there is great potential.

Default value: none
Accepted values: Any valid IP address (xxx.xxx.xxx.xxx)

Return values

visitors-list returns a list of visitors for the given date range and limit, and contains a wealth of information about each of them.

• unixtime - the "raw" Unix time of the visit (for custom formatting depending on your needs)
• date_pretty - the unixtime formatted like: Fri Jun 22 2007, 8:30pm
• ip_address - the visitor's IP address
• time_total - the amount of time in seconds that this visit lasted
• 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 - 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
• 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.
• url_clicky - a link to view the details of the session on Clicky

For the "popular" data types, the response will be a group of items with the following values:

• 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, if available (pages, incoming links, outbound links, etc)
• url_clicky - an internal Clicky URL for more information on the item, if available (searches, domains, ip addresses, etc)

For the "daily values" data types, as these just return one number, the response is simpler. For JS and PHP, just the number itself will be returned, e.g. the entire response will just be "350". For XML, the entire response would be <value>350</value>

• value - the item's value

Back to top