validated Campaign Essentials Audience Report Data API
This API is the programming interface to the comScore AdEffx validated Campaign Essentials Audience report data. You can use the API to integrate this data directly into your dashboards or systems.
The vCE Audience Report Data API currently provides read-only access to reporting data. All API calls require authentication credentials, which can be obtained from your Client Service representative.
Quota
Applications are limited to a courtesy usage quota.
Authentication
All API calls require authentication credentials. AdEffx uses basic authentication over SSL to allow authorized clients to access their data. For access, contact your client service representative.
The vCE Audience Report Data API uses Basic Http authentication and SSL. The API can be accessed using valid AdEffx credentials (the same credentials used to access the AdEffx site) using Basic HTTP authentication through SSL. To use the service, you need:
- Valid AdEffx user credentials
- API access
- SSL connection
- Basic Http authentication headers using the AdEffx credentials
POST /private/index.html HTTP/1.1
Host: localhost
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
API Documentation
vCE Audience Report Data API v2.0 ReferenceAPI Calls
Most of the vCE Audience Report Data API follows a RESTful API design, meaning that you can use standard HTTP methods to retrieve and manipulate resources. For example, to see a list of studies permissioned to your account, you might send a HTTP request like:
POST https://user:password@adeffx-api.comscore.com/vCE/v2.0/Report/GetStudies.json
Different API methods require parameters to be passed either as part of the URI path or as query parameters.
To see a full list of report API endpoints, see API Documentation
Data Formats
Resources in the vCE Audience Report Data API are represented using either JSON or XML formats. The URI resource requires an extension of either “.json” or “.xml”. For example, retrieving a list of studies might look like:
POST https://user:password@adeffx-api.comscore.com/vCE/v2.0/Report/GetStudies.json
{
"Input": {
"Start": null,
"Limit": null,
"EndPoint": "/vce/v2.0/Report/GetStudies.json",
"Format": "json",
"Version": "v2.0"
},
"Data": {
"TotalStudies": 4,
"Studies": [
{
"StudyId": 27288,
"StudyName": "Anything Dressing | Q2 2013",
"StartDate": "2013-07-01",
"EndDate": "2013-08-31",
"DataThrough": "2013-08-27",
"PopulationId": 840,
"CountryName": "United States",
"TargetTypes": [
{
"TargetName": "Primary",
"TargetComponents": [
{
"DemographicId": 3,
"DemographicName": "Females - Age",
"DemographicMemberId": 114,
"DemographicMemberName": "Females: 25-34"
},
{
"DemographicId": 3,
"DemographicName": "Females - Age",
"DemographicMemberId": 115,
"DemographicMemberName": "Females: 35-44"
},
{
"DemographicId": 3,
"DemographicName": "Females - Age",
"DemographicMemberId": 116,
"DemographicMemberName": "Females: 45-49"
},
{
"DemographicId": 3,
"DemographicName": "Females - Age",
"DemographicMemberId": 117,
"DemographicMemberName": "Females: 50-54"
}
]
}
],
"Groups": {
"Placement": {
"SubGroup": [
{
"Name": "Publishers",
"List": [
{
"PlacementGroupId": 59,
"Name": "ABC.COM"
},
{
"PlacementGroupId": 534381,
"Name": "AOL, Inc."
}
]
},
{
"Name": "Strategies",
"List": []
}
]
},
"Creative": {
"SubGroup": [
{
"Name": "Strategies",
"List": []
},
{
"Name": "Sizes",
"List": [
{
"CreativeGroupId": 43,
"Name": "0 x 0"
},
{
"CreativeGroupId": 38,
"Name": "1 x 1"
},
{
"CreativeGroupId": 28,
"Name": "160 x 600"
}
]
},
{
"Name": "Formats",
"List": [
{
"CreativeGroupId": 5,
"Name": "Banners and Buttons"
},
{
"CreativeGroupId": 420,
"Name": "Non-Standard"
}
]
},
{
"Name": "Types",
"List": [
{
"CreativeGroupId": 552791,
"Name": "BANNER CREATIVE"
},
{
"CreativeGroupId": 46,
"Name": "CUSTOM"
},
{
"CreativeGroupId": 42,
"Name": "EXPANDABLE"
},
{
"CreativeGroupId": 2,
"Name": "FLASH IN-PAGE"
}
]
}
]
}
},
"Campaigns": [
{
"ClientId": "15078573",
"CampaignId": "13945"
},
{
"ClientId": "15078573",
"CampaignId": "50931"
}
]
}
}
]
}
]
}
Errors
The REST API will return standard HTTP status codes for requests (200 Successful, 404 Not Found, 500 Error). Application errors and warnings will be returned in an “Errors” section of each response. For example, a missing required parameter might look like:
{
"Errors": [
{
"ErrorCode": "InvalidParameter",
"Message": "Invalid parameter: PopulationId"
}
]
}
The following is a list of Error Codes returned by the API:
| Error Code | Description |
|---|---|
| UnknownError | Error Unknown |
| InvalidParameter | Parameter Not Valid. Could be a non-existent parameter or a value not allowed |
| UrlNotFound | URL Not Valid. Could be a non existing URL or a parameter not allowed |
| NotAuthorized | Access not authorized for the requested resource |
| NotAuthorizedForThisInput | Access not authorized to send an input |
| ConcurrentRequestsExceeded | Requests per minute Exceeded |
| StudyNotAvailable | Study not available to your account |
| ReportNotAvailable | Report not available to this study |
| NotAuthorizedForThisInput | You don't have permissions to send this input |
| RequestLimitExceeded | Request per Minute Exceeded (max = 120) |
| StudyNotAvailaible | Access to not availale study |
| ReportNotAvailable | Access to not available report |
| NotAuthorizedForThisInput | You dont have permissions to send this input |
| ConcurrentRequestsExceeded | Concurrent requests exceeded (max = defined max) |
Minimum Reporting Standards and Not Available Measures
Minimum Reporting Standards (MRS) rules apply to all report data. If a particular measure does not meet MRS or data is not available at that level of granularity (e.g. TRPs for certain target groups), then a value of NULL will be returned for that measure.
Polling for Updated Report Data
Report data is updated once per day. New data can be detected by identifying a change to the DataThrough field in the DataThrough endpoint for each study. Polling the List endpoint every 15 minutes is recommended for triggering the retrieval of new report data.
Examples
Json
C# (Download)
Stream dataStream;
//Creating Url
var queryStringUtil = new QueryStringUtil();
string url = BaseUrl + urlSuffix + "." + responseType;
//Setting http request
var request = (HttpWebRequest)HttpWebRequest.Create(url);
//Adding Http Basic authentication header
string username = "username";
string password = "password";
string usernamePassword = username + ":" + password;
CredentialCache mycache = new CredentialCache();
mycache.Add(new Uri(url), "Basic", new NetworkCredential(username, password));
request.Credentials = mycache;
request.Headers.Add("Authorization", "Basic " + Convert.ToBase64String(new ASCIIEncoding().GetBytes(usernamePassword)));
request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
if (urlParams.Any())
{
byte[] byteArray = Encoding.UTF8.GetBytes(queryStringUtil.DictionaryToQueryString(urlParams));
request.ContentLength = byteArray.Length;
dataStream = request.GetRequestStream();
dataStream.Write(byteArray, 0, byteArray.Length);
dataStream.Close();
}
//Getting Response
HttpWebResponse httpWebResponse = null;
try
{
httpWebResponse = (HttpWebResponse)request.GetResponse();
}
catch (WebException we)
{
string responseBody = "";
try
{
using (var reader = new StreamReader(we.Response.GetResponseStream()))
{
responseBody = reader.ReadToEnd();
}
}
catch (Exception) { }
Assert.Fail("WebException thrown for url: {0}; Exception message: {1}; Response body: {2}", url, we.Message, responseBody);
}
//Validating Encoding
if (httpWebResponse.CharacterSet != "utf-8")
throw new Exception(string.Format("Rest request [{0}] came back as encoding other than utf-8", url));
var resp = new RestTestResponse() { HttpWebResponse = httpWebResponse };
using (var reader = new StreamReader(httpWebResponse.GetResponseStream(), Encoding.UTF8))
{
resp.ResponseString = reader.ReadToEnd();
}
CheckStatusCode(resp);
//Deserializing object
MemoryStream ms = new MemoryStream(Encoding.Unicode.GetBytes(resp.ResponseString));
DataContractJsonSerializer serialiser = new DataContractJsonSerializer(typeof(Response));
var json = serialiser.ReadObject(ms);
//Closing Strem reader
ms.Close();