Church Analytics

About Church Analytics

Customizable Tracking

Video Analytics

Terms and Definitions

You Are Currently Viewing: Our Available API

The Church Analytics Analytics 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://stats.churchanalytics.com/api/stats/4

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

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 Church Analytics 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 Church Analytics knows).

Tallies

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 10,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 750 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. 2010-09-09
YYYY-MM-DD,YYYY-MM-DD - for a specific date range, e.g. 2010-08-01,2010-08-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, 2010-09-09.

Note that "X" needs to be replaced by an actual number in your request.

today - returns today's date, 2010-09-09
yesterday - returns yesterday's date, 2010-09-08
X-days-ago - returns single date, X days ago. "3-days-ago" would return 2010-09-06
last-X-days - returns range of last X days, including today. "last-3-days" would return 2010-09-07,2010-09-09
previous-X-days - returns range of previous X days, before today. "previous-3-days" would return 2010-09-06,2010-09-08
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, 2010-09-01,2010-09-30
last-month - returns range for the entire last month. In this case, 2010-08-01,2010-08-31
X-months-ago - returns range for an entire month, X months ago. "3-months-ago" would return 2010-06-01,2010-06-30
this-week - returns range for current week, Sunday - Saturday. In this case, 2010-09-05,2010-09-11
last-week - returns range for last week, Sunday - Saturday. In this case, 2010-08-29,2010-09-04
X-weeks-ago - returns range for for an entire Sunday - Saturday week, X weeks ago. "3-weeks-ago" would return 2010-08-15,2010-08-21

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

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

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

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!

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 will get all visitor sessions from the last hour. Note that the default limit of '10' will still apply unless you specify the limit, 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

Please note: calculating segmentation data is an intensive process. For this reason, the maximum date range you can specify is 90 days. Even so, we don't recommend requesting more than 7 days at a time if your site has a significant amount of traffic (more than 1,000 visitors a day), as the request may take a long time.

ip_address, href, landing, exit, num_actions, search, domain, link, browser, os, resolution, country, city, language, hostname, org, source, shorturl, custom

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

Examples:

type=visitors-list&browser=firefox+3.5
type=visitors-list&domain=google.com
type=visitors-list&country=the+united+states
ip_address can accept both IP ranges, and multiple IPs or ranges, in a single values. 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, 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=123
action_type=download

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.

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 Church Analytics 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.

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.churchanalytics.com/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.churchanalytics.com/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.

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)
canalytics_url - a link to view more details for this item on Church Analytics

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: Thu Sep 9 2010, 6:45pm
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.
canalytics_url - a link to view the details of the visitor session on Church Analytics

actions-list

time - the "raw" Unix time of the visit (for easy custom formatting)
time_pretty - the unixtime pre-formatted like so: Thu Sep 9 2010, 6:45pm
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.
canalytics_url - a link to view the details of the visitor session on Church Analytics

searches-recent

searches-unique

links-recent

links-unique

time - the "raw" Unix time of the visit (for easy custom formatting)
time_pretty - the unixtime pre-formatted like so: Thu Sep 9 2010, 6:45pm
item - the search query or link
canalytics_url - a link to your Church Analytics 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

Jump Back to the Top!