Quantcast Measurement API Documentation

  1. Audience
  2. Getting started
  3. Overview
  4. Getting started
  5. Call Structure
    1. Root
    2. Resource types
      1. Network
      2. Domain
      3. Mobile App
      4. Segment
    3. Parameters
      1. Country filter
      2. Platform filter
      3. Mobile Platform filter
      4. Version filter
      5. Limit
      6. Offset
    4. API Key
    5. Signature
    6. Example return
  6. Queries

 

   FAQ

  1. General Questions
  2. Details: Costs, Access, and Availability
  3. Troubleshooting

 

 

Audience

This document is intended as a "quick start" guide for developers who want to integrate the Quantcast API into their websites or workflows. It assumes you are familiar with the basic concepts of APIs, JSON, HTTP request methods, and the REST style of software architecture. If you have questions after reading this document, you can contact us here.

Overview

The Quantcast API is implemented using common REST principles.  Currently the API supports GET requests over HTTPS, and returns responses as JSON objects.  The following sections describe the URL Structure and Authentication methods for all API requests, and list the Queries that are currently supported.

Developers should also review the shared Request Parameters that are common to many requests.

 

Getting started

To get up and running quickly with the Quantcast API, perform the following steps:

  1. Sign up here to get your free developer key.
  2. You will receive a validation email that will contain a link to validate your request.
  3. At this time, it may take up to 2 business days for your request to be approved and for an API Key and Secret key to be assigned.
  4. Browse and experiment with the API Console, a tool that allows you to view API requests and results before you begin coding.
  5. Integrate the desired results from the API into your site.

 

Call Structure

Request = Root + Resource + Parameters + API Key + Signature

Root

All Quantcast API requests have the following root.

https://measure.api.quantcast.com/api/{version}/…

Currently {version} must be v1.  Follow our blog for information about new versions of the API, and deprecation notifications for older versions.

 

 

Resource Types

Resources

 

 

Network

Almost all API calls require a publisher’s unique identifier (their publisher code), which is usually referred to as a “pCode”. 

https://measure.api.quantcast.com/api/{version}/networks/{pCode}/traffic/cookies…

A network is simply the set of properties (sites, apps, syndicated content, etc) measured by a particular account.  In the case of single-site owners, the network is equivalent to the site, plus the traffic from syndicators. The syndicators for a network are the external sites from which people viewed the publisher’s content. For example, for a publisher of Quantified Flash videos, the syndication will show sites where the videos are embedded. Google is a common syndicator of HTML content via its cached results pages. If a publisher run's Quantcast code on their site, but haven't submitted it via the "add a site" process, the traffic from that site will show up as syndicated traffic.  

 

Domain

For more granular detail, the domain value specifies a specific domain (or subdomain) to look up, as in the case below:

https://measure.api.quantcast.com/api/v1/networks/{pCode}/domains/{domain}/demographics…
https://measure.api.quantcast.com/api/v1/networks/p-16-nFEkkjh789M/domains/foo.com/demographics…

 

Mobile App

For more granular detail, the app_id value specifies a specific mobile app you want to learn about, as in the case below:

https://measure.api.quantcast.com/api/v1/networks/{pCode}/apps/{app_id}/demographics… 
https://measure.api.quantcast.com/api/v1/networks/p-16nFEkkjh799M/apps/2daya45nb2njkr2x/demographics…

For network-owned regular apps, the app id can be found by calling:

 https://measure.api.quantcast.com/api/v1/networks/{pCode}/apps 

For syndicated apps, the app id can be found by calling:

 https://measure.api.quantcast.com/api/v1/networks/{pCode}/syndicators?platform=mobile_app 

 

Segment

Another way to pull data is by audience segments, the segment_id value specifies a specific segment to look up, as in the case below. The segment_id can be the encoded universally unique segment identifier starting with wpath and including the network code (pCode), or simply the properly encoded segment name (see examples below). To learn more about audience segments, click here.

https://measure.api.quantcast.com/api/v1/networks/{pCode}/segments/{segment_id}/demographics…
https://measure.api.quantcast.com/api/v1/networks/p-16nFEkkjh799M/segments/logged-in/demographics…

We recommend obtaining the segment_id programmatically by making a “segments” call on the Measure API.

Note: All special characters need to be encoded using standard URL encoding (RFC 3986)

Example:

/ should be %2F

+ should be %2B

Other special characters including non-ASCII characters should be properly escaped using HTML encoding standard to keep the fidelity.   In case you are not familiar with special characters encoding, a reference can be found here:  http://www.w3schools.com/tags/ref_urlencode.asp

 

Parameters:

