Introduction

Base URL

https://{DomainAndOrg}/{ProductName}

What are the Savanta Data APIs?

Scroll down for code samples, and worked examples.

There are two different APIs available:

Calculated metrics API
Survey response API

These APIs are designed to be accessed from a program/service, so, rather than user login details, all requests must be sent with an API Key.

This Savanta Data Open API 3 spec may be useful in generating code to call these APIs, or integrating with other tools.

Calculated metrics API

Provides the calculated metric data that is used in Savanta dashboards. This data comes from survey responses that are aggregated and weighted.

This API is useful if you want to pull metrics from Savanta dashboards into your own reporting systems. For example, you may want to measure the effectiveness of offline marketing efforts. The metrics from this API can be used to measure whether your campaigns have an impact.

Survey response API

Provides all of the data, by individual respondents, from a survey and metadata to interpret the responses. It does not return results for calculated metrics seen in Savanta dashboards.

This API is useful if you want to do custom results aggregation; combining raw data from Savanta surveys with your own data sources to produce enriched analytics. It can also be used to present survey data in BI solutions. Data scientists can use this API to interrogate and investigate survey responses.

Authentication and authorization

You will need an API license and an API key before you can make any requests to the API.

API keys

Request - get available surveysets

GET /api/surveysets -H 'Authorization: Bearer {access-token}'

Example response

{
    "value": [
        {
            "surveysetId": "UK",
            "name": "UK"
        }
    ]
}

Getting an API key

Your Savanta account manager will be able to provide you with an API Key. You are responsible for any API access using your key and any data retrieved using your key is subject to our contractual licence with you. Please contact us immediately if there's a possibility the key has been accessed by an unauthorized party.

Using your API key

Your API key will need to be included in the Authorization header for every request.

Your API key is tied to your API license which determines the endpoints you can access and what data is available to you.

Revoking/reissuing an API key

Please contact your account manager or Savanta support if you need to revoke an API key. This can be done at any time and a new key provided to you. We will revoke any keys we suspect have been compromised - for example those that significantly exceed allowed API usage thresholds.

API licenses

Your API key is tied to your API license which determines the endpoints you can access and what data is available to you.

You may have either or both of the APIs (Survey response & Calculated metrics) available to you, depending on your API license. Access to specific API endpoints is restricted according to your license. Some API endpoints are available with any license, these typically are used to retrieve metadata necessary to interpret survey responses or describe calculated metrics.

Endpoints that are only available with the Calculated metrics API license will be marked like this in the documentation.

Calculated metrics API license required.

Endpoints that are only available with the Survey response API license will be marked like this in the documentation.

Survey response API license required.

Worked examples

See the right hand pane for concrete examples.

All parameters are case sensitive.
The order of response questions, and the contents of any arrays may change without warning.

Responses

Most endpoints return a json response, with the result nested within a value property.

The survey answers endpoints return a csv in order to reduce file size, and make it simpler to add directly into a database, see:

/api/surveysets/{surveyset}/profile/answers/{date}
/api/surveysets/{surveyset}/classes/{class}/answers/{date}

Discover what data is available

Request:

GET /api/surveysets/UK/classes

Response:

{
    "value": [
        {
            "classId": "brand",
            "name": "brand",
            "childClassIds": []
        },
        {
            "classId": "product",
            "name": "product",
            "childClassIds": [
                "brand"
            ]
        }
    ]
}

To explore the data available from the Survey Response API or Calculated Metrics API you will need to have a valid surveyset to use in your requests. If you want to download response or metric data then you will need to use a class and date with the surveyset.

To get classes & averages available for the UK surveyset

GET /api/surveysets
Returns a list of available surveysets.
A surveyset needs to be specified for all other API calls
GET /api/surveysets/UK
Returns the start and end dates of data for the UK surveyset.
You will need to request a date within the start and end dates to return data from the APIs
GET /api/surveysets/UK/classes
Returns a list of classes for the UK surveyset.
A class needs to be specified when calling the APIs
GET /api/surveysets/UK/averages
Returns a list of averages for the UK surveyset.
An average needs to be specified when requesting data from the APIs

Calculated metrics API examples

Calculated metrics API license required.

Get a brand metric for a chosen brand

Request:

GET /api/surveysets/UK/classes/brand/metrics/Net-Buzz/monthly?instanceId=1&startDate=2018-01-01&endDate=2018-12-31

Response:

EndDate,Value,SampleSize
2018-01-31,0.005001647,1173
2018-02-28,0.01277445,1146
2018-03-31,0.002071999,1156
2018-04-30,0.01358118,1186
2018-05-31,0.005597305,1147
2018-06-30,0.007488097,1124
2018-07-31,0.003319101,1270
2018-08-31,0.01332785,1192
2018-09-30,0.0103398,1204
2018-10-31,0.00704436,1145
2018-11-30,0.007060822,1146
2018-12-31,0.01834407,861

Metric data can be retrieved for any supported class and metric in a surveyset. When requesting metric data for a class you will need to specify an instance ID for the class as well as a supported average. Start and end dates for the date you want are also required.

The API will return responses in JSON format.

GET /api/surveysets/UK/averages
Returns a list of averages for the UK surveyset.
An average needs to be specified when requesting calculated metrics.
GET /api/surveysets/UK/classes/brand/metrics
Returns a list of available brand metrics for the UK surveyset.
A metric ID needs to be specified when requesting calculated metrics.
GET /api/surveysets/UK/classes/brand/instances
Returns a list of brands available for the UK surveyset. A brand instance ID is required when requesting calculated metrics.
GET /api/surveysets/UK/classes/brand/metrics/Net-Buzz/monthly ?instanceId=1&startDate=2018-01-01&endDate=2018-12-31
Returns Net Buzz monthly data, for 2018, for brand instance ID 1.

Get a profile metric

Request:

GET api/surveysets/UK/profile/metrics/Age/monthly?startDate=2018-01-01&endDate=2018-12-31

Response:

EndDate,Value,SampleSize
2018-01-31,0.005001647,1173
2018-02-28,0.01277445,1146
2018-03-31,0.002071999,1156
2018-04-30,0.01358118,1186
2018-05-31,0.005597305,1147
2018-06-30,0.007488097,1124
2018-07-31,0.003319101,1270
2018-08-31,0.01332785,1192
2018-09-30,0.0103398,1204
2018-10-31,0.00704436,1145
2018-11-30,0.007060822,1146
2018-12-31,0.01834407,861

Profiles are treated as a unique class in the APIs and do not need an instance ID. Profile metrics are about survey respondents e.g. age, gender and SEG. When requesting profile metrics you will need to specify a supported average. Start and end dates for the date you want are also required.

The API will return responses in JSON format.

