Documentation

Overview

The Compete API delivers accurate, reliable, and flexible digital performance data that empowers companies to build new products and drive their businesses forward. Our clients have used the Compete API to enhance their current products, make new products and lines of business possible, and build internal reporting functionality to make more informed business decisions - just to name a few.

Premium access to the Compete API is available through an annual subscription tailored to your data-point allotment needs. For more information on plans and pricing, fill out the form on our contact page or call 888-274-3282 to speak with a representative.

Getting Started

All requests are submitted via https and have this basic format:

https://apps.compete.com/sites/DOMAIN/trended/METRIC/?apikey=APIKEY

DOMAIN (Required)

The name of the domain or subdomain you are requesting. Including "http://" or "https://" with the domain will return an INVALID response. (e.g. facebook.com)

METRIC (Required)

The code of the metric you are requesting (eg. Unique Visitors, Visits, Rank)

API KEY (Required)

Your API key (provided when you sign up and register an app)

This example request would return a list of the Unique Visitors to facebook.com for the last year:

Example Request

https://apps.compete.com/sites/facebook.com/trended/uv/?apikey=APIKEY

Returned Data

{
    "status": "OK",
    "data": {
        "trends": {
            "uv": [
                {"date": "201403", "value": 90714948},
                {"date": "201404", "value": 98292793},
                {"date": "201405", "value": 103509116},
                ...
            ]
        },
        "trends_low_sample": false,
        "query_cost": 13,
        "trends_frequency": "monthly"
    }
}

Metric Codes

Monthly Metrics

The default cost for a monthly metric is 13 data points. You can access 25 months of historical data from current month using the DATE parameter.

Metric Code Description
rank Domain rank by total number of unique visitors
uv Unique visitors for a domain
vis Number of separate visits made to a domain by all unique visitors
pv Number of times a page has been loaded from a domain
avgstay Avg. number of seconds that a visit lasts
vpp Avg. number of times each unique visitor visits the domain
ppv Avg. number of pages displayed during a visit
att % of total minutes spent by all US users on the Internet that were spent on this domain

Daily Metrics

The default cost for a daily metric is 30 data points. You can access 365 days of historical data using the DATE parameter.

Metric Code Description
reachd % of all US users on the Internet that had at least one visit to this domain by day
attd % of total minutes spent by all US users on the Internet that were spent on this domain by day

Demographic Metrics

The default cost for demographics vary - see the chart below. You can access 25 months of historical data from current month using the DATE parameter.

Metric Code Description Cost
gen The split between males and females visiting a domain 13
age % of unique visitors in various age brackets 78
inc % of unique visitors in various income brackets 52

Advanced Metrics

The default cost for advanced metrics vary - see the chart below.

Metric Code Description Default Range Historical Cost
kw/kw_all Top 100 keywords for any domain 90 day avg. 90 day avg. 500
iref/iref_all Top 25 traffic sources for any domain Current month Current month 158
oref/oref_all Top 25 traffic destinations for any domain Current month Current month 50
related/related_all/ Top 10 related sites for any domain 10 Current month 10

Parameters

You can pass the following optional parameters when requesting data from the Compete API.

DATE

For DATE insert the code defining the time period you want metrics for (see below). If omitted the Compete API returns the default range of data for that metric. This parameter is available for all trended metrics.

Desired Range Parameter Valid Values
Latest N months | days &latest=(NUM_MONTHS|NUM_DAYS) NUM_MONTHS = 1 to 25
NUM_DAYS = 1 to 365
Specific start and end date (monthly) &start_date=YYYYMM
&end_date=YYYYMM
Current month to current month minus 24 (both)
Specific start and end date (daily) &start_date=YYYYMMDD
     &end_date=YYYYMMDD
Current day to current day minus 364 (both)

Invalid timeframes will return a response of 400, "INVALID."