Geographic Filter (country=...)

For most API calls, a country geographic filter is provided and optional. The country parameter can be left blank, or a 2-letter country code can be used to filter the results by a specific country. For most calls, the default is "Global", but because global demographic data is not available, leaving the Geographic filter empty for demographic calls will default to “US” data.   

 Here is a list of country codes. For instance, to return Global totals for pageviews, use:

https://measure.api.quantcast.com/api/v1/networks/{pCode}/domains/{domain}/traffic/pageviews…
https://measure.api.quantcast.com/api/v1/networks/{pCode}/domains/{domain}/traffic/pageviews?Country=GLOBAL…

To return values for US only, use:

https://measure.api.quantcast.com/api/vq/networks/{pCode}/domains/{domain}/traffic/pageviews?Country=US…

 

Platform Filter(platform=...)

For most traffic calls, the requested data can be filtered to return only the value for the specified platform, unless there is an exception (see the list below of API calls with restrictions). If the filter is available, the parameter can either be left blank (same as set to the default value “all”), which returns the data for all platforms, or set to a valid platform identifier. Below is the list of valid platform identifiers (case insensitive):

  • all: the total of all platforms (default)
  • web: only data from online web and mobile web (excluding mobile apps)
  • online_web : only data from the online web (excludint tablets or phones)
  • mobile_web: only data from the mobile web
  • mobile_app: only data from mobile apps

When looking at a domain, mobile app data is automatically excluded (but online web or mobile web can be specified).  When looking at a mobile app, all web data is automatically excluded.  All platforms are possible for network and audience segments.

API calls with restrictions:

  • For Network.getPeople, we only provide data for web (i.e. online_web/mobile_web/mobile_app are not valid here and “all” provides the same data as “web”).
  • For Network.getPageviews, we don’t provide data for mobile apps as the pageview metric does not apply (i.e. mobile_app is not valid, and “all” provides the same data as “web”).
  • For all domain related calls, mobile app data is not provided and “all” provides the same data as “web”.
  • For all demographics calls, only all/web/mobile_app are valid, and the corresponding data will only be returned when it is available.
  • For all mobile app related calls, platform filtering is not available since it is always implicitly “mobile_app”.
  • For the "top-sites" call, only “all” and “mobile_web” are valid parameters.

Here is an example using the Platform filter:

https://measure.api.quantcast.com/api/v1/networks/{pCode}/segments/{segment_id}/demographics?platform={platform}&…   
https://measure.api.quantcast.com/api/v1/networks/p-16nFEkkjh799M/segments/logged-in/demographics?platform=mobile_app&… 

 

Mobile Platform Filter (mobile_platform=...)

For mobile app calls, the requested data can be filtered to return only the values for the specified mobile platform. This parameter can either be left blank (same as set to the default value “all”). The following platforms are available (case insensitive):

  • Android:  only data from devices running Android
  • iOS:  only data from devices running iOS

Note:

  • The API calls to demographic or audience interest data do NOT support this filter as they alway returns the overall demographics data for that particular app specified by the app ID, regardless of platforms/versions.
  • This filter can be used together with the version filter.

Here is an example using the Mobile_Platform filter:

 

https://measure.api.quantcast.com/api/v1/networks/{pCode}/apps/{app_id}/traffic/installs?mobile_platform={mobile_platform}&… 
https://measure.api.quantcast.com/api/v1/networks/p-16nFEykjh799M/apps/2daey45nb2njkr2x/traffic/installs?mobile_platform=ios&… 

 

App Version Filter (version=...)

For mobile app calls, the requested data can be filtered to return only the values for the specified app version. This parameter can either be left blank (same as set to the default value “all”), which returns the data from apps with any version number, or set to a specific version number of that app. The version number should match exactly the one in that particular app (e.g. 2.1.0).

Notes:

  • This filter only works for regular network-owned apps. For syndicated apps, we do not provide versioned data.
  • The API calls to demographic or audience interest data do NOT support this filter as they alway returns the overall demographics data for that particular app specified by the app ID, regardless of platforms/versions.


Here are some examples of the possible cominations. For example:

  • mobile_app=all &version=all (default, if not specified) -> returns all the data from any apps
  • mobile_app=iOS&version=all -> returns the data from all apps with any version number running on iOS
  • mobile_app=Andriod&version=2.1.5 -> returns the data from the specific app with version number 2.1.5 and running on Andriod
  • mobile_app=all&version=2.1.5 -> this is not valid and an error message will be returned

 

Here is an example using the Version filter:

 https://measure.api.quantcast.com/api/v1/networks/{pCode}/apps/{app_id}/traffic/installs?version={version}&… 