GET /api/surveysets/UK/averages
Returns a list of averages for the UK surveyset.
An average needs to be specified when requesting calculated metrics.
GET /api/surveysets/UK/profile/metrics
Returns a list of available profile metrics for the UK surveyset.
A metric ID needs to be specified when requesting calculated metrics.
GET /api/surveysets/UK/profile/metrics/Age/monthly?startDate=2018-01-01&endDate=2018-12-31
Returns Age monthly data, for 2018.

Survey Response API examples

Survey response API license required.

Export the latest data

Survey answers can be obtained on a daily basis from the API. The most recent day you can request data for is always the latest complete day e.g. yesterday. You may want to retrieve data on a daily basis to push into your data warehouse, or feed into other BI systems, to provide an up-to-date view on the data.

The API will return survey answers as CSV files.

GET /api/surveysets/UK/profile/answers/2019-01-31
Returns a CSV file of the profile answers for the UK surveyset for the 31st January 2019.
Only needs to be called once each day.
GET /api/surveysets/UK/classes/brand/answers/2019-01-31[?includeText=true]
Returns a CSV file of the brand class answers for the UK surveyset for the 31st January 2019.
Only needs to be called once each day. includeText is optional (default false) and if set to true will also return any reponses for questions that allow free text.

Get weightings for an average period

Request:

GET /api/surveysets/UK/averages/monthly/weights/2019-01-31

Response:

{
    "value": [
        {
            "weightingCellId": 1,
            "multiplier": 0.6108187
        },
		...
  ]
}

Weightings are required if you want to reproduce values used in Savanta dashboards.
For example, to get weightings for UK surveyset for January 2019 data (i.e. Monthly average):

GET /api/surveysets/UK/averages
Returns a list of averages for the UK surveyset.
An average needs to be specified when calling the get weightings api.
GET /api/surveysets/UK/weightingCells
Returns a list of the weighting cell ids and associated profile questions used for the UK surveyset.
The weighting cell id is the key that links profile answers and weights.
GET /api/surveysets/UK/averages/monthly/weights/2019-01-31
Returns a list of the weights for the for the UK surveyset for monthly average for January 2019.

Advanced examples

Calculate 28 day weighted average for awareness metric

Collect metadata

Example: To retrieve start and end dates for a surveyset

GET /api/surveysets/UK

Response:

{
    "value": {
        "earliestResponseDate": "2017-05-17T00:00:00+00:00",
        "latestResponseDate": "2019-08-12T00:00:00+00:00"
    }
}

We need to call several endpoints to get the required metadata to calculate a weighted average.

GET /api/surveysets
Returns a list of available surveysets.
A surveyset needs to be specified for all other api calls
GET /api/surveysets/UK
Returns the start and end dates of data for the UK surveyset.
You will need to request a date within the start and end dates to return data from the API
GET /api/surveysets/UK/classes
Returns a list of classes for the UK surveyset.
A class needs to be specified when calling the responses API
GET /api/surveysets/UK/averages
Returns a list of averages for the UK surveyset.
An average needs to be specified when calling the get weightings api
GET /api/surveysets/UK/averages/28Days/weightings/2019-02-28
Returns a list of the weightings for the UK surveyset for the 28 Day average and end date 2019-02-28
GET /api/surveysets/UK/metrics Returns a list of available metrics for the UK surveyset.
Each metric includes additional data required to calculate a weighted average.

We now have a valid surveyset, date, class, average, weightings and metric for that average and date. Note in this example we are going to calculate a 28 day average and thus we can count back 28 days from the date we selected to get the data.

Downloading the data we need

Now we can call the profile and class answerset endpoints iteratively requesting data from the 2019-02-01 to 2019-02-28. Note that the weightings we apply to the data must match the range for the weightings.

In our example if we choose 2019-02-28 to request weightings and count back 28 days we get to 2019-02-01 so this is correct. Be careful with non daily averages See weights endpoint for more information.

GET /api/surveysets/UK/profile/answers/2019-02-01
Returns profile data by day in CSV format
GET /api/surveysets/UK/classes/brand/answers/2019-02-01
Returns class answerset data by day in CSV format

The data can now be concatenated together to form 28 days of profile data and 28 days of class answerset data. These two sets of data can be joined on Profile_Id (Profile_Id is a foreign key in class answers)

Next we can join the weightings data by weightingCellId (weightingCellId is a foreign key in profiles)

Calculating the result

Using the properties Filter.QuestionId and BaseFilter.QuestionId from metric Awareness we know which questions we are interested in. In this case it is Consumer_Segment for both.
Using the properties Filter.IncludeList and BaseFilter.IncludeList from metric Awareness we filter out results where the answer for the base filter's question is not in the list of BaseIncludeList and attribute the results contained in the main question as 1 if in the IncludeList list and 0 otherwise. We can do this because the calculation type for Awareness is YesNo which is a boolean.
Sum the attributed values of the Awareness metric multiplied by the scale factor for the weighting cell of the respondent.
Divide through by the sum of the scale factors for the entire surveyset for a weighted average.
A count of profile ids can also be taken for a sample size.

The data returned covers all brands. Use the instances endpoint to get the id of the brand you are interested in.

Downloading data to a CSV

Here is a sample powershell script WriteCsv-FromBrandVueApi.ps1 that creates a CSV for respondent and brand response data. The script requires 2 parameters:

baseUrl - your dashboard url
accessToken - your access token.

For analysis in excel you could join those csvs together on the profile id field using Join-Csvs.ps1 The script requires 2 parameters:

leftCsvPath - path to respondents csv.
rightCsvPath - path to responses csv.

Scripting metric calculation in a SQL database

Example SQL for 'Familiarty' metric for brand id 159

SELECT
  COUNT(ProfileId) AS SampleSize,
  SUM(ResponseMetricValue * ScaleFactor) / SUM(ScaleFactor) AS MetricResult
FROM (SELECT
  sr.ProfileId,
  CASE 
    WHEN Familiarity IN (1, 2, 3, 4) -- {desiredMetric.Filter.Name} in {desiredMetric.Filter.IncludeList}
    THEN 1 ELSE 0
  END AS ResponseMetricValue,
  ScaleFactor
FROM SurveyResponses AS sr
INNER JOIN SurveyRespondents AS srs
  ON sr.ProfileId = srs.ProfileId
INNER JOIN ScaleFactors AS sf
  ON sf.WeightingCellId = srs.WeightingCellId
WHERE BrandId = 159 -- {desiredBrand.BrandId}
AND ConsumerSegmentBrandAdvantage IN (1, 2, 3, 4) -- {desiredMetric.BaseFilter.QuestionId} in {desiredMetric.BaseFilter.IncludeList}
) AS d