When you request a date range which spans a period where data exists for some months (or days) and not for others, you will receive a full trend data structure with entries for each month but with value set to null in each entry. Entries which are null do not contribute to the query cost of your query. In the event that no data whatsoever exists in the period requested you will receive a response of 200, "NO_DATA".

Date Formatting

Dates are represented as strings in the format YYYYMM for monthly and YYYYMMDD for daily metrics. Example: January 2010 is represented as 201001 and the 15th of January 2010 is represented as 20100115. Sorting these strings in order will sort the dates in ascending calendar order.

&latest takes an integer representing the most recent number of months or days for which we want data. Example: if the latest month for which we have data is December, using &latest=6 on a month metric would yield data for July through December. For daily data, &latest will pull the most recent number of days for which you want data.

Example request for latest 3 months:

https://apps.compete.com/sites/facebook.com/trended/uv/?apikey=[APIKEY]&latest=3

Response

{
	status: "OK",
	data: {
	trends: {
		uv: [
		{
			date: "201601",
			value: 162010417
		},
		{
			date: "201602",
			value: 160334156
		},
		{
			date: "201603",
			value: 161515813
		}
			]
	},
		trends_low_sample: false,
		query_cost: 3,
		trends_frequency: "monthly"
		}
}

Example request for specific monthly range:

https://apps.compete.com/sites/facebook.com/trended/uv/?apikey=[APIKEY]&start_date=201512&end_date=201603

Response

{
    status: "OK",
        data: {
        trends: {
            uv: [
    {
            date: "201512",
            value: 163100002
    },
    {
            date: "201601",
            value: 162010417
    },
    {
            date: "201602",
            value: 160334156
    },
    {
            date: "201603",
            value: 161515813
    }
                ]
    },
        trends_low_sample: false,
        query_cost: 4,
        trends_frequency: "monthly"
        }
}

Example request for specific daily range:

https://apps.compete.com/sites/facebook.com/trended/attd/?apikey=[API_KEY]&start_date=20160301&end_date=20160305

Response

{
        status: "OK",
        data: {
        trends: {
            attd: [
        {
                date: "20160301",
                value: "8.32907580"
        },
{
                date: "20160302",
                value: "8.28974020"
        },
        {
                date: "20160303",
                value: "8.38288900"
        },
    {
                date: "20160304",
                value: "8.49341350"
    },
        {   
                date: "20160305",
                value: "9.56315260"
        }
        ]
},
            trends_low_sample: false,
            query_cost: 5,
            trends_frequency: "daily"
        }
}
[/api_description]

GRAPH

Return a GRAPH for monthly, daily and demographic data. Only available for trended metrics. Keywords, Incoming/Outgoing Traffic and Related Sites metrics do not have graph parameters available.

Add the following to a trended metric API call

&format=[IMAGE_FORMAT]

IMAGE_FORMAT types = png | jpg | gif

NOTE

  • Multi-metric requests using the "search" mode will only support comparing two metrics.
  • No data and invalid requests will return an image indicating no data or an error.

Example request to return a png chart:

http://apps.compete.com/sites/facebook.com/trended/uv/?apikey=[APIKEY]&format=png

Response Codes

Response Status Description Data point cost?
200 OK Successful request yes
200 NO_DATA No data is available for the requested domain/metric/time period no
400 INVALID The request contains invalid parameters or is formatted incorrectly no
403 ACCESS_DENIED The API key is not allowed to access the requested data or the key has hit its limit. The value in response.data.status_message will reveal which is the case. no
500 UNKNOWN ERROR Indicates an unanticipated technical error no
503 UNAVAILABLE Indicates that the Compete API is currently unavailable no

Data Structure

Every request will return a JSON encoded object. At the top level the response packet contains two key-value pairs: "status"; successful responses contain "data" and unsuccessful responses contain "status_message." A successful request using the parameters above will return a JSON encoded object with the following structure:

Structure definitions

  • status: A string, indicating whether the request was successful or not.
  • data: Contains a structure encoding all of the returned data matching the request.
  • trends: Trends is only applicable when calling a metric with historical data. When pulling keyword data, 'trends' will be replaced by 'keywords' and when pulling incoming referral data, it will be replaced by 'iref'.
  • status_message: Unsuccessful requests contain this string, providing an explanation as to why the request failed.
  • trends: Contains the actual data, formatted by month or day. This is an Object mapping from trend_codes (which identify the different trends of data available -- see below) to arrays of trend data points. Each data point is of the format {"date": "200907", value: 98292793} where data_point.date indicates the month or day to which the data applies and data_point.value is the numerical value of the trended data for that date.
  • trends_low_sample: Boolean parameter that if TRUE, means Compete has a statistically low amount of panel data for the target site in the current month.
  • query_cost: The total number of non-null data points returned in the data packet.
  • trends_frequency: Either "monthly" or "daily". This indicates the timescale on which the metric(s) returned operate. All metrics within a given data packet must always be of the same timescale.

Example response of an API key without access to a particular metric:

{
    "status": "OK",
    "status_message": "Not allowed to access this metric",
}

Advanced Querying

Multiple Metrics

To query for multiple metrics for a single domain add /search/:
https://apps.compete.com/sites/facebook.com/trended/search/?apikey=APIKEY&metrics=pv,uv,rank

Examples

One full monthly metric (13 data points):
https://apps.compete.com/sites/compete.com/trended/uv/?apikey=APIKEY

Most recent monthly data point for a metric:
https://apps.compete.com/sites/compete.com/trended/uv/?apikey=APIKEY&latest=1

Most recent year of data for two metrics:
https://apps.compete.com/sites/compete.com/trended/search/?apikey=APIKEY&metrics=uv,rank&latest=12

January, February, and March of 2016 for a monthly metric:
https://apps.compete.com/sites/compete.com/trended/uv/?apikey=APIKEY&start_date=201601&end_date=201603

A chart representing the most recent 6 months of data:
https://apps.compete.com/sites/compete.com/trended/uv/?apikey=APIKEY&latest=6&format=png

The most recent month of a daily metric (30 data points):
https://apps.compete.com/sites/compete.com/trended/attd/?apikey=APIKEY

November 15th through December 24th for a daily metric:
https://apps.compete.com/sites/compete.com/trended/attd/?apikey=APIKEY&start_date=20151115&end_date=20151224

Website Keyword data for the most recent 90 days:
https://apps.compete.com/apps/sites/facebook.com/kw/kw_all/?apikey=APIKEY

Client-Side Mashups Using JSONP

If you are building an application which is primarily client-side, you may wish to retrieve Compete API data directly to your users' browser. However, you will not be able to do so using the browser's XmlhttpsRequest object because of the Same-Origin Policy.

To help with this situation, the Compete API supports the JSONP protocol, which allows client and server to collaborate to work around the Same-Origin Policy. For more information about jsonp, take a look at the wikipedia entry https://en.wikipedia.org/wiki/JSONP

In order to place a JSONP call to the Compete API, format your request as normal, and then append jsonp=FUN_NAME to your query parameters, where window.FUN_NAME is some function which will handle the returned data. The Compete API will return the formatted contents of a tag, with fun_name being directly applied to the data set, thus: FUN_NAME({ ... });

You can work with JSONP directly by writing script tags into the DOM:

window.handle_uv_data = function (data) { ... };

var s = document.createElement('script'),
d = document.getElementByType('body')[0];
s.type = "text/javascript";
s.async = "async";
s.src ="https://apps.compete.com/sites/facebook.com/trended/uv/?apikey=[API_KEY]


&jsonp=handle_uv_data";  d.appendChild(s);

However, most major JavaScript libraries (such as jQuery, Prototype, Dojo, etc.) come with functionality or plugins which provide higher level abstractions for working with JSONP.