Welcome to the Compete API! This API, or application programming interface, provides access to the competitive web analytics that support Compete's industry-leading services. We open our vast stores of consumer data for you to integrate and use in your business. You and your company can use this data to enhance existing applications or create entirely new services.

Free and Premium APIs

The Compete API is divided into five different APIs and two different levels of access:

Free: The Free API provides access to all of Compete's data types at limited quantities for any of the millions of domains in our database.

  • Premium data is available to paying customers. If you are interested in purchasing a greater volume of calls please contact us for details.
  • Free API users may show this data publicly (as long as you don't violate the Terms and Conditions

Premium: The Premium API provides access to an unlimited number of data points per day of Unique Visitors, Daily Reach, Daily Attention, Visits, Page Views, Average Stay, Visits per Person, Pages per Visit, Attention, Age, Income, Gender, Website Keywords, and Incoming Traffic for any of the millions of domains in our database.

  • There are 5 APIs: The Monthly Metric API, the Demographic API, the Daily Data API, the Keyword API, and the Incoming Traffic API.
  • The Premium API is available only to paying customers. If you are interested in becoming an Premium API customer learn more here.
  • Premium API customers may show this data behind a paywall to their own clients, employees, and/or paying subscribers.

This documentation will walk you through the process of getting an API key and how to use that key to integrate Compete's data into your own applications.

Getting Started

You can submit a sample request right now! All requests must include three primary pieces of information:

DOMAIN: The name of the domain you are requesting (e.g.,,

METRIC: The code of the metric you are requesting (e.g., Unique Visitors, Visits, Rank)

APIKEY: Your API key (provided when you sign up and available upon log-in)

There are other parameters that can be used to specify format, date ranges, and other preferences. These are covered in the advanced querying section.

Requests are submitted via https and have this format:

Example Request

This example request returns a list of the Unique Visitors to for the last year:

Example Request

Returned Data

    "status": "OK",
    "data": {
        "trends": {
            "uv": [
                {"date": "200906", "value": 90714948},
                {"date": "200907", "value": 98292793},
                {"date": "200908", "value": 103509116},
        "trends_low_sample": false,
        "query_cost": 13,
        "trends_frequency": "monthly"

Getting Your API Key

Creating an API key is free and easy. Simply click this signup link and fill out the form. Signup takes less than a minute and you'll receive your API key immediately afterwards.

If you would like to use the Premium API either fill out the provided form during the signup process or contact us through the form at this page with any questions you may have.

Compete APIs

Free API

The Free API is available free of charge and gives access to all data types, with a limit on how much data you can access each day. You are automatically given access to all metrics when you sign up for a new key. To access Compete's data directly, simply sign-up for a new Compete API key.

Monthly Metric API

The Monthly Metric API gives access to a suite of monthly metrics powered by Compete's industry-leading consumer panel. Metrics such as Unique Visitors, Average Stay, and Page Views are powerful indicators of online performance. Each metric can be trended for up to 25 months, and subdomain data is also available for each metric. Premium access to the Monthly Metric API is available via the Premium API; please contact if you are interested in a Premium subscription.

Demographic API

The Demographic API contains powerful audience measurement and consumer targeting data. Age, Income, and Gender are the three available demographic metrics, and are organized by cohort, or segmented into groups. Because these metrics are organized into cohorts, calls for the Age and Income metrics will return more than 13 data points for a year. The maximum amount of data points that each metric will cost to return one year of data is as follows:

  • Age - 78 data points
  • Income - 52 data points
  • Gender - 13 data points

Example Demographic API Request
Returned Data
    "status": "OK",
    "data": {
        "trends": {
            "male": [
                {"date": "201112", "value": "47.22"},
                {"date": "201201", "value": "47.25"},
                {"date": "201202", "value": "47.20"},
        "trends_low_sample": false,
        "query_cost": 13,
        "trends_frequency": "monthly"

Daily Data API

The Daily Data API contains daily share data for websites. The two available metrics are Share of Visits (reach) and Share of Time (attention). These two metrics allow users to view weekly and monthly trended behavior of people on their websites. Data is available for the previous 365 days. The daily data is updated 2-4 days behind real time and provides reliable insights into recent trends and spikes of activity across the domains in Compete's database. Because these two metrics are share-based metrics, the data is not normalized.

Example Daily Data API Request

Returned Data

    "status": "OK",
    "data": {
        "trends": {
            "reachd": [
        "trends_low_sample": false,
        "query_cost": 30,
        "trends_frequency": "daily"

Keyword API

The Keyword API provides the ability for users to call the top 100 keywords for any website in Compete's database. The keywords are ranked by search referral share, or the percentage of traffic that the keyword brings to that website. A query with all data returned will cost 500 data points per website, but if null values are returned, or there are fewer than 100 keywords available, the query will only cost the amount of data points that are returned. Note that keyword data is based on a 90 day moving window, so it is updated 2-4 days behind real time and updates daily. This is a perfect way to see the top keywords of competitive sites, or to display them in your applications. In addition to search referral share, a call will return Paid Share %, Natural Share %, Average Time Index, and Total Time Index for each keyword. Please email if you are interested in receiving Premium access to this data.

Example Keyword API Request

Returned Data

    "status": "OK",
    "data": {
        "keywords": [
            "keyword":"facebook login",
    "trends_low_sample": false,
    "keywords_frequency": "90 days"
    "query_cost": 494,

Metric List

Metric Name Historical Data Description Metric Code
Rank 25 months The ranking of the domain by total number of unique visitors rank
Unique Visitors 25 months The number of unique people who visited a domain uv
Visits 25 months The number of separate visits made to a domain by all unique visitors vis
Page Views 25 months The number of times a page has been loaded from a domain pv
Average Stay 25 months The average number of seconds that a visit lasts avgstay
Visits per Person 25 months The average number of times each unique visitor visits the domain vpp
Pages per Visit 25 months The average number of pages displayed during a visit ppv
Attention 25 months The percent of total minutes spent by all US users on the Internet that were spent on this domain att
Reach (Daily) 365 days The percent of all US users on the Internet that had at least one visit to this domain by day reachd
Attention (Daily) 365 days The percent of total minutes spent by all US users on the Internet that were spent on this domain by day attd
Gender 25 months The split between males and females visiting a domain gen
Age 25 months Percent of unique visitors in various age brackets age
Income 25 months Percent of unique visitors in various income brackets inc
Top Keywords 90 day average Top 100 keywords for any website kw/kw_all
Incoming Traffic Current Month Top 25 traffic sources for any website iref/iref_all

Incoming Traffic API

The Incoming Traffic API provides the ability for users to create calls to pull the top 25 referring websites to any of the millions of websites in our database. This gives a comprehensive view of traffic sources for the website that you, or your users want to analyze. The websites are ranked by visits, or the share of traffic that the referrer brings to the website. Each call will also contain the total visits number for the site and the amount of direct traffic that the website has received (when the website is a homepage, or the first site visited during a browsing session). If there are fewer than 25 incoming websites available, only the available data will be returned. This data is published between the 6th and 15th of the following month, due to stringent normalization techniques. Calls will return a host of data: the incoming website URL, total visits from that website, the numerical change from the previous month, the percentage change from the previous month, the share of visits that the incoming website represents, and the change in share of visits from the previous month. If you are interested in obtaining Premium access to these powerful metrics, please email

Example Incoming Traffic API Request


Returned Data

    "status": "OK",
    "data": {     
        date: "20121201"
        "incoming_referrals": [
            {"+/-": 12179756,
            "incoming_referral": "",
            "u0394share": "(+/-)0.96"
            "industry_category":"General Portals and Search"
    "trends_frequency": "Monthly"
    "query_cost": 108,

Pricing and Data Points

Amount of Access

By default every Free application is restricted to a limited amount of data from the Compete API per day. The Compete API counts each data point with each https request that is placed to it with your API key as one point against this maximum. Calls which return NO_DATA or INVALID are not counted. The window of "one day" stretches from midnight to midnight, EST.

Premium access to our data can be purchased with a pricing structure that fits your business needs. If you are interested in Premium access to Compete's metrics please contact us for pricing and availability details.

Data Points Versus "Calls"

If you have requested and received access to the Premium API you will be charged based on the number of data points you receive. One call to the API can return over 100 data points! In fact, the example call at the top of this documentation that requests unique visitors data returns 13 data points, one for each month of the past year. For JSON representations of metric data, the number of data points is always included as NO_DATA, INVALID, and ERROR requests do not have a data member but also do not have an assessed query cost.

Each time you request a data point it is added to your total whether you have previously queried for that data point or not. In the case of demographics, the one request for either Age or Income will return 6 data points per month, each data point corresponding to a range (i.e., "18-24: 30%" would be one data point while "25-34: 29%" would be an additional data point).

Allowed Uses & Branding Requirements

Allowed Uses

Every user of the Compete API is subject to the terms and conditions you accept when you generate your API key. There are two key restrictions in these terms that we want to highlight here:

  • Caching data is not allowed: We charge for each time you use our data, so if you cache data instead of calling us each time you need it, we will consider it a violation.
  • Keep data behind a pay wall: This is the same data that we use to power our core business so while we want you to use it for your own paying customers, we don't want it available to the general public.

Branding Requirements

Users of the Free API and those Premium users who do not elect to remove branding should attribute Compete metrics in two ways.

  • Use an approved brand image (supplied below) near where metrics from the Compete API appear.
  • Link back to the Profile for the data point being referenced by the Compete metric (e.g.,

Acceptable Imagery Brand Image URL

Creating the Call

All requests to the Compete API are just simple https 1.1 requests. Browsers can make these directly, and most programming languages have libraries suitable for making these calls. In the future, Compete will work to create API client libraries in some popular languages, but for now you should just use https.

When requesting data from the Compete API you may utilize up to five different parameters. Those parameters should be formatted in the following manner:[DATE]&[GRAPH]

DOMAIN Parameter (Required)

  • For DOMAIN insert the name of the domain or subdomain for which you wish to receive data.
  • DO request data for a domain by putting just the domain name without a leading "https://" and without a leading www. (e.g. "" not "")
  • DO request data for a specific subdomain if desired (e.g. ""). We have data for many, although not all, subdomains.
  • DON'T use "www."  We currently disregard the leading "www" in any request but in future versions of the API this behavior may change. To avoid having your application impacted by these future releases, simply avoid listing "www" in the domain parameter.

Example Requests:[DATE]&[GRAPH][DATE]&[GRAPH]

METRIC Parameter (Required)

For METRIC insert the code for the metric you wish to receive. The available metrics and their codes are:

Metric Name Historical Data Available Metric Code
Rank 25 months rank
Unique Visitors 25 months uv
Visits 25 months vis
Page Views 25 months pv
Average Stay 25 months avgstay
Visits/Person 25 months vpp
Pages/Visit 25 months ppv
Attention 25 months att
Daily Reach 365 days reachd
Daily Attention 365 days attd
Gender 25 months gen
Age 25 months age
Income 25 months inc
Top Keyword 90 day rolling (updates daily) kw/kw_all
Incoming Traffic Current Month iref/iref_all

Example Requests[DATE]&[GRAPH][DATE]&[GRAPH]

APIKEY Parameter (Required)

For APIKEY insert the API key you created for this application after signing up. You can locate your key at any time by logging in and clicking on "Dashboard." Your API key is private and should not be shared as all usage will be charged to your account.

Example Request


DATE Parameter (Optional)

For DATE insert the code defining the time period you want metrics for (see below). This parameter is not required and can be omitted if desired. If omitted the Compete API returns data for the most recent 13 months for a monthly or demographic metric. For daily metrics, it returns data for the most recent 30 days. This parameter is available for all trended metrics, so Keyword and Incoming Traffic APIs cannot use the date parameters.

Desired Date 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 data) &start_date=YYYYMM


Current month to current month minus 24 (both)
Specific start and end date (daily data) &start_date=YYYYMMDD


Current day to current day minus 364 (both)

Should you submit a start date which is later than an end date, or any date which doesn't exist you will receive a response of 400, "INVALID", indicating that your request does not make sense.

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" and response data will not exist. Please reference the glossary below for failed requests.

Example Requests[GRAPH] &[GRAPH] &[GRAPH]

GRAPH Parameter (Optional)

For GRAPH insert the code for which format of graph you would like to receive (see below). This parameter is not required and can be omitted if desired. If omitted no graph will be returned. Note that this is only available for trended metrics, so Keywords and Incoming Traffic metrics do not have graph parameters available.

The Compete API generates graphs for your use that are hosted on our domain. The API will provide you with a link to embed those graphs into your web page. You can specify that your graph should be returned as either a PNG, a JPG, or a GIF.

To request a graph simply insert this query parameter


to any well-formed trend request, where

IMAGE_FORMAT = png | jpg | gif

You may fetch trend images to your server by placing these calls from the back end.

Two important notes about the GRAPH parameter:

  • Multi-metric requests using the "search" mode will only support comparing two metrics. It is not currently possible to compare more than two metrics graphically.
  • If you use the tag approach described above and you embed an image for which we have no data, or in some manner send an invalid request, the Compete API will serve back an image indicating the lack of data, or error.

Example Requests[DATE]&format=png

Call Success or Failure

The Compete API communicates whether a call was a success or failure in two ways.

  • The https response code indicates whether a request was successfully processed.
  • The 'status' term in the response to indicate the type of response.
  • If successful, the response will contain a 'data' term, containing the structured data for your query. Otherwise, it will contain the 'status_message' term containing an explanation of why your request returned the status that it did.
Response Code Status Description Charged for data point?
200 OK The request was well-formed and at least one data point has been returned yes
200 NO_DATA The request was well-formed but no data was available for the requested domain/metric/time period no
400 INVALID The request contains invalid parameters or parameters which do not make sense when grouped together no
403 ACCESS_DENIED The request is well-formed but the application key is not allowed to access the requested data. This may be because the key is over its daily query quota or else because it is not authorized to request the data in question. The value in will reveal which is the case. no
500 UNKNOWN ERROR Indicates an unanticipated technical error within the specific request no
503 UNAVAILABLE Indicates that the Compete API is currently unavailable no
  • To summarize, a response code of 200 indicates a successfully processed call. A response code other than 200 indicates failure, and the values in "status" and "status_message" will contain an explanation of why the call failed.
  • A 500 or 503 response code indicates an error or problem with our system. We will of course minimize any disruption to API access; the codes are included here for completeness.
  • Low Sample Warning. Some domains have a "low sample warning" flag attached to their data return. When this warning is true it indicates that although Compete has enough data to make a projection, the margin of error is greater than we prefer. It is up to you to take this into account within your application.
  • The low sample warning is returned in the variable "data.trends_low_sample" and can be either true or false.
  • Response Format
  • Data Structure
  • Every request will return a JSON encoded object.  At the top level the response packet contains two key-value pairs: Every response contains "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:
        "status": "OK",
        "data": {
        "trends": {
        "uv": [
        {"date": "200906", "value": 90714948},
        {"date": "200907", "value": 98292793},
        {"date": "200908", "value": 103509116},
        "trends_low_sample": false,
        "query_cost": 13,
        "trends_frequency": "monthly"

Here's what those values mean:

  • status: A string, indicating whether the request was successful or not. See below for a discussion of the possible values of status.
  • 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.

Let's talk about the structure of the data returned by successful requests. Within, we find the following terms:

  • trends: Contains the actual data, formatted by month (or, for some metrics, by 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 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: This Boolean parameter is true if Compete has a statistically low amount of panel data for the target site in the current month. If is true then the data is derived from a smaller amount of clickstream data and is less likely to be highly accurate.
  • query_cost: This is the total number of non-null data points returned in the data packet (i.e., the  total number of meaningful data points across all the trends in the response 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.

An unsuccessful request using the parameters above will return a JSON encoded object with the following structure:

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

Date Formatting

In the Compete API we always represent dates as strings of the format YYYYMM(DD), meaning the year is first then the month and then the day (if appropriate). If you are requesting a monthly metric, use only the year and month in your request. If you are requesting a daily metric, use year, month, and day. For example, the month of January 2010 is represented as 201001, while the 15th of January 2010 is represented as 20100115.

This format has two advantages:

  • It avoids ambiguities between American and British date formats.
  • Sorting these strings in order will sort the dates in ascending calendar order.

Advanced Querying

Forming Advanced Queries

The sites/<site>trended part of the API returns either:

  • A JSON stream with trended Site Analytics data
  • An image representing trended data, very much like the ones you see on
  • JSON in the form of a predicate via &jsonp

There are two ways in which you can query for data:

1. You can query for a specific metric:

2. You can query for several metrics at a time:

And the parameters you can use to query for trended metrics are:

  • include &format=png for a visual graph (or JPG or GIF, if you prefer)
  • start_date: the start date of the trend. YYYYMM for monthly metrics, YYYYMMDD for daily metrics
  • end_date: the trend's end point. Idem start_date
  • latest: an alternative to start_date and end_date, latest takes an integer representing the most recent number of months or days for which we want data. For 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.
  • jsonp: javascript magic not included. If you aren't sure what jsonp is, take a look at the wikipedia entry

Advanced Query Examples

Finally, here are some examples:

One full monthly metric (13 data points):

Most recent data point for a metric:

Most recent year of data for two metrics:

January, February, and March of 2013 for a monthly metric:

A chart representing the most recent 6 months of data:

The most recent month of a daily metric (30 data points):

November 15th through December 24th for a daily metric:

Website Keyword data for the most recent 90 days:

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' browsers. However, you will not be able to do so using the browser's XmlhttpsRequest object because of the Same-Origin Policy.

To help you deal with this situation, the Compete API supports the JSONP protocol, which allows client and server to collaborate to work around the Same-Origin Policy.

In order to place a JSONP call to the Compete API, format your request as normal, and then append


to your query parameters, where


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 ="

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