Here is a sample powershell script that retrieves data from the API, creates a database schema and inserts some data into that schema. It has three dependencies that can be viewed and used individually. Please see powershell scripts for retrieving data from the API, creating a database schema and calculating the result. The script requires 3 parameters:

baseUrl - your dashboard url.
accessToken - your access token.
instanceName - an instance of sql server running in your machine.

The script currently fetches and inserts data for the metrics:

Consider with base filter ConsumerSegment
Familiarity with base filter ConsumerSegmentBrandAdvantage

From here we can calculate a weighted average for both Consider and Familiarity. For brevity the sample script doesn't store metric properties.

We have provided a sample SQL script on the right pane to calculate the sample size and weighted average from the collected data. In this example we have hardcoded the Filter.IncludeList and BaseFilter.IncludeList, but these should be obtained from the API and populated dynamically. Note that for the example Filter.IncludeList and BaseFilter.IncludeList for the metric Familiarity would have been [1, 2, 3, 4].

API Concepts

API model diagram

API model showing relationship between objects returned from endpoints within a surveyset

Survey definition

These endpoints are available with any license, they typically are used to retrieve metadata necessary to be used in further API calls to retrieve survey responses or calculated metrics.

Surveyset

Geographical examples:

UK (United Kingdom)

US (United States)

DE (Germany)

A surveyset contains responses to a common set of questions asked in a common context within a survey project. It's usually best to aggregate data within a surveyset first before comparing between surveysets. Many projects will only have a small number of surveysets, often only one.

Even if the questions are identical, the respondent's context can differ between surveysets. For example in a fashion survey project, the majority of men and women would be considering substantially different products - therefore UKWomen and UKMen would be separate surveysets for that survey project.

See /api/surveysets

Question

Range:
Min : 0
Max : 10

Listed answers:
-999: Don't know
1 : I have NEVER made a complaint
2 : I have made a complaint OVER A YEAR AGO

Question with checkbox:
-99 : Unchecked
1 : Checked

A question corresponds to a survey question. It includes the question text, and the defintition of all possible answers to the question. Answers are typically stored as a numeric value, either representing:

A direct numerical answer from an allowed range
An id matching a single-select listed answer
An id representing the selection status of an answer

For ids, negative numbers are usually used to represent special cases such as "don't know".

Each question has a name which acts as a unique identifier for reference within the surveyset.

/api/surveysets/{surveyset}/questions

Class

Common examples: Brand, Product

A class is a key focus area for the survey questions. For example: A respondent may be asked the same set of questions about several brands. The response will have a brand id associated with it. Each brand in this example is a class instance. Each class has its own set of questions - the ones asked within that class context.

Endpoint references:

/api/surveysets/{surveyset}/classes
/api/surveysets/{surveyset}/classes/{class}/instances

Metric results

Returns aggregated results for a metrics visible in the dashboard. If you require filtering or more advanced calculations, see Custom result aggregation.

Average type

Two different types of average are offered for results:

Daily rolling: One result per day.
- Weighting is applied over the entire average period.
Monthly fixed: One result per fixed period. Aligned to calendar months (monthly, quarterly, annual, etc).
- Each month is weighted independently.

Endpoint reference: /api/surveysets/{surveyset}/averages

Metric

A metric describes how to calculate a results seen in the dashboard by aggregating answers to 1 or 2 questions across all responses. For a percentage, the "baseFilter" determines the denominator and the "filter" determines the numerator.

List: [1, 2, 3, 4]

Range: { "Min": 18, "Max": 74 }

The filter and base filter can have several different value inclusion criteria:

List - This means "any of", and can be implemented with the SQL IN operator.
Range - This is an inclusive range and can be implemented with the SQL BETWEEN operator.
NotNull - Any non empty value. Assuming empty values were mapped to null, this can be implemented with a NOT NULL expression.

There are two types of metrics:

Class metric (e.g. Brand metric): The filter or base filter use a question linked to a defined class.
Profile metric: The filter and base filter only relate to questions asked with no defined class context.

MetricResult

Calculated metrics API license required.

MetricResult contents: EndDate: 2019-10-31 Value: 44.56578 SampleSize: 5015

The result of applying aggregating a metric over all responses within the requested time period. For percentage ("yn") metrics the value will be between 0 and 1. For class metrics, the figure is only for responses for that class instance. e.g. All responses for a specific brand. For profile metrics, the figure is for all responses.

Custom result aggregation

Survey response API license required.

For queries requiring custom segmentation, other data sources or filtering, you'll need to retrieve the survey answers. This offers complete flexibility, but requires a deeper understanding of the data. To ensure consistency with other results, we'd suggest first using this data to repdroduce a figure available from the dashboard / MetricResults API.

Profile

A profile represents a person's complete survey run-through. If the same person completes the survey next month they will get a new profile id. Each profile belongs to a weighting cell.

Answerset

An answerset is a Profile's answers for a set of questions. Each profile will only have answers for a subset of the questions in order to keep the survey to a manageable length.

Profile answerset

Profile answerset contents:

ProfileId: 346

Age: 36

How many times a month do you eat out at a restaurant?: 3

A profile answerset includes questions at the profile level. These help us to place the profile in a weighting cell as well as better understand their habits and preferences. Each profile is defined by exactly one profile response. Each profile response contains:

Weighting cell id
Survey start time
Answer mappings for profile questions

Endpoint reference: /api/surveysets/{surveyset}/profile/answers/{date}

Class answerset

Brand X class answerset contents:

ProfileId: 346

Brand: Brand X

Where did you last shop?: Brand X

On your last visit to Brand X, how much did you spend?: £36

These are class level questions and dig deeper into the respondents experience with a particular class instance. A respondent can be asked about more than one class instance in a survey. These are shown as a separate row in the response. Each class answerset contains:

Answer mappings for the class' questions.
Class id of the class instance.

Endpoint reference: /api/surveysets/{surveyset}/classes/{class}/answers/{date}

Weighting

When aggregating responses over time, to create the most population-accurate result BrandVue applies weighting.

Endpoint reference: /api/surveysets/{surveyset}/averages/{average}/weights/{date}

Weighting cell

Consider a time period where 10% of our survey respondents within a time period were Men aged 25-34.

If the population contained 15% Men aged 25-34, then they are underrepresented in the sample, and will be scaled up.

Respondents are classified into a weighting cell based on factors such as age, gender, location and socio-economic status (part of their profile answerset).

We aim to capture data from a nationally representative sample for each of these weighting cells, normalised over 7 day periods. However, inevitably there is some variation in each time window.

The BrandVue dashboard applies weighting during statistical analysis to counteract imperfections in sampling.

Endpoint reference: /api/surveysets/{surveyset}/weightingcells

Endpoint definitions

Choose your preferred programming language tab at the top (or the nav menu on mobile).