https://measure.api.quantcast.com/api/v1/networks/p-16nFEkkjh799M/apps/2daea45nb2njkr2x/traffic/installs?version=5.3&… 

 

Limit (limit=...)

A record-returned limit is required for some of our API calls.  Here is an example of a call using the limit parameter. 

https://measure.api.quantcast.com/api/v1/networks/{pCode}/segments?country=GLOBAL&limit=1000&offset=0 

For calls where it is required and not included, a limit will be used and specified in the JSON response. 

 

Offset

A record offset can also be specified for some API calls.

Here is an example of the limit parameter in use. 

https://measure.api.quantcast.com/api/v1/networks/{pCode}/segments?country=GLOBAL&limit=1000&offset=1000 

For calls where it is an available option, the default offset is 0.

 

 

API Key

A valid Quantcast API Key must be passed via the api_key parameter.  If you have been issued an API key, you will find it here.  If you do not have an API key you can request one by registering.  Here is an example structure:

https://measure.api.quantcast.com/api/v1/networks/{pcode}/domains?Country=GLOBAL?api_key={key}…
http://measure.api.quantcast.com/api/v1/networks/p-16jj798hhkjhM/domains/foo.com/traffic/cookies?country=GLOBAL&api_key=abhp3mru7687fhj6xh379np4…

 

Signature

Each request must be signed. The validity of the signature is determined by examining a sig parameter from the query string of the request.

The sig value is calculated by generating an MD5 hash made up of the API key, the API user's shared secret (If you have been issued an API key and secret you will find them here), and a UNIX timestamp reflecting number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) at the time the request was made. A five-minute wiggle is permitted on either side of the current timestamp on the Mashery server to allow for reasonable clock drift.  Most programming languages provide an md5()-type of function. The signature should be generated using such a function.

The following is an example of generating a valid signature with PHP:

 

 $apikey = '2fvmer3qbk7f3jnqneg58bu2'; 
 $secret = 'qvxkmw57pec7'; 
 $timestamp = gmdate('U'); // 1200603038 
 $sig = md5($apikey . $secret . $timestamp); 6997e1dd775fa

 

Here is an example request to the JSON-RPC interface to the Quantcast API, based on a timestamp of 1200603038 (Thu, 17 Jan 2008 20:50:38 +0000), an apikey of 2fvmer3qbk7f3jnqneg58bu2 and a secret of qvxkmw57pec7:                 

http://measure.api.quantcast.com/api/v1/networks/p-16jj798hhkjhM/domains/foo.com/traffic/cookies?country=GLOBAL&api_key=2fvmer3qbk7f3jnqneg58bu2&sig=65a08176826fa4621116997e1dd775fa
 

Example Return

The call above returns the unique number of cookies for a given domain.  For every day the site has been quantified, it returns the unique count per day, the previous week’s unique cookie count, and the preceding 30-day's unique cookie count.  Here is an excerpt:

 

Sample call: 

https://measure.api.quantcast.com/api/v1/networks/{p-code}/domains/{domain}/cookies&api_key={API_key}&sig={Signature}


Sample return:



{
    "freshness": {
        "next_expected_update": "2013-04-02T01:00:59Z", 
        "updated": "2013-03-31T02:07:07Z"
    }, 
    "name": "foo.com", 
    "p-code": "p-8gy6ighjx45", 
    "quantified": true, 
    "reach_details": [
        {
            "country": {
                "code": "GLOBAL", 
                "id": "GLOBAL", 
                "name": "Global"
            }, 
            "days": [
                {
                    "day": "2008-02-28T00:00:00Z", 
                    "value": 611230.0
                }, 
                {
                    "day": "2008-02-29T00:00:00Z", 
                    "value": 501762.0
                }, 
                {
                    "day": "2008-03-01T00:00:00Z", 
                    "value": 607439.0

 

 

Queries

Here is the list of queries that can be made to our API. 

Resource

Description

Parameters

top-sites

 

Returns an ordered list of sites ranked by reach (includes non-quantified sites for US only)

 

Example

Country, Platform, Limit, Offset

networks/{pCode}

networks/{pCode}/domains/{domain}

networks/{pcode}/apps/{app id}

networks/{pCode}/segments/{segment_id}

Returns the list of calls available through our API for that particular “object”

 

Example

Country, Platform.

For network-owned apps: Country, Mobile_Platform, Version

For syndicated apps: Country, Mobile_Platform

 

networks/{pCode}/domains

Returns the list domains for a given network and the number of people visiting each domain in the preceding 30 days.

 

Example

Country, Limit, Offset

networks/{pCode}/domains/{domain}/subdomains

Returns the list of subdomains for a given network and the number of people visiting each subdomain in the preceding 30 days

Example

Country, Limit, Offset

networks/{pCode}/segments
networks/{pCode}/segments/{segment_id}/segments

Returns the list of top-level segments for a given resource and the number of Uniques visiting each segment in the preceding 30 days

Example

Country, Limit, Offset

networks/{pCode}/syndicators

Returns the list of syndicators for a given network and the number of people visiting each syndicator in the preceding 30 days

Example 

Country, Platform

networks/{pCode}/demographics

networks/{pCode}/domains/{domain}/demographics

networks/{pcode}/apps/{app id}/demographics

networks/{pCode}/segments/{segment_id}/demographics

Returns our set of demographic data for the defined resource (preceding 30 days)

Example

Country, Platform

 

We do not provide demographics data for syndicated apps

networks/{pCode}/interests

networks/{pCode}/domains/{domain}/interests

networks/{pcode}/apps/{app id}/interests

networks/{pCode}/segments/{segment_id}/interests

Returns the list of interest reports available through our API for that particular resource.

Currently the two calls returned by this query are interests/domains and interests/categories.

Example

Country, Platform

 

We do not provide interests data for syndicated apps

networks/{pCode}/interests/domains

networks/{pCode}/domains/{domain}/interests/domains

networks/{pcode}/apps/{app id}/interests/domains

networks/{pCode}/segments/{segment_id}/interests/domains

Returns a list of domains that users of the identified resource have visited in high proportions relative to the overall internet population in the preceding 30 days. For each domain returned, the API provides the affinity index, the percentage of the resource that also visits the site, and the % of the site that visits the resource.

Example

Country, Limit, Offset

 

We do not provide interests data for syndicated apps

networks/{pCode}/interests/categories

networks/{pCode}/domains/{domain}/interests/categories

networks/{pcode}/apps/{app id}/interests/categories

networks/{pCode}/segments/{segment_id}/interests/categories

Returns a list of interest categories that users of the identified resource have visited in high proportions relative to the overall internet population in the preceding 30 days. For each category returned, the affinity index is provided.

Example

Country, Limit, Offset

 

We do not provide interests data for syndicated apps

networks/{pCode}/traffic

networks/{pCode}/domains/{domain}/traffic

networks/{pcode}/apps/{app id}/traffic

networks/{pCode}/segments/{segment_id}/traffic

Returns summarized traffic data for the defined resource over the preceding 30 days.  Will return slightly different labels for resources with less than 30 days worth of data.

Example

Country, Platform

For network-owned apps: Country, Mobile_Platform, Version

For syndicated apps: Country, Mobile_Platform

networks/{pCode}/traffic/visits

networks/{pCode}/domains/{domain}/traffic/visits

networks/{pcode}/apps/{app id}/traffic/visits

networks/{pCode}/segments/{segment_id}/traffic/visits

 

Returns the number of visits to a given resource.  For every day the resource has been quantified, it returns the number of visits to the resource that day, the number of visits the previous week, and the number of visits the previous month. 

Example

Country, Platform

For network-owned apps: Country, Mobile_Platform, Version

For syndicated apps: Country, Mobile_Platform

 

networks/{pCode}/traffic/cookies

networks/{pCode}/domains/{domain}/traffic/cookies

networks/{pcode}/apps/{app id}/traffic/cookies

networks/{pCode}/segments/{segment_id}/traffic/cookies

Returns the number of unique cookies (or devices using mobile apps) for the given resource.  For every day the resource has been quantified, it returns the unique count per day, the previous week’s unique cookie count, and the preceding 30-day's unique cookie count".  

Example

Country, Platform

For network-owned apps: Country, Mobile_Platform, Version

For syndicated apps: Country, Mobile_Platform

networks/{pCode}/traffic/people

networks/{pCode}/domains/{domain}/traffic/people

networks/{pCode}/segments/{segment_id}/traffic/people

 

 

Returns the number of people visiting the given resource.  For every day the resource has been quantified, it returns the number of people visiting the resource per day, the" previous week’s people count, and the preceding 30-day's people count.

Example

Country, Platform

networks/{pCode}/traffic/pageviews

networks/{pCode}/domains/{domain}/traffic/pageviews

networks/{pCode}/segments/{segment_id}/traffic/pageviews

Returns the number of pageviews for a given resource.  For every day the resource has been quantified, it returns the unique count per day, the previous week’s pageview count, and the preceding 30-day's pageview count. 

Example

Country, Platform

networks/{pcode}/apps/traffic/installs
networks/{pcode}/apps/{app id}/traffic/installs

Returns the number of installs for a given app.  For every day the app has been quantified, it returns the install count per day, the previous week’s install count, and the preceding 30-day's install count. 

Example

For network-owned apps: Country, Mobile_Platform, Version

For syndicated apps: Country, Mobile_Platform

networks/{pcode}/apps/traffic/upgrades
networks/{pcode}/apps/{app id}/traffic/upgrades

Returns the number of upgrades for a given app.  For every day the app has been quantified, it returns the upgrade count per day, the previous week’s upgrade count, and the preceding 30-day's upgrade count. 

For network-owned apps: Country, Mobile_Platform, Version

For syndicated apps: Country, Mobile_Platform

 

 

Is there a data resource that is not available in the calls that you would like to see added?  Email: measure.api@quantcast.com

 

FAQ


 

General Questions

1. What is an API?

An application programming interface (API) is a protocol intended to be used as an interface by software components to communicate with each other. An API sets the rules of communication between two pieces of software. The Quantcast Measure API defines how you can write software to access your Quantcast data.

2. Why has Quantcast decided to make its content/data available via Measure API?

We have several high-volume data users accessing Quantcast Measure data in mass volume and multiple times a day. Those publishers and others asked about a Measure API so they could customize their data pulls.

The Measure API will allow also allow people to see their measure data in new ways, combined with other data, to garner new insights unique to their business needs.

3. Where can I learn more about the Measure API?

Read our documentation at http://developer.quantcast.com or email us at measure.api@quantcast.com with any specific questions.

4. How can I gain access to the Measure API?

 You can apply for an API key here: http://developer.quantcast.com/member/register

Please use an email address that has access to your Quantcast account.  If you do not yet have a Quantcast account, please sign up here: https://www.quantcast.com/user/signup

5. Who is the intended audience for the Quantcast Measure API?

At this stage, any Quantified web publisher can use the API. It is most likely to benefit users who measure a number of different properties or who use Audience Segments.

Details: Costs, Access, and Availability


1. How much does the Quantcast Measure API cost?

Our API is free within the usage limits described when you register for a developer key. If you have a specific application that requires more than the allotted limit of API calls per day, please email us at measure.api@quantcast.com and describe your usage needs.

2. Do I need to give Quantcast credit if I use information from the Measure API?

Yes, but only if you publish the data outside your company.  

3. What data formats does the Quantcast measure API support?

We currently support JSON and response types. For more information, check out our documentation at developer.quantcast.com  to learn more about how to interact with our API.

4. I am not a Quantified publisher, can I still use the API?

Not yet. Currently the Measure API can only be used to collect data about property measured with your own Quantified site.  It is easy and free to get Quantified.If you are interested in using the API to access Quantcast data about other sites, please contact us at measure.api@quantcast.com and we will notify you when that feature becomes available.

5. Can I use the API to access data about my mobile properties?

Yes!  The Quantcast Measure API allows you measure apps and to filter site or account data based on whether or not the traffic came from a mobile device.

 

6. What are default rate key limits?

 2 calls per second and 5,000 calls per day. Limits can be adjusted on a case by case basis. Please direct questions to measure.api@quantcast.com.

7. What are the API’s limitations at this stage?

Our API allows you to pull any data available via the main traffic graph or the demographic report. API partners cannot yet pull the following data:

  • Video
  • Business
  • Lifestyle reports
  • Ranked lists of top states, cities, countries, or DMA's
  • Retention graph

Please let us know if you are interested in pulling this data via api by emailing measure.api@quantcast.com and we will use that information when prioritizing new features.


Troubleshooting


1. I signed up and my calls are not working. Why?

  • It can take up to two business days to process your application. Unless you have received an email from us saying that your account is live, your calls will receive "<h1>Developer Inactive</h1>" errors.     
  • If more than two business days have passed or you have received email notification that your account is live and you still have trouble, please contact us at measure.api@quantcast.com.
  • If neither of the above is true, please refer to the IO documentation to ensure that you are forming the calls correctly. If you confirm that this is the case, please email us at measure.api@quantcast.com.

2. My call is not returning what I think it should. What should I do?

 Please refer to the IO documentation for guidance. If you still don't see what you're expecting, please contact us at measure.api@quantcast.com.


3. How do I find my "P-code"?

Your P-code can be found in the activation email sent to you after registration. It should contain the subject line "API Is Live".  Alternatively, you can log into Quantcast and click on the Quantcast logo (quantcast.com). 
Your P-code will appear in your right-hand navigation: 

4. How do I contact support?

For API support, please email measure.api@quantcast.com