StatCounter API Documentation - Version 3

  • 1. Introduction #

    The StatCounter API accepts requests via the HTTP GET method. Results are returned in either JSON (default) or XML format. To perform the required task, simply send the necessary HTTP request, as described in this specification.

    All API calls return an error response in the case of a failure. The structure of an error response (JSON format) is as follows:

    { "@attributes": { "status": "fail", }, "error": [{ "code": "CODE", "description": "ERROR_DESCRIPTION" }] }
  • 2. API Login Credentials #

    To use the StatCounter API, you will require a StatCounter account with a paid upgrade. If you do not already have an account, you must sign up for an account. Paid upgrades are available here.

    Once you have a StatCounter account with a paid upgrade, you will need to set your API password. You may then construct an API call.

    If you do not have an upgraded account, you may test the StatCounter API using our Demo API User details:

    Username: demo_user
    API Password: statcounter
    Demo Project ID: 2292634

  • 3. Constructing an API Call #

    Each StatCounter API call contains settings that configure the task or function that you wish to execute. To perform the required task, you must configure the correct settings.

    As an example, we will look in detail at how to retrieve statistics for Recent Visitors.

    All API calls are sent via HTTP to the same URL, so every API call must begin with:

    http://api.statcounter.com/

    The correct function must then be added to the call (e.g. stats/, add_project/, update_project/, etc.). In this example, we will add "stats/", as stated in the specification for Recent Visitors:

    http://api.statcounter.com/stats/

    The next step is to add the required settings, beginning with the "?" symbol, with each setting separated by the "&" symbol.

    The "Version Number" (vn) setting determines the particular API version number that you wish to use. The current API version is version 3. To request the most recent API version number, we use "vn=3":

    http://api.statcounter.com/stats/?vn=3

    Again, using Recent Visitors as an example, we will look at the "Stats" (s) setting. "Stats" determines the set of statistics which you wish to return e.g. summary, visitor, popular. To request the "Recent Visitor Activity" statistics, we use "s=visitor":

    http://api.statcounter.com/stats/?vn=3&s=visitor

    The "Format" (f) setting determines the format in which you wish to return data from the server. The available options are "JSON" and "XML". The default setting is "JSON". To request "XML" format, use "f=xml":

    http://api.statcounter.com/stats/?vn=3&s=visitor&f=xml

    The "Project ID" (pi) is always required when retrieving data for a particular project. To request project ID "1234567", for example, use "pi=1234567":

    http://api.statcounter.com/stats/?vn=3&s=visitor&f=xml&pi=1234567

    You can also set the number of results (n) that you wish to return. This setting is optional, and will return 20 results by default if not set. To request 10 returned results, use "n=10":

    http://api.statcounter.com/stats/?vn=3&s=visitor&f=xml&pi=1234567&n=10

    For security and authentication reasons, each API call must be accompanied by the time of execution (t) of the call, in Unix timestamp format. When a scripting language such as PHP, the timestamp can easily be generated with the "time()" function e.g. timestamp "1329142078". To include this timestamp in your API call, we use "t=1329142078":

    http://api.statcounter.com/stats/?vn=3&s=visitor&f=xml&pi=1234567&n=10&t=1329142078

    You must also include your StatCounter username in the API call e.g. username "myusername". To include your username in the API call, we use "u=myusername":

    http://api.statcounter.com/stats/?vn=3&s=visitor&f=xml&pi=1234567&n=10&t=1329142078&u=myusername

    The final step in creating your API call for Recent Visitors is to add the SHA-1 (sha1) authentication data. The SHA-1 proves your identity within the StatCounter system. The SHA-1 value that you must use is found by calculating the SHA-1 value of the existing URL query string to-date, with your API password appended.

    In our example, the URL query string to-date is:

    ?vn=3&s=visitor&f=xml&pi=1234567&n=10&t=1329142078&u=myusername

    If we take our example password to be "mypassword", and append it to the URL query string, we get the following string:

    ?vn=3&s=visitor&f=xml&pi=1234567&n=10&t=1329142078&u=myusernamemypassword

    Using PHP, the SHA-1 of this string can easily be found using the sha1() function:

    sha1("?vn=3&s=visitor&f=xml&pi=1234567&n=10&t=1329142078&u=myusernamemypassword");

    The following SHA-1 string is returned:

    e0fd149f1999f81ce474070a01c7b14c01e4044f

    The final step in creating our API call is to go back to our URL string to-date, and add the SHA-1 value:

    http://api.statcounter.com/stats/?vn=3&s=visitor&f=xml&pi=1234567&n=10&t=1329142078&u=myusername&sha1=e0fd149f1999f81ce474070a01c7b14c01e4044f

    When this URL is passed to the StatCounter server via HTTP, the data will be returned, in this case, in XML format. The URL will only work for 15 minutes, after which time, it will need to be re-constructed.

  • 4. Retrieve Stats #

  • 4.1 Date Range Selection #

  • The StatCounter API allows for the retrieval of each statistic type (Popular Pages, Recent Visitors, etc.) within a set time period. To select your required period, just add the necessary details to your API call, as detailed for each appropriate time period below. If no time period is specified, the API will search all available records.

    Hourly:

    Daily:

    Weekly:

    &g=weekly&sy=START_YEAR&sw=START_WEEK&ey=END_YEAR&ew=END_WEEK

    Monthly:

    &g=monthly&sm=START_MONTH&sy=START_YEAR&em=END_MONTH&ey=END_YEAR

    Quarterly:

    &g=quarterly&sy=START_YEAR&sq=START_QUARTER&ey=END_YEAR&eq=END_QUARTER

    Yearly:

    &g=yearly&sy=START_YEAR&ey=END_YEAR

    With the exception of Summary Stats, the returned response structure for each statistic type is unchanged, regardless as to whether a time period is specified or not. Specific examples are given for Summary Stats (below) due to different response structures.

  • 4.2 Multiple Project Selection #

  • The StatCounter API allows for the retrieval of stats data for multiple projects in one call. This may be faster than making a seperate call to the stats function for each project of interest. To request data for multiple projects, just add multiple "Project ID" (pi) parameters to your stats call:

    http://api.statcounter.com/stats/?vn=3&s=visitor&f=xml&pi=123&pi=456pi=789

    The returned response structure is different when multiple "Project ID" (pi) parameters are used. The response will consist of an array of objects composed of a id attribute, representing the Project ID, and the normal sc_data attribute with the associated project's stats data:

    { "@attributes": { "status": "ok", }, "project": [{ "id": "123", "sc_data": [{ ... }, { "id": "456", "sc_data": [{ ... }, { "id": "789", "sc_data": [{ ... }] }] }
  • 4.3 Summary Stats #

  • 4.3.1 Summary Stats - Hourly #

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "date": "DATE", (YYYY-MM-DD) "hour": "HOUR", (HH) "page_views": "PAGE_VIEWS", "unique_visits": "UNIQUE_VISITS", "returning_visits": "RETURNING_VISITS", "first_time_visits": "FIRST_TIME_VISITS" }] }

    Here is a sample return containing data from a number of days:

    { "@attributes":{ "status":"ok" }, "sc_data": [{ "date":"2012-01-10", "hour":"01", "page_views":"3369", "unique_visits":"938", "returning_visits":"289" }, { "date":"2012-01-11", "hour":"02", "page_views":"2409", "unique_visits":"840", "returning_visits":"258" }, { "date":"2012-01-12", "hour":"03", "page_views":"2712", "unique_visits":"1068", "returning_visits":"277" }] }
  • 4.3.2 Summary Stats - Daily #

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "date": "DATE", (YYYY-MM-DD) "page_views": "PAGE_VIEWS", "unique_visits": "UNIQUE_VISITS", "returning_visits": "RETURNING_VISITS", "first_time_visits": "FIRST_TIME_VISITS" }] }

    Here is a sample return containing data from a number of days:

    { "@attributes":{ "status":"ok" }, "sc_data": [{ "date":"2012-01-10", "page_views":"3369", "unique_visits":"938", "returning_visits":"289" }, { "date":"2012-01-11", "page_views":"2409", "unique_visits":"840", "returning_visits":"258" }, { "date":"2012-01-12", "page_views":"2712", "unique_visits":"1068", "returning_visits":"277" }] }
  • 4.3.3 Summary Stats - Weekly #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=summary&g=GRANULARITY&sy=START_YEAR&sw=START_WEEK&ey=END_YEAR&ew=END_WEEK&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "year": "YEAR", "week": "WEEK", "page_views": "PAGE_VIEWS", "unique_visits": "UNIQUE_VISITS", "returning_visits": "RETURNING_VISITS", "first_time_visits": "FIRST_TIME_VISITS" }] }

    Here is a sample return containing data from a number of days:

    { "@attributes":{ "status":"ok" }, "sc_data": [{ "year":"2012", "week":"1", "page_views":"3369", "unique_visits":"938", "returning_visits":"289" }, { "year":"2012", "week":"2", "page_views":"2409", "unique_visits":"840", "returning_visits":"258" }] }
  • 4.3.4 Summary Stats - Monthly #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=summary&g=GRANULARITY&sm=START_MONTH&sy=START_YEAR&em=END_MONTH&ey=END_YEAR&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "year": "YEAR", "month": "MONTH", (MM) "page_views": "PAGE_VIEWS", "unique_visits": "UNIQUE_VISITS", "returning_visits": "RETURNING_VISITS", "first_time_visits": "FIRST_TIME_VISITS" }] }

    Here is a sample return containing data from a number of days:

    { "@attributes":{ "status":"ok" }, "sc_data": [{ "year":"2012", "month":"1", "page_views":"3369", "unique_visits":"938", "returning_visits":"289" }, { "year":"2012", "month":"2", "page_views":"2409", "unique_visits":"840", "returning_visits":"258" }, { "year":"2012", "month":"3", "page_views":"2712", "unique_visits":"1068", "returning_visits":"277" }] }
  • 4.3.5 Summary Stats - Quarterly #

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "year": "YEAR", "quarter": "QUARTER", "page_views": "PAGE_VIEWS", "unique_visits": "UNIQUE_VISITS", "returning_visits": "RETURNING_VISITS", "first_time_visits": "FIRST_TIME_VISITS" }] }

    Here is a sample return containing data from a number of days:

    { "@attributes":{ "status":"ok" }, "sc_data": [{ "year":"2012", "quarter": "1", "page_views":"3369", "unique_visits":"938", "returning_visits":"289" }, { "year":"2012", "quarter": "2", "unique_visits":"840", "returning_visits":"258" }] }
  • 4.3.6 Summary Stats - Yearly #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=summary&g=GRANULARITY&sy=START_YEAR&ey=END_YEAR&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "year": "YEAR", "page_views": "PAGE_VIEWS", "unique_visits": "UNIQUE_VISITS", "returning_visits": "RETURNING_VISITS", "first_time_visits": "FIRST_TIME_VISITS" }] }

    Here is a sample return containing data from a number of days:

    { "@attributes":{ "status":"ok" }, "sc_data": [{ "year":"2012", "page_views":"3369", "unique_visits":"938", "returning_visits":"289" }] }
  • 4.4 Recent Visitors #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=visitor&pi=PROJECT_ID&n=NUMBER_OF_RESULTS&t=TIME_OF_EXECUTION&f=FORMAT&u=USERNAME&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "log_visits": "The number of visits from this visitor available in the log.", "entries_in_visit": "The number of page views in the most recent visit from a visitor.", "entry_t": "ENTRY_TIME", "entry_url": "ENTRY_PAGE_URL", "entry_title": "ENTRY_PAGE_TITLE", "se_keywords": " SEARCH_ENGINE_KEYWORDS", "link": "REFERRAL_URL", "country_name": "COUNTRY_NAME", "state": "STATE", "res": "RESOLUTION", "exit_t": "EXIT_TIME", "exit_url": "EXIT_PAGE_URL", "exit_title": "EXIT PAGE TITLE", "returning_count": "The number of returning visits from this visitor based on the cookie data (not limited to log size).", "browser_name": "BROWSER_NAME", "browser_version": "BROWSER_VERSION", "os": "OS", "width": "WIDTH", "height": "HEIGHT", "javascript": "JAVASCRIPT", "country": "COUNTRY", "city": "CITY", "isp": "ISP", "ip_address": "IP_ADDRESS", "latitude": "LATITUDE", "longitude": "LONGITUDE", "num_entry": "The total number of page views for this visitor available in the log.", "visit_length": "VISIT_LENGTH" }] }
  • http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=popular&pi=PROJECT_ID&n=NUMBER_OF_RESULTS&c=CHOP_URL&ct=COUNT_TYPE&t=TIME_OF_EXECUTION&f=FORMAT&u=USERNAME&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_views": "PAGE_VIEWS", "title": "TITLE", "url": "URL" }] }
  • 4.6 Entry Pages #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=entry&pi=PROJECT_ID&n=NUMBER_OF_RESULTS&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_views": "PAGE_VIEWS", "page_title": "PAGE_TITLE", "page_url": "PAGE_URL" }] }
  • 4.7 Exit Pages #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=exit&pi=PROJECT_ID&n=NUMBER_OF_RESULTS&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_views": "PAGE_VIEWS", "title": "PAGE_TITLE", "page_url": "PAGE_URL" }] }
  • 4.8 Came From #

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_views": "PAGE_VIEWS", "referring_url": "REFERRING_URL" }] }
  • 4.9 Recent Came From #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=recent_camefrom&pi=PROJECT_ID&n=NUMBER_OF_RESULTS&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&ese=EXCLUDE_SEARCH_ENGINES&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "referring_url": "REFERRING_URL", "time": "TIME", "entry_page": "ENTRY_PAGE", "ip_address": "IP_ADDRESS", "se_keywords": "SE_KEYWORDS" }] }
  • 4.10 Recent Keyword Activity #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=keyword-activity&pi=PROJECT_ID&eek=EXCLUDE_ENCRYPTED_KEYWORDS&n=NUMBER_OF_RESULTS&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&e=EXTERNAL&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "search_engine_name": "SEARCH_ENGINE_NAME", "search_engine_host": "SEARCH_ENGINE_HOST", "keyword": "KEYWORD", "time": "TIME", "page_url": "PAGE_URL", "page_title": "PAGE_TITLE", "referring_url": "REFERRING_URL", "ip_address": "IP_ADDRESS" }] }
  • 4.11 Browsers #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=browsers&de=DEVICE&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_views": "PAGE_VIEWS", "browser_name": "BROWSER_NAME", "browser_version": "BROWSER_VERSION", "percentage": "PERCENTAGE" }] }
  • 4.12 Operating Systems #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=os&de=DEVICE&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_views": "PAGE_VIEWS", "os_name": "OS_NAME", "percentage": "PERCENTAGE" }] }
  • 4.13 Search Engines #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=search_engine&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_views": "PAGE_VIEWS", "search_engine_name": "SEARCH_ENGINE_NAME", "search_engine_provider": "SEARCH_ENGINE_PROVIDER", "percentage": "PERCENTAGE" }] }
  • 4.14 Country #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=country&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_views": "PAGE_VIEWS", "country_name": "COUNTRY_NAME", "percentage": "PERCENTAGE" }] }
  • 4.15 Recent Pageload Activity #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=pageload&de=DEVICE&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "page_url": "PAGE_URL", "time": "TIME", "referring_url": "REFERRING_URL", "page_title": "PAGE_TITLE", "browser_name": "BROWSER_NAME", "browser_version": "BROWSER_VERSION", "os_name": "OS_NAME", "device_vendor": "DEVICE_VENDOR", "device_model": "DEVICE_MODEL", "se_keywords": "SEARCH_ENGINE_KEYWORDS", "resolution_width": "RESOLUTION_WIDTH", "resolution_height": "RESOLUTION_HEIGHT", "isp": "ISP", "city": "CITY", "state": "STATE", "country": "COUNTRY", "ip_address": "IP_ADDRESS" }] }
  • http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=exit-links&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "hit": "HIT", "link": "EXIT_LINK" }] }
  • http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=exit-link-activity&de=DEVICE&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "link": "EXIT_LINK", "time": "TIME", "page_url": "EXIT_PAGE_URL", "page_title": "EXIT_PAGE_TITLE", "ip_address": "IP_ADDRESS" }] }
  • 4.18 Downloads #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=downloads&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "hit": "HIT", "link": "DOWNLOAD_LINK" }] }
  • http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=download-link-activity&de=DEVICE&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "link": "DOWNLOAD_LINK", "time": "TIME", "page_url": "DOWNLOAD_PAGE_URL", "page_title": "DOWNLOAD_PAGE_TITLE", "ip_address": "IP_ADDRESS", "extension": "EXTENSION" }] }
  • 4.20 Visit Length #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=visit_length&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "Lessthan5secs": "STRING", "From5secsto30secs": "STRING", "From30secsto5mins": "STRING", "From5minsto20mins": "STRING", "From20minstoanhour": "STRING", "Longerthananhour": "STRING" }] }
  • 4.21 Returning Visits #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=returning_visits&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "ReturningVisitsFirstTimeVisitors": "STRING", "ReturningVisits1to5": "STRING", "ReturningVisits6to10": "STRING", "ReturningVisits10OrMore": "STRING" }] }
  • 4.22 Keyword Analysis #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=keyword_analysis&pi=PROJECT_ID&ck=COMBINE_KEYWORDS&eek=EXCLUDE_ENCRYPTED_KEYWORDS&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Optional: Date Range Selection

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "keyword_count": "KEYWORD_COUNT", "keyword": "KEYWORD", "percentage": "PERCENTAGE", "search_engine_name": "SEARCH_ENGINE_NAME", "search_engine_host": "SEARCH_ENGINE_HOST" }] }
  • 4.23 Lookup Visitor Navigation Path #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=lookup_visitor_navigation&ip=IP_ADDRESS&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "url": "URL", "type": "TYPE", "time": "TIME" }] }
  • 4.24 Lookup Visitor Info #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=lookup_visitor_info&ip=IP_ADDRESS&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "resolution": "RESOLUTION", "country_name": "COUNTRY_NAME", "city": "CITY", "state": "STATE", "isp": "ISP", "browser_name": "BROWSER_NAME", "os": "OS", "host": "HOST", "latitude": "LATITUDE", "longitude": "LONGITUDE", "javascript": "JAVASCRIPT", "visit_length": "VISIT_LENGTH", "returning_visits": "RETURNING_VISITS" }] }
  • 4.25 Mobile Devices #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=mobile_device&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "hit": "HIT", "vendor": "VENDOR", "device": "DEVICE", "percentage": "PERCENTAGE", }] }
  • 4.26 Platform #

    http://api.statcounter.com/stats/?vn=VERSION_NUMBER&s=platform&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "desktop": "DESKTOP", "mobile": "MOBILE", "tablet": "TABLET", "console": "CONSOLE" }] }
  • Query String Fields

    Each API call is made with a URL containing a detailed query string. The fields used by the API are detailed below.

    vn – Version Number
    The version number of the StatCounter API that you are calling. This document describes the StatCounter API for Version 3 so the value '3' should always be passed.
    Example: vn=3

    f – Format
    The required format of the returned data. The available options are 'json' and 'xml'. JSON is the default format.
    Example: f=xml

    s – Stats
    The stats that you wish to call. The available options are:
    - summary (Summary Stats)
    - visitor (Recent Visitor Activity)
    - popular (Popular Pages)
    - entry (Entry Pages)
    - exit (Exit Pages)
    - camefrom (Recent Came From)
    Example: s=popular

    pi – Project ID
    The project ID of your StatCounter project.
    Example: pi=7407742

    u – Username
    Your statCounter username.
    Example: u=myusername

    wt – Website Title
    The name that will be given to the new StatCounter project e.g. 'My Website'. The title must be encoded for use in the URL.
    Example: wt=My%20Website

    wu – Website URL
    The URL of the website e.g. 'http://www.mywebsite.com/'. The URL must be encoded for use in the URL.
    Example: wu=http%3A%2F%2Fwww.mywebsite.com

    ls – Log Size
    The desired log size for the project.
    Example: ls=5000

    t – Time of Execution
    The time of execution of the request, in Unix timestamp format.
    Example: t=1321438882

    tz – Time Zone
    The time zone to be used for the project stats e.g. 'America/New_York'. See Time Zone Options in the Appendix for the complete list. The default is America/New_York. The Time Zone must be encoded for use in the URL.
    Example: tz=America%2FNew_York

    ps – Public Stats
    Set the level of public access to stats in a project. The default is that all stats are publicly available. The available options are:
    0: All public stats are disabled 1: All stats are public 2: Only 'Summary Stats' are public Example: ps=2

    n – Number of Results
    The number of results to return.
    Example: n=10

    c – Chop URL
    Chop the query string from the returned URL. Many URLs contain data variables in a query string that is used to set details on the web page. Chopping the query string can make the returned URL list easier to read and less cluttered. The available options are '0' and '1'. The default is '1' (chop URL).
    Example: c=1

    ct – Count Type
    The type of counts used by a stat. A stat can be counted by page views or visitors. The available api options are 'page_view' and 'visitor'. The default is 'page_view'.
    Example: ct=page_view

    g – Granularity
    The time interval of returned stats, used with a 'Summary Stats' query. Default value is 'weekly'. The available options are:
    - hourly
    - daily
    - weekly
    - monthly
    - quarterly
    - yearly
    Example: g=weekly

    sh – Start Hour
    The start hour for a time period in a 'Summary Stats' query. Default value is '0'.
    Example: sh=10

    sd – Start Day
    The start day for a time period in a 'Summary Stats' query. Default value is '1'.
    Example: sd=26

    sm – Start Month
    The start month for a time period in a 'Summary Stats' query. Default value is '1'.
    Example: sm=8

    sy – Start Year
    The start year for a time period in a 'Summary Stats' query. Default value is '2014'.
    Example: sy=2011

    sw – Start Week
    The start week for a time period in a 'Summary Stats' query. Only required if granularity is 'weekly'. Default value is '1'.
    Example: sw=2

    sq – Start Quarter
    The start quarter for a time period in a 'Summary Stats' query. Only required if granularity is 'quarterly'. Default value is '1'.
    Example: sq=1

    eh – End Hour
    The end hour for a time period in a 'Summary Stats' query. Default value is '23'.
    Example: eh=22

    ed – End Day
    The end day for a time period in a 'Summary Stats' query. Default value is '28'.
    Example: ed=30

    em – End Month
    The end month for a time period in a 'Summary Stats' query. Default value is '12'.
    Example: em=11

    ey – End Year
    The end year for a time period in a 'Summary Stats' query. Default value is '2014'.
    Example: ey=2012

    ew – End Week
    The end week for a time period in a 'Summary Stats' query. Only required if granularity is 'weekly'. Default value is '2'.
    Example: ew=34

    eq – End Quarter
    The end quarter for a time period in a 'Summary Stats' query. Only required if granularity is 'quarterly'. Default value is '4'.
    Example: eq=4

    e – Exclude External
    Choose to exclude external results to your site. Available options are '0' or '1'. Default value is '1' (exclude external).
    Example: e=1

    ese – Exclude Search Engines
    Choose to exclude search engine driven results to your site. Available options are '0' or '1'. Default value is '0' (include search engines).
    Example: ese=1

    eek – Exclude Encrypted Keywords
    Choose to exclude encrypted keyword results. Available options are '0' or '1'. Default value is '0' (include encrypted keyword results).
    Example: eek=1

    ck – Combine Keywords
    Choose to combine keyword results based on one of three possible criteria. Available options are 'search_engine_host' or 'search_engine_name' or 'together'. Default value is 'search_engine_host'.
    Example: ck=together

    gbd – Group By Domain
    Choose to group results by referring domain, in the 'Came From' stats query. Available options are '0' or '1'. Default value is '0' (do not group by domain).
    Example: gbd=1

    de – Device
    Choose the device type. Default value is 'All'. The available options are:
    - all
    - desktop
    - mobile
    Example: de=mobile

    ip – I.P. Address
    The I.P. address of a visitor you want to look up, in the stat lookup_visitor.
    Example: ip=192.168.1.1

    sha1 – SHA-1 Proof
    The SHA-1 proof is used to verify your identity within the StatCounter system. It is created from the SHA-1 value of the existing URL query string to-date, with your API password appended. e.g. sha1 (query string + api password)

    • Query string is the full URL query string, beginning with and including '?'.
    • The API password is set by you (see API Login Credentials for more details).
    Example: sha1=e0fd149f1999f81ce474070a01c7b14c01e4044f

  • 5. Create a New Project #

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok", }, "sc_data": [{ "project_id": "PROJECT_ID", "security_code": "SECURITY_CODE" }] }

    Once you receive a successful response, it is important to save the PROJECT_ID and the SECURITY_CODE into a database for that website, as these values will need to be retrieved each time the website is loaded.

  • 6. Update Project Settings #

    http://api.statcounter.com/update_project/?vn=VERSION_NUMBER&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&ps=PUBLIC_STATS&f=FORMAT&u=USERNAME&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status": "ok" } }
  • 7. Increase Project Log Size #

    This call allows you to increase the log size of any of your projects. The log size must be greater than 500, and you cannot use this call to decrease the log size.

    http://api.statcounter.com/update_logsize/?vn=VERSION_NUMBER&pi=PROJECT_ID&ls=LOG_SIZE&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "message": "The adjust log request has been received for project ID PROJECT_ID and will be processed in the next 5 minutes" } }
  • 8. Retrieve Account Log Sizes #

    This call will return log details for each project associated with your account.

    http://api.statcounter.com/account_logsizes/?vn=VERSION_NUMBER&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status":"ok" }, "sc_data": { "project_id":"PROJECT_ID", "project_name":"PROJECT_NAME", "log_size":"LOG_SIZE", "log_usage":"LOG_USAGE", "log_size_days_estimated":"LOG_SIZE_DAYS_ESTIMATE", "log_size_days_usage":"LOG_SIZE_DAYS_USAGE" } }
  • 9. Retrieve User Details #

    This call will return details of the user making the call.

    http://api.statcounter.com/user_details/?vn=VERSION_NUMBER&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status":"ok" }, "sc_data":[{ "name":"FULL_NAME", "email":"EMAIL_ADDRESS", "log_quota":"LOG_QUOTA", "date_format":"DATE_FORMAT", "time_format":"TIME_FORMAT" }] }

    Note:

    date_format key:

    1. DD MONTH YYYY
    2. MONTH DD YYYY
    3. YYYY.MM.DD
    4. DDth MONTH YYYY
    5. MONTH DDth YYYY

    time_format key:

    1. HH:MM:SS
    2. HH:MM:SS AM/PM
    3. HH:MM:SS
    4. HH:MM:SS AM/PM
  • 10. Integrate StatCounter Stats using an iframe #

    To view the public website stats, the user needs to be sent to the following website URL:

    http://statcounter.com/pPROJECT_ID?guest=1

    project_id
    The project ID returned by StatCounter via the API.
    Example: 3104569

    The user can view their website stats inside any control panel with the following iframe integration:

    <HTML> <HEAD> <TITLE>User Admin Panel</TITLE> </HEAD> <BODY> <p>Your Standard Control Panel HTML here</p> <iframe src = "http://statcounter.com/pPROJECT_ID?guest=1" width="100%" height="900"> <p>Your browser does not support iframes.</p> </iframe> </BODY> </HTML>
  • 11. Retrieve User Project Details #

    This call will return details of each project for which the given user has sufficient permissions.

    http://api.statcounter.com/user_projects/?vn=VERSION_NUMBER&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status":"ok" }, "sc_data":[{ "project_id":"PROJECT_ID", "project_name":"PROJECT_NAME", "url":"URL", "project_group_id":"PROJECT_GROUP_ID", "project_group_name":"PROJECT_GROUP_NAME", "hidden_group":"HIDDEN_GROUP" }] }
  • 11. Select Project Details #

    This call will return details of a project specified by the project id (pi) parameter

    http://api.statcounter.com/select_project/?vn=VERSION_NUMBER&pi=PROJECT_ID&t=TIME_OF_EXECUTION&u=USERNAME&f=FORMAT&sha1=SHA-1_TO_PROVE_IDENTITY

    Successful response structure (JSON format):

    { "@attributes": { "status":"ok" }, "sc_data":[{ "project_name":"PROJECT_NAME", "log_size": "LOG_SIZE", "timezone": "TIME_ZONE", "url":"URL", "log_oldest_entry":"LOG_OLDEST_ENTRY", "log_latest_entry":"LOG_LATEST_ENTRY" }] }
Last Update: 27th June 2014