Base URL: https://{DomainAndOrg}/{ProductName}

DomainAndOrg - The same subdomain used to visit the BrandVue dashboard Default: demo.all-vue.com/finance
- {yourorg}.all-vue.com
- barometer.wgsn.com
ProductName - Product name - the first part of the path when visiting the BrandVue dashboard. Empty for barometer domain Default: finance
- charities
- eatingout
- finance

Rate limiting & thresholds

After receiving a 429 'too many requests' status code clients should wait 5 seconds before sending the next request.

This will generally only happen if the client:

Repeatedly requests large amounts of survey responses for the same dates - these should be cached/stored since they don't change
Repeatedly querying non-existent survey response dates - see the /api/surveysets/{surveyset} endpoint for which dates have data
Making many requests in parallel - there should be no need for this if caching responses appropriately

Some endpoints limit the maximum number of data points they return. In this case a 400 'bad request' status code will inform you of the limit. If this happens, make a more specific request that will return fewer data points.

Get Surveysets

GET /api/surveysets

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

The Id for a surveyset is required to use all other endpoints.

To request surveysets:

/api/surveysets

Return type: ApiResponse containing a list of SurveysetDescriptor

200 Response

{
  "value": [
    {
      "surveysetId": "string",
      "name": "string"
    }
  ]
}

Get Surveyset Detail

GET /api/surveysets/{surveyset}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Returns basic information about the specified surveyset. This includes the start and end dates of data collection.

Requesting only valid dates will speed up your automated process and help avoid rate limiting restrictions.

To request information for the UK surveyset:

/api/surveysets/UK

Return type: ApiResponse containing a SurveysetInfo instance

200 Response

{
  "value": {
    "earliestResponseDate": "2019-08-24T14:15:22Z",
    "latestResponseDate": "2019-08-24T14:15:22Z"
  }
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint

Get Averages

GET /api/surveysets/{surveyset}/averages

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Over time average types used in BrandVue - for use with the weights and metric results endpoints

Monthly averages larger than a month (e.g. yearly) are intentionally omitted since their weightings are applied on a monthly basis.

To request average types for UK surveyset:

/api/surveysets/UK/averages

Return type: ApiResponse containing a list of AverageDescriptor

200 Response

{
  "value": [
    {
      "averageId": "string",
      "name": "string"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint

Get Weightings

DEPRECATED

GET /api/surveysets/{surveyset}/averages/{average}/weightings/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weightings/{date} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weightings/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weightings/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weightings/{date}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weightings/{date}', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Demographic cell ids and weighting values for the period ending on {date}

Survey response API license required

Request to get weightings for 14 day average from 1st July till 14th July 2018: The weight of a respondent on the day they complete the survey may not match their weight at the end of the time period, as weightings change due to new respondents. Therefore, the last day of the period must be used for the weight of all respondents over the period:

/api/surveysets/UK/averages/14Days/weightings/2018-07-14

Request to get weightings for monthly average, for March 2018: Last day of the period can be used:

/api/surveysets/UK/averages/Monthly/weightings/2018-03-31

Alternate request to get weightings for monthly average, for March 2018: For a fixed monthly average, using any day in March will return the same results:

/api/surveysets/UK/averages/Monthly/weightings/2018-03-01

Return type: ApiResponse containing a list of DemographicCellWeighting

200 Response

{
  "value": [
    {
      "demographicCellId": 0,
      "multiplier": 0
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
average	path	AverageDescriptor	true	Valid averages for the requested surveyset. See the averages endpoint.
date	path	string(date-time)	true	Last day in average period being calculated in format yyyy-MM-dd. See the averages endpoint.

Get Weights

GET /api/surveysets/{surveyset}/averages/{average}/weights/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weights/{date} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weights/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weights/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weights/{date}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/averages/{average}/weights/{date}', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Weighting cell ids and weight values for the period ending on {date}

Survey response API license required

Request to get weightings for 14 day average from 1st July till 14th July 2018: The weight of a respondent on the day they complete the survey may not match their weight at the end of the time period, as weightings change due to new respondents. Therefore, the last day of the period must be used for the weight of all respondents over the period:

/api/surveysets/UK/averages/14Days/weights/2018-07-14

Request to get weights for monthly average, for March 2018: Last day of the period can be used:

/api/surveysets/UK/averages/Monthly/weights/2018-03-31

Alternate request to get weights for monthly average, for March 2018: For a fixed monthly average, using any day in March will return the same results:

/api/surveysets/UK/averages/Monthly/weights/2018-03-01

Return type: ApiResponse containing a list of Weight

200 Response

{
  "value": [
    {
      "weightingCellId": 0,
      "multiplier": 0
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
average	path	AverageDescriptor	true	Valid averages for the requested surveyset. See the averages endpoint.
date	path	string(date-time)	true	Last day in average period being calculated in format yyyy-MM-dd. See the averages endpoint.

Get Classes

GET /api/surveysets/{surveyset}/classes

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

*The list of classes that can be used with:

questions
instances
answers*

For many surveys you may see classes such as "brand" or "product" returned. More complex surveys may export multiple classes of data.

To request classes for UK:

/api/surveysets/UK/classes/

Return type: ApiResponse containing a list of ClassDescriptor

200 Response

{
  "value": [
    {
      "classId": "string",
      "name": "string",
      "childClassIds": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.

Get Class Answers

GET /api/surveysets/{surveyset}/classes/{class}/answers/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answers/{date}?includeText=false \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answers/{date}?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answers/{date}?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answers/{date}?includeText=false");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answers/{date}', params={
  'includeText': 'false'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Each row contains ProfileId, {class}Id and all questions for the specified {class}. See the questions endpoint for the names of those questions and what their values mean. Some values will be empty, this indicates that the respondent was not asked the question for the class instance on that row

Survey response API license required. Returns results in CSV format.

Request for brand level answers for the UK subset on 2019-02-01:

/api/surveysets/UK/classes/brand/answers/2019-02-01.

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example, UK, US, or DE. See surveysets endpoint.
class	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
date	path	string(date-time)	true	The date for the data in yyyy-MM-dd format
includeText	query	boolean	true	Include text responses

Get Class Answersets

DEPRECATED

GET /api/surveysets/{surveyset}/classes/{class}/answersets/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answersets/{date}?includeText=false \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answersets/{date}?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answersets/{date}?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answersets/{date}?includeText=false");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/answersets/{date}', params={
  'includeText': 'false'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

This is now deprecated. Use class answers instead.

Survey response API license required. Returns results in CSV format.

Request for brand level answersets for the UK subset on 2019-02-01:

/api/surveysets/UK/classes/brand/answersets/2019-02-01.

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example, UK, US, or DE. See surveysets endpoint.
class	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
date	path	string(date-time)	true	The date for the data in yyyy-MM-dd format
includeText	query	boolean	true	Include text responses

Get Class Instances

GET /api/surveysets/{surveyset}/classes/{class}/instances

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/instances \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/instances',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/instances',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/instances");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/instances', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Defines the meaning of values in the {class}Id column from the class answers endpoint

e.g. An id for each brand that can be returned.

To request brand instances:

/api/surveysets/UK/classes/brand/instances

Return type: ApiResponse containing a list of ClassInstanceDescriptor

200 Response

{
  "value": [
    {
      "classInstanceId": 0,
      "name": "string"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint
class	path	ClassDescriptor	true	Name of response class for which you want to retrieve instances. See the classes endpoint

Get Class Metrics

GET /api/surveysets/{surveyset}/classes/{class}/metrics

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Information required to calculated figures matching those in the BrandVue dashboard. Filtered by class.

Each metric's filter and base filter contain one of: FilterInfoList, FilterInfoRange or FilterInfoNotNull

To request metrics for UK surveyset in brand class:

/api/surveysets/UK/classes/brand/metrics

Return type: ApiResponse containing a list of MetricDescriptor

200 Response

{
  "value": [
    {
      "metricId": "string",
      "name": "string",
      "description": "string",
      "type": "string",
      "filter": {
        "includedValuesType": "Unknown",
        "questionId": "string",
        "questionClassIds": [
          "string"
        ]
      },
      "baseFilter": {
        "includedValuesType": "Unknown",
        "questionId": "string",
        "questionClassIds": [
          "string"
        ]
      },
      "startDate": "2019-08-24T14:15:22Z",
      "questionClasses": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
class	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.

Get Class Metric Results

DEPRECATED

GET /api/surveysets/{surveyset}/classes/{class}/metrics/{metric}/{average}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics/{metric}/{average}?instanceId=0&startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics/{metric}/{average}?instanceId=0&startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics/{metric}/{average}?instanceId=0&startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics/{metric}/{average}?instanceId=0&startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/metrics/{metric}/{average}', params={
  'instanceId': '0',  'startDate': '2019-08-24T14:15:22Z',  'endDate': '2019-08-24T14:15:22Z'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Returns the sample size and calculated metric by date for the parameters requested. These are the same figures BrandVue uses to plot charts.

This is now deprecated. Use Get Metric Results instead.

Calculated metrics API license required
This request has a response limit of 2500 data points. If more than 2500 points are requested then a 400 'bad request' status code will be returned.

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
class	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
metric	path	MetricDescriptor	true	Supported metric id. See the metrics endpoint.
average	path	AverageDescriptor	true	Valid averages for the requested surveyset. See the averages endpoint.
instanceId	query	integer(int32)	true	The instance id of the requested class. See the instances endpoint
startDate	query	string(date-time)	true	The start date for the calculation. This should fall within the earliest and latest response dates of the surveyset. See the surveyset detail endpoint.
endDate	query	string(date-time)	true	The endpoint for the calculation. This should fall within the earliest and latest response dates of the surveyset. See the surveyset detail endpoint.

Get Class Questions

DEPRECATED

GET /api/surveysets/{surveyset}/classes/{class}/questions

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/questions?includeText=false \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/questions?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/questions?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/questions?includeText=false");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{class}/questions', params={
  'includeText': 'false'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Defines the column names (and meaning of the values) returned from the class answersets endpoint. Question names are also used in the response of the class metrics endpoint as part of the filter and base filter.

This is now deprecated. Use questions. instead.

To request a list of brand questions for the UK surveyset:

/api/surveysets/UK/classes/brand/questions

Return type: ApiResponse containing a list of QuestionDescriptor

200 Response

{
  "value": [
    {
      "questionId": "string",
      "questionText": "string",
      "answerSpec": {
        "answerType": "Value"
      },
      "classes": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint
class	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
includeText	query	boolean	true	Include questions that may have text responses

Get Nested Class Answers

GET /api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answers/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answers/{date}?includeText=false \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answers/{date}?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answers/{date}?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answers/{date}?includeText=false");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answers/{date}', params={
  'includeText': 'false'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Each row contains the product id and all fields and questions for the specified {class}. It is important that the product class is the first level of class in the url. See the questions endpoint for the names of those questions and what their values mean. Some values will be empty, this indicates that the respondent was not asked the question for the class instance on that row

Survey response API license required. Returns results in CSV format.

Request for product brand level answers for the UK subset on 2019-02-01:

/api/surveysets/UK/classes/product/classes/brand/answers/2019-02-01.

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
parentClass	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
childClass	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
date	path	string(date-time)	true	The date for the data in yyyy-MM-dd format
includeText	query	boolean	true	Include text responses

Get Nested Class Answersets

DEPRECATED

GET /api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answersets/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answersets/{date}?includeText=false \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answersets/{date}?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answersets/{date}?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answersets/{date}?includeText=false");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/answersets/{date}', params={
  'includeText': 'false'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

This is now deprecated. Use nested class answers instead.

Survey response API license required. Returns results in CSV format.

Request for product brand level answersets for the UK subset on 2019-02-01:

/api/surveysets/UK/classes/product/classes/brand/answersets/2019-02-01.

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
parentClass	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
childClass	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
date	path	string(date-time)	true	The date for the data in yyyy-MM-dd format
includeText	query	boolean	true	Include text responses

Get Nested Class Metrics

GET /api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/metrics

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/metrics \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/metrics',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/metrics',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/metrics");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/metrics', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Information required to calculated figures matching those in the BrandVue dashboard. This endpoint supports nested classes.

Each metric's filter and base filter contain one of: FilterInfoList, FilterInfoRange or FilterInfoNotNull

To request metrics for UK surveyset in brand class:

/api/surveysets/UK/classes/product/classes/brand/metrics

Return type: ApiResponse containing a list of MetricDescriptor

200 Response

{
  "value": [
    {
      "metricId": "string",
      "name": "string",
      "description": "string",
      "type": "string",
      "filter": {
        "includedValuesType": "Unknown",
        "questionId": "string",
        "questionClassIds": [
          "string"
        ]
      },
      "baseFilter": {
        "includedValuesType": "Unknown",
        "questionId": "string",
        "questionClassIds": [
          "string"
        ]
      },
      "startDate": "2019-08-24T14:15:22Z",
      "questionClasses": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
parentClass	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
childClass	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.

Get Nested Class Questions

DEPRECATED

GET /api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/questions

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/questions?includeText=false \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/questions?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/questions?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/questions?includeText=false");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/classes/{parentClass}/classes/{childClass}/questions', params={
  'includeText': 'false'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Defines the column names (and meaning of the values) returned from the nested answersets endpoint. Question names are also used in the response of the nested class metrics endpoint as part of the filter and base filter.

This is now deprecated. Use questions instead.

To request a list of product brand questions for the UK surveyset:

/api/surveysets/UK/classes/product/classes/brand/questions

Return type: ApiResponse containing a list of QuestionDescriptor

200 Response

{
  "value": [
    {
      "questionId": "string",
      "questionText": "string",
      "answerSpec": {
        "answerType": "Value"
      },
      "classes": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint
parentClass	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
childClass	path	ClassDescriptor	true	Supported class. For example brand. See the classes endpoint.
includeText	query	boolean	true	Include questions that may have text responses

Get Demographic Cells

DEPRECATED

GET /api/surveysets/{surveyset}/demographiccells

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/demographiccells \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/demographiccells',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/demographiccells',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/demographiccells");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/demographiccells', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

The id within the returned demographic cells correspond to the demographicCellId in a profile response. The other information is for descriptive purposes.

This is now deprecated. Use weighting cells instead.

Survey response API license required

To request demographic info for the UK subset:

/api/surveysets/UK/demographiccells

Return type: ApiResponse containing a list of DemographicCellDescriptor

200 Response

{
  "value": [
    {
      "demographicCellId": 0,
      "region": "string",
      "gender": "string",
      "ageGroup": "string",
      "socioEconomicGroupIndicator": "string"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.

Get Metrics

GET /api/surveysets/{surveyset}/metrics

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Information required to calculated figures matching those in the BrandVue dashboard.

Each metric's filter and base filter contain one of: FilterInfoList, FilterInfoRange or FilterInfoNotNull

To request metrics for UK surveyset:

/api/surveysets/UK/metrics

Return type: ApiResponse containing a list of MetricDescriptor

200 Response

{
  "value": [
    {
      "metricId": "string",
      "name": "string",
      "description": "string",
      "type": "string",
      "filter": {
        "includedValuesType": "Unknown",
        "questionId": "string",
        "questionClassIds": [
          "string"
        ]
      },
      "baseFilter": {
        "includedValuesType": "Unknown",
        "questionId": "string",
        "questionClassIds": [
          "string"
        ]
      },
      "startDate": "2019-08-24T14:15:22Z",
      "questionClasses": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.

Get Metric Results

POST /api/surveysets/{surveyset}/metrics/{metric}/{average}

Code samples

# You can also use wget
curl -X POST https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics/{metric}/{average} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'

const inputBody = '{
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "classInstances": {
    "property1": [
      0
    ],
    "property2": [
      0
    ]
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics/{metric}/{average}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');
const inputBody = {
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "classInstances": {
    "property1": [
      0
    ],
    "property2": [
      0
    ]
  }
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics/{metric}/{average}',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics/{metric}/{average}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.post('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/metrics/{metric}/{average}', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Body parameter

{
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "classInstances": {
    "property1": [
      0
    ],
    "property2": [
      0
    ]
  }
}

Returns the sample size and calculated metric by date for the parameters requested. These are the same figures BrandVue uses to plot charts.

Calculated metrics API license required. Returns results in CSV format.
This request has a response limit of 2500 data points. If more than 2500 points are requested then a 400 'bad request' status code will be returned.

Request for a brand only metric for instance ids 1,2 and 3 in the UK subset for 2019 by month:

/api/surveysets/UK/metrics/positive-buzz/Monthly

With Body

{
    "StartDate" : "2019-01-01",
    "EndDate": "2019-12-31",
    "ClassInstances" : {
        "brand": [1,2,3]
    }
}

Request a 7 day average for a profile metric in the UK subset for December 2019:

/api/surveysets/UK/metrics/age/7Days

With Body

{
    "StartDate" : "2019-12-01",
    "EndDate": "2019-12-31"
}

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
metric	path	MetricDescriptor	true	Supported metric id. See the metrics endpoint.
average	path	AverageDescriptor	true	Valid averages for the requested surveyset. See the averages endpoint.
body	body	MetricCalculationRequest	true	Body of the request. This contains request dates and the instances to calculate the results for.

Get Profile Answers

GET /api/surveysets/{surveyset}/profile/answers/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answers/{date} \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answers/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answers/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answers/{date}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answers/{date}', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Each row contains ProfileId, Demographic_Cell_Id and all profile questions. See the questions for the names of those questions and what their values mean. Some values will be empty, this indicates that the respondent was not asked the question. A Demographic_Cell_Id value of -1 means that no weighting is available

Survey response API license required. Returns results in CSV format.

Request for UK subset on 2019-02-01:

/api/surveysets/UK/profile/2019-02-01

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
date	path	string(date-time)	true	The date for the data in yyyy-MM-dd format

Get Profile Answersets

DEPRECATED

GET /api/surveysets/{surveyset}/profile/answersets/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answersets/{date} \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answersets/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answersets/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answersets/{date}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/answersets/{date}', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Each row contains ProfileId, DemographicCellId and all profile questions. See the questions for the names of those questions and what their values mean. Some values will be empty, this indicates that the respondent was not asked the question.

This is now deprecated. Use profile answers instead.

Survey response API license required. Returns results in CSV format.

Request for UK subset on 2019-02-01:

/api/surveysets/UK/profile/2019-02-01

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
date	path	string(date-time)	true	The date for the data in yyyy-MM-dd format

Get Profile Metrics

GET /api/surveysets/{surveyset}/profile/metrics

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Information required to calculated figures matching those in the BrandVue dashboard. These are the profile metrics.

Each metric's filter and base filter contain one of: FilterInfoList, FilterInfoRange or FilterInfoNotNull

To request profile metrics for UK surveyset:

/api/surveysets/UK/profile/metrics

Return type: ApiResponse containing a list of MetricDescriptor

200 Response

{
  "value": [
    {
      "metricId": "string",
      "name": "string",
      "description": "string",
      "type": "string",
      "filter": {
        "includedValuesType": "Unknown",
        "questionId": "string",
        "questionClassIds": [
          "string"
        ]
      },
      "baseFilter": {
        "includedValuesType": "Unknown",
        "questionId": "string",
        "questionClassIds": [
          "string"
        ]
      },
      "startDate": "2019-08-24T14:15:22Z",
      "questionClasses": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.

Get Profile Metric Results

DEPRECATED

GET /api/surveysets/{surveyset}/profile/metrics/{metric}/{average}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics/{metric}/{average}?startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics/{metric}/{average}?startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics/{metric}/{average}?startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics/{metric}/{average}?startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/metrics/{metric}/{average}', params={
  'startDate': '2019-08-24T14:15:22Z',  'endDate': '2019-08-24T14:15:22Z'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Returns the sample size and calculated metric by date for the parameters requested. These are the same figures BrandVue uses to plot charts.

This is now deprecated. Use Get Metric Results instead.

Calculated metrics API license required
This request has a response limit of 2500 data points. If more than 2500 points are requested then a 400 'bad request' status code will be returned.

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.
metric	path	MetricDescriptor	true	Supported metric id. See the profile metrics endpoint.
average	path	AverageDescriptor	true	Valid averages for the requested surveyset. See the averages endpoint.
startDate	query	string(date-time)	true	The start date for the calculation. This should fall within the earliest and latest response dates of the surveyset. See the surveyset detail endpoint.
endDate	query	string(date-time)	true	The endpoint for the calculation. This should fall within the earliest and latest response dates of the surveyset. See the surveyset detail endpoint.

Get Profile Questions

DEPRECATED

GET /api/surveysets/{surveyset}/profile/questions

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/questions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/questions',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/questions',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/questions");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/profile/questions', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

These question names are used as column names in the data provided from the profile answersets endpoint. They also relate to the metric properties QuestionName and BaseQuestionName

This is now deprecated. Use questions. instead.

To request profile questions for the UK surveyset:

/api/surveysets/UK/profile/questions

Return type: ApiResponse containing a list of QuestionDescriptor

200 Response

{
  "value": [
    {
      "questionId": "string",
      "questionText": "string",
      "answerSpec": {
        "answerType": "Value"
      },
      "classes": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint

Get Questions

GET /api/surveysets/{surveyset}/questions

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/questions?includeText=false \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/questions?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/questions?includeText=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/questions?includeText=false");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/questions', params={
  'includeText': 'false'
}, headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Defines the column names (and meaning of the values) returned from the answers endpoint. Question names are also used in the response of the metrics endpoint as part of the filter and base filter.

To request a list of questions for the UK surveyset:

/api/surveysets/UK/questions

Return type: ApiResponse containing a list of QuestionDescriptor

200 Response

{
  "value": [
    {
      "questionId": "string",
      "questionText": "string",
      "answerSpec": {
        "answerType": "Value"
      },
      "classes": [
        "string"
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint
includeText	query	boolean	true	Include questions that may have text responses

Get Variable Answers

GET /api/surveysets/{surveyset}/variables/{variable}/answers/{date}

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/variables/{variable}/answers/{date} \
  -H 'Accept: application/octet-stream' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/variables/{variable}/answers/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/octet-stream',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/variables/{variable}/answers/{date}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/variables/{variable}/answers/{date}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/octet-stream',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/variables/{variable}/answers/{date}', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

Each row contains ProfileId and the {class}_Id(s) for the variable See the class answers endpoint for the names and values

Survey response API license required. Returns results in CSV format.

Variable level answers request for "namedVariable" within the UK subset on 2019-02-01:

/api/surveysets/UK/variables/namedvariable/answers/2019-02-01.

Return type: string

200 Response

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example, UK, US, or DE. See surveysets endpoint.
variable	path	VariableDescriptor	true	Variable. See [metrics]{#get-metrics) endpoint for the name to use
date	path	string(date-time)	true	The date for the data in yyyy-MM-dd format

Get Weighting Cells

GET /api/surveysets/{surveyset}/weightingcells

Code samples

# You can also use wget
curl -X GET https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/weightingcells \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YourApiKey'


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/weightingcells',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer YourApiKey'
};

fetch('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/weightingcells',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/weightingcells");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YourApiKey'
}

r = requests.get('https://{DomainAndOrg}/{ProductName}/api/surveysets/{surveyset}/weightingcells', headers = headers)

print('Response code: ' + str(r.status_code))
print(r.text)

The id within the returned weighting cells correspond to the weightingCellId in a profile response. The other information is for descriptive purposes.

Survey response API license required

To request weighting info for the UK subset:

/api/surveysets/UK/weightingcells

Return type: ApiResponse containing a list of WeightingCellDescriptor

200 Response

{
  "value": [
    {
      "weightingCellId": 0,
      "cellPartDescriptions": {
        "property1": "string",
        "property2": "string"
      },
      "isWeighted": true
    }
  ]
}

Parameters

Name	In	Type	Required	Description
surveyset	path	SurveysetDescriptor	true	Supported surveyset ID. For example: UK, US or DE. See the surveysets endpoint.

Response object definitions

Status and error codes

The API uses the following HTTP status codes:

Status Code	Message	Meaning
200	OK	Successful request and response
400	Bad request	Malformed parameters or other bad request. Your request is invalid
401	Unauthorised	API key is invalid. Authorization has been denied for this request
403	Forbidden	Not authorized to access this resource
404	Resource not found	The specified resource could not be found
405	Method not allowed	You are using an incorrect HTTP verb
406	Not acceptable	You requested an unsupported format, try json or csv instead
429	Too many Requests	See rate limiting for further information
500	Internal server error	We had a problem with our server. Please try again later
503	Service unavailable	We're temporarily offline for maintenance. Please try again later

ApiResponse

{
  "value": "object"
}

Properties

Name	Type	Required	Restrictions	Description
value	object	false	none	An object that has been wrapped by this response object

SurveysetDescriptor

{
  "surveysetId": "string",
  "name": "string"
}

Properties

Name	Type	Required	Restrictions	Description
surveysetId	string	false	none	Surveyset id - used as the surveyset identifier for calls to other API endpoints
name	string	false	none	Surveyset name - a description of the surveyset. Often but not always the same as the surveyset id.

ClassDescriptor

{
  "classId": "string",
  "name": "string",
  "childClassIds": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
classId	string	false	none	Class id - used as the class identifier for calls to other API endpoints
name	string	false	none	Class name - The name of the class. Often but not always the same as the class id.
childClassIds	[string]	false	none	Child class id's - A list of other class id's nested under this class.

VariableDescriptor

{
  "variableIdentifier": "string",
  "displayName": "string"
}

Properties

Name	Type	Required	Restrictions	Description
variableIdentifier	string	false	none	Variable id - used as the variable identifier for calls to other API endpoints
displayName	string	false	none	Variable display name - The display name for the variable

AverageDescriptor

{
  "averageId": "string",
  "name": "string"
}

Properties

Name	Type	Required	Restrictions	Description
averageId	string	false	none	The id of the average
name	string	false	none	The name of the average

DemographicCellWeighting

DEPRECATED (Please use the weights endpoint)

{
  "demographicCellId": 0,
  "multiplier": 0
}

Properties

Name	Type	Required	Restrictions	Description
demographicCellId	integer(int32)	false	none	none
multiplier	number(float)	false	none	none

Weight

{
  "weightingCellId": 0,
  "multiplier": 0
}

The lookup of identifiers to weightings

Properties

Name	Type	Required	Restrictions	Description
weightingCellId	integer(int32)	false	none	The id of the weighting cell
multiplier	number(float)	false	none	The multiplier to apply to responses to get the correct weighted averages

ClassInstanceDescriptor

{
  "classInstanceId": 0,
  "name": "string"
}

Properties

Name	Type	Required	Restrictions	Description
classInstanceId	integer(int32)	false	none	The id of the class instance
name	string	false	none	The name of the class instance

DemographicCellDescriptor

DEPRECATED (UseWeightingCellDescriptor)

{
  "demographicCellId": 0,
  "region": "string",
  "gender": "string",
  "ageGroup": "string",
  "socioEconomicGroupIndicator": "string"
}

The lookup of identifiers to demographic cell parts

Properties

Name	Type	Required	Restrictions	Description
demographicCellId	integer(int32)	false	none	The id of the demographic cell
region	string	false	none	The region of the descriptor
gender	string	false	none	The gender of the descriptor
ageGroup	string	false	none	The age group of the descriptor
socioEconomicGroupIndicator	string	false	none	The socioeconomic group of the descriptor

MetricDescriptor

{
  "metricId": "string",
  "name": "string",
  "description": "string",
  "type": "string",
  "filter": {
    "includedValuesType": "Unknown",
    "questionId": "string",
    "questionClassIds": [
      "string"
    ]
  },
  "baseFilter": {
    "includedValuesType": "Unknown",
    "questionId": "string",
    "questionClassIds": [
      "string"
    ]
  },
  "startDate": "2019-08-24T14:15:22Z",
  "questionClasses": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
metricId	string	false	none	The id of the metric
name	string	false	none	The name of the metric
description	string	false	none	none
type	string	false	none	The type of the metric. This will be a class id.
filter	FilterInfo	false	none	The filter for the metric
baseFilter	FilterInfo	false	none	The base filter for the metric
startDate	string(date-time)¦null	false	none	The start date for the metric
questionClasses	[string]	false	none	The classes for this metric

FilterInfo

{
  "includedValuesType": "Unknown",
  "questionId": "string",
  "questionClassIds": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
includedValuesType	IncludedValuesTypeEnum	false	none	none
questionId	string	false	none	none
questionClassIds	[string]	false	none	none

IncludedValuesTypeEnum

"Unknown"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated Values

Property	Value
anonymous	Unknown
anonymous	List
anonymous	Range
anonymous	NotNull

FilterInfoList

{
  "includedValuesType": "Unknown",
  "questionId": "string",
  "questionClassIds": [
    "string"
  ],
  "includeList": [
    0
  ]
}

Properties

Name	Type	Required	Restrictions	Description
includedValuesType	IncludedValuesTypeEnum	false	none	none
questionId	string	false	none	none
questionClassIds	[string]	false	none	none
includeList	[integer]	false	none	none

FilterInfoRange

{
  "includedValuesType": "Unknown",
  "questionId": "string",
  "questionClassIds": [
    "string"
  ],
  "min": 0,
  "max": 0
}

Properties

Name	Type	Required	Restrictions	Description
includedValuesType	IncludedValuesTypeEnum	false	none	none
questionId	string	false	none	none
questionClassIds	[string]	false	none	none
min	integer(int32)	false	none	none
max	integer(int32)	false	none	none

FilterInfoUnknown

{
  "includedValuesType": "Unknown",
  "questionId": "string",
  "questionClassIds": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
includedValuesType	IncludedValuesTypeEnum	false	none	none
questionId	string	false	none	none
questionClassIds	[string]	false	none	none

FilterInfoNotNull

{
  "includedValuesType": "Unknown",
  "questionId": "string",
  "questionClassIds": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
includedValuesType	IncludedValuesTypeEnum	false	none	none
questionId	string	false	none	none
questionClassIds	[string]	false	none	none

MetricCalculationRequest

{
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "classInstances": {
    "property1": [
      0
    ],
    "property2": [
      0
    ]
  }
}

Properties

Name	Type	Required	Restrictions	Description
startDate	string(date-time)¦null	false	none	none
endDate	string(date-time)¦null	false	none	none
classInstances	object	false	none	none
» additionalProperties	[integer]	false	none	none

QuestionDescriptor

{
  "questionId": "string",
  "questionText": "string",
  "answerSpec": {
    "answerType": "Value"
  },
  "classes": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
questionId	string	false	none	none
questionText	string	false	none	none
answerSpec	QuestionAnswer	false	none	none
classes	[string]	false	none	none

QuestionAnswer

{
  "answerType": "Value"
}

Properties

Name	Type	Required	Restrictions	Description
answerType	AnswerTypeEnum	false	none	none

AnswerTypeEnum

"Value"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated Values

Property	Value
anonymous	Value
anonymous	Text
anonymous	Category
anonymous	Unknown

QuestionValueAnswer

{
  "answerType": "Value",
  "minValue": 0,
  "maxValue": 0,
  "multiplier": 0
}

Properties

Name	Type	Required	Restrictions	Description
answerType	AnswerTypeEnum	false	none	none
minValue	integer	false	none	Deprecated
maxValue	integer	false	none	Deprecated
multiplier	number(float)	false	none	none

QuestionTextAnswer

{
  "answerType": "Value"
}

Properties

Name	Type	Required	Restrictions	Description
answerType	AnswerTypeEnum	false	none	none

QuestionMultipleChoiceAnswer

{
  "answerType": "Value",
  "choices": [
    {
      "id": "string",
      "value": "string"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
answerType	AnswerTypeEnum	false	none	none
choices	[QuestionChoice]	false	none	none

QuestionChoice

{
  "id": "string",
  "value": "string"
}

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	none
value	string	false	none	none

QuestionUnknownAnswerType

{
  "answerType": "Value"
}

Properties

Name	Type	Required	Restrictions	Description
answerType	AnswerTypeEnum	false	none	none

SurveysetInfo

{
  "earliestResponseDate": "2019-08-24T14:15:22Z",
  "latestResponseDate": "2019-08-24T14:15:22Z"
}

Properties

Name	Type	Required	Restrictions	Description
earliestResponseDate	string(date-time)	false	none	Date of the earliest survey response available.
latestResponseDate	string(date-time)	false	none	Date of the latest survey response available.

WeightingCellDescriptor

{
  "weightingCellId": 0,
  "cellPartDescriptions": {
    "property1": "string",
    "property2": "string"
  },
  "isWeighted": true
}

The lookup of identifiers to weighted cell parts

Properties

Name	Type	Required	Restrictions	Description
weightingCellId	integer(int32)	false	none	The id of the weighting cell
cellPartDescriptions	object	false	none	The descriptions of the parts of the weighted cell
» additionalProperties	string	false	none	none
isWeighted	boolean	false	none	Indicates if the cell is weighted

undefined