There's a few API endpoints to help you fetch recorded video or audio Responses and their transcripts and translations. Each of those endpoints provides you with full control to decide which fields you would like to be returned, as well as filtering options to specify exactly which Responses you want to fetch, if you're fetching multiple.
Fetching Responses and Transcriptions
As each Response is stored against a Project, and each Project is stored against an Account (see API Structure), we allow you to fetch an individual Response by its ID, or all Responses against a Project, or all Responses stored against an Account.
The sample cURL request below will fetch all Responses for a given Project, but will only return Response ID, it's transcripts if there's multiple languages, and any Additional Data on the Response.
Please note that Questions and Projects in our APIs mean the same thing.
curl --location --request GET 'https://developer.voxpopme.com/v2/question/{questionId}/responses?returnFields[]=id&returnFields[]=transcripts&returnFields[]=response_additional_data&pageSize=25&page=1' \
--header 'account-id: your_account_id' \
--header 'x-api-key: your_api_key'
You can also fetch a single Response, see GET /v2/response/{responseId}
or all Responses inside an Account GET /v2/responses
.
Return Fields - Flexible API Responses
If the API documentation specifies that an endpoint has an optional returnFields
parameter, that means you can specify which fields you want returned in your request. If you only need Response IDs and their Additional Data, you’re in control. Being explicit about what data you want returned will speed up requests, make dealing with them easier, and allow you to ask for more Responses per page.
Below is an example request fetching specific fields for a single Response, where we know the Response ID before hand:
fetch('https://developer.voxpopme.com/v2/response/{responseId}?' +
'returnFields[]=thumb_path&' +
'returnFields[]=video_path&' +
'returnFields[]=response_additional_data', {
headers: {
'x-api-key': 'your_api_key',
'account-id': 'your_account_id',
}
});
Filtering Responses
When using an endpoint to fetch multiple Responses, we provide an option to apply a set of filters to your request to ensures you only get the Responses that match your specified criteria.
To fetch Responses, send a GET
request to /v2/question/{questionId}/responses
, where questionId
is the ID of the Project whose Responses we’re trying to fetch. Besides being able to specify returnFields
to only get the data you need, you can attach another parameter called filters like so:
const filters = JSON.stringify([
{
"searchTerm": "female",
"filterProperty": "gender",
"selectedFilter": "equal"
}, {
"searchTerm": "30",
"filterProperty": "age",
"selectedFilter": "greater_than"
}
]);
fetch('https://developer.voxpopme.com/v2/question/{questionId}/responses?'+
`filters=${filters}&` +
'returnFields[]=id&' +
'returnFields[]=response_additional_data&', {
headers: {
'x-api-key': 'your_api_key',
'account-id': 'your_account_id',
},
});
Dissecting a Filter & Filtering Options
A singular filter object, must always consist of a searchTerm
, a filterProperty
, and a selectedFilter
.
Parameter | Description | Example Values |
---|---|---|
searchTerm |
The value of the property we’re trying to filter and match by. | "female" , "30" "1512, 61231, 123123" - when using an "in" as selectedFilter |
filterProperty |
The name of the value we’re trying to match the searchTerm against. This can either be one of the default possible values, or the name of your Additional Data attribute. In the code snippet above, age and gender are both Additional Data values. |
"transcript" , "age" , "declined" , "response_id" |
selectedFilter |
The comparison operator to use when comparing filterProperty of the Response against the searchTerm . |
"in" - but only when filterProperty is "response_id" |
Filter Operators
By default, all filters will be joined by an equivalent of an AND
operator. So in the example above, we requested all Responses where the responded is over the age of 30, and female. If we wanted to search with an equivalent of an OR
, so finding all Responses where the responded is over 30, or a female, we have to send filterConditional = 'ANY'
, instead of filterConditional = 'ALL'
.
Comments
0 comments
Article is closed for comments.