Getting Started

To get started simply create a free API account and register an app to get your API key.

All requests require 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 (eg. Unique Visitors, Visits, Rank)

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

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

Example Request

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

Example Request

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"


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://". (e.g. "")
  • DO request data for a specific subdomain if desired (e.g. ""). We have data for many, although not all, subdomains.

API KEY Parameter (Required)

For API KEY 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."

METRIC Parameter (Required)

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

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

DATE Parameter (Optional)

For DATE insert the code defining the time period you want metrics for (see below). 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.

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

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.

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

GRAPH Parameter (Optional)

To return a GRAPH simply insert the code for which format of graph you would like to receive (see below). 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. 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

Response Codes

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

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.

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": "201403", "value": 90714948},
                {"date": "201404", "value": 98292793},
                {"date": "201405", "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/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:,rank,uv,rank

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:,rank&latest=12

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: