The KnowledgeHound platform supports per user data access controls called Access Control Lists (ACLs for short) and all data APIs respond only with data that is accessible by a given user.
\nUser shadowing lets you shadow a given user and access data APIs on that user's behalf\n(if your account allows for shadowing).
\nGiven your JWT token and the user's email you want to shadow (specified in user_email), this returns another JWT token that lets you access\ndata APIs as the given user.\nPlease note, that if the user is not registered in our system we will return a new token\nthat can access data which has no ACL restrictions.
This token has a lifespan of one week (subject to change at a later date). We recommend that you obtain one at the beginning of your user session and use it throughout the duration of the session.
\n","urlObject":{"protocol":"https","path":["authentication","shadow-token",""],"host":["api","knowledgehound","com"],"query":[],"variable":[]}},"response":[{"id":"e3069d8a-600b-4762-8bb0-cb525627eb51","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"user_email","value":"user@knowledgehound.com","type":"text"}]}},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"JWT\": \"KJHSD8767DSSHDJ76.OIDDIJ.DNFKDJHFIO\"\n}"},{"id":"0308d368-4c40-43e0-9606-3097855245d8","name":"Unauthorized","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"user_email","value":"user@knowledgehound.com","type":"text"}]}},"code":401,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"Invalid credentials"},{"id":"60a69772-0f29-43cd-9d68-31e16d631e0f","name":"Not Permitted","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"user_email","value":"user@knowledgehound.com","type":"text"}]}},"code":403,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"You do not have permission to access this API"}],"_postman_id":"bd2b35a9-6147-4829-b433-0b4da5f64d4d"}],"id":"40339e42-95dc-44e2-b902-5cd2883dd36e","description":"This API authenticates your account with your username and password and returns a JWT token that will expire in a week. We suggest that you authenticate once per user session and reuse the token for the duration of the session. This API requires username and password fields as part of the body of the request.
Note: If you are integrating KnowledgeHound into an existing product,\nit is likely that you will want to access our data APIs on behalf of end users. To that end your auth token can only be used to shadow a user first and the newly obtained token must then be used for further data API access.
\n![\"Data](\"https://s3-us-west-2.amazonaws.com/kh-api-docs/media/data_api_with_user_shadowing.png\")
A JSON file defining the programming of the survey.
\nSchema
\n{\n \"id\": \"The unique identifier of the survey\",\n \"description\": \"(optional) A description of the survey\",\n \"type\": \"Tracker|OneTime\",\n \"status\": \"Created|Live|Completed\",\n \"start_date\": \"The datetime the survey began\",\n \"responses_as_of_date\": \"The datetime of the most recent survey response.\",\n \"completion_date\": \"(optional) The datetime the survey was completed. Not included if the survey is still open.\",\n \"language\": \"The ISO 639-2 language code for the default survey language : http://www.loc.gov/standards/iso639-2/php/code_list.php\",\n \"base_description\": \"(optional) Textual description of the survey base\",\n \"base_size\": \"int (optional): Count to use as base size, this may be different then response_count when applying weighting\",\n \"response_count\": \"int: Number of responses in the response file(s)\",\n \"source_url\": \"(optional) A url to the original research study in the source system\",\n \"source_display_text\": \"(optional) A text snippet to use as a display replacement for the source URL in KnowledgeHound\",\n \"metadata\": {\n \"metadata_field_1\": \"(optional) A set of field-value entries that can be set as flexible metadata in KnowledgeHound\"\n },\n \"question_templates\": [\n {\n \"id\": \"The unique identifier of the question template\",\n \"type\": \"OpenEnd|Categorical|Int|Decimal\",\n \"categorical_response_options\": [\n {\n \"id\": \"The unique value of the response.\",\n \"text\": \"The displayed response text.\",\n \"media_id\": \"(optional) The id of media content shown.\"\n }\n ],\n \"selection_limit\": \"(optional) int: The number of permissible values for a categorical question Ex: Pick 1 or Pick 3\",\n \"text\": \"The question presented to the user. (Includes variables when used)\",\n \"display_text\": \"(optional) If the question contains a variable, this should be the human readable version of the template. If no display text is included, the text field is displayed.\",\n \"description\": \"(optional) Any additional information about the question\",\n \"visible\": \"boolean (optional): Defaults to true : Do all users or only admins see the question in KnowledgeHound\",\n \"default_weighting\": \"boolean (optional): Defaults to false - use this question as the weighting variable by default\",\n \"weighting_label\": \"(optional): Display text to more concisely describe the weighting variable\",\n \"variables\": [\n {\n \"id\": \"The variable used in the question template\",\n \"type\": \"survey|survey_response|person\",\n \"order\": \"The sequence of the variable\"\n }\n ]\n }\n ],\n \"question_groupings\": [\n {\n \"id\": \"The unique identifier of the question group\",\n \"description\": \"(optional)\",\n \"order\": \"int\",\n \"source_url\": \"(optional) A url to the original question in the source system\",\n \"variables\": [\n {\n \"id\": \"VariableId\",\n \"type\": \"survey|survey_response|person\",\n \"order\": \"The sequence of the variable\"\n }\n ],\n \"questions\": [\n {\n \"question_template_id\": \"string: The id of the question template in the question_templates array\",\n \"order\": 1\n }\n ]\n }\n ],\n \"variables\": [\n {\n \"id\": \"The variable used in the question template\",\n \"name\": \"The human readable name for the variable\",\n \"description\": \"(optional)\",\n \"values\": [{\n \"value\": \"string\",\n \"display_value\": \"(optional): If no display text is included, the value field is displayed.\",\n \"sort_order\": \"int (optional): Controls the default ordering in lists and controls. When not sent we apply an alphanumeric sort.\"\n }],\n \"visible\": \"boolean (optional): Defaults to true : Do all users or only admins see the variable in KnowledgeHound\"\n }\n ],\n \"media\": [\n {\n \"id\": \"The unique identifier of the media.\",\n \"relative_path\": \"The full path to the file in S3\",\n \"url\": \"The publicly accessible URL of the file. This can be used in place of relative_path.\",\n \"type\": \"image|video\",\n \"display_text\": \"(optional) text to display for accessibility or when the content cannot render\"\n }\n ]\n}\n\nDefault Weighting
\nThe Survey dimension supports specifying a default weighting variable, using the default_weighting and weighting_label
fields on a question template. Both fields are optional, but if used, only one template should be marked as such.
Only a numeric question can be used for this purpose - either types Int or Decimal. Use weighting_label to provide a more concise identifier for the question - for example, if the question is \"How old are you?\", consider using
\"Respondent Age\" as the weighting_label if selecting the question for default weighting.
Numeric Values for Categorical Responses
\nCategorical Responses will be automatically scanned for numeric values within them. Responses that contain numeric values may then be used to calculate means during analysis.
\nFor example, in a scale question with responses 1 - 5, respondents will be assigned the numeric value for the response they selected. Thus if all respondents selected \"Slightly agree\", the mean would be 4.
\n`1 Strongly disagree`\n`2 Slightly disagree`\n`3 Neither agree or disagree`\n`4 Slightly agree`\n`5 Strongly agree`\n\nAdditionally, Categorical Responses that contain numeric ranges will use the intermediate value of the range. For example, a question which asks how many children are in a household may have responses:
\n0\n1 - 2\n3 - 5\n6 or more\n\nThe numeric values assigned to the responses would be 0, 1.5, 4, 6 respectively.
\nGeneric Metadata
\nThe Survey dimension also supports a form of hierarchical generic metadata entry that can be used to feed KnowledgeHound's flexible survey metadata. This field can be omitted or left as an empty object \"metadata\": {} if not desired.
NOTE: At this time, metadata using this method can only be set at first-time Data API survey creation, not during updates.
\nTo set metadata fields, include metadata as an object containing the desired metadata field name as a key and the field value as a value. You can specify multiple fields:
\"metadata\": {\n \"field_1\": \"value_1\",\n \"field_2\": \"value_2\"\n}\n\nKnowledgeHound supports hierarchical metadata fields. You can specify fields of this kind by nesting objects and using the key of the nested object as the parent metadata field value, and the value of the object as the child metadata field value.
For example, you can specify a field named FruitType with a parent value of Berry and a child value of Strawberry as follows:
\"metadata\": {\n \"FruitType\": {\n \"Berry\": \"Strawberry\"\n }\n}\n\nThis would allow the study in KnowledgeHound to be tagged with both Berry and Strawberry categories that can be used as filters. You can also continue nesting, as well as specify other fields:
\n\"metadata\": {\n \"Sweetness\": \"High\",\n \"FoodType\": {\n \"Fruit\": {\n \"Citrus\": \"Orange\"\n }\n }\n}\n\nIt is important to understand that metadata fields are case sensitive.
\n","_postman_id":"40021d0f-5468-4157-88da-fea98fe628a6"},{"name":"Person Dimension","item":[],"id":"71841393-33a2-4012-8c1c-871a5e1d311b","description":"A JSON file containing the list of unique people who have participated in the survey.
\nIf the same person exists in multiple datasets, their ID should remain consistent. Some countries and research may not allow for the identification of a person across multiple datasets. In these cases, the ID should be an incrementing value that is consistent between the person dimension and the survey response dimension.
\nKnowledgeHound has defined several core attributes about a person. These attributes are all optional and sit at the root of the person object. In the future, custom attributes will be supported in the 'attribute' object.
\nWhere a person attribute is listed as having multiple types such as \"decimal or string\", they will first be parsed as a numeric type and default to a string to allow support for individual values and ranges. All person entries must be type consistent. Mixing numerics or strings in response data for the same field will cause errors.
\n{\n \"attribute\": [\n {\"to be defined in the future\": null}\n ],\n \"person\": [\n {\n \"id\": \"The unique ID from the source system for this person\",\n \"first_name\": \"string (optional) - not currently imported for PII protection\",\n \"last_name\": \"string (optional) - not currently imported for PII protection\",\n \"gender\": \"Male|Female|Non-Binary (optional)\",\n \"age\": \"int (optional)\",\n \"income\": \"int (optional) personal income (optional)\",\n \"household_income\": \"int (optional) household income (optional)\",\n \"income_range\": \"string (optional)\",\n \"household_income_range\": \"string (optional)\",\n \"household_size\": \"int (optional)\",\n \"count_of_children\": \"int (optional)\",\n \"marital_status\": \"divorced|married|separated|single|widowed (optional)\",\n \"home_ownership\": \"own|rent|relative (optional)\",\n \"email\": \"string (optional) - not currently imported for PII protection\",\n \"phone\": \"string (optional) - not currently imported for PII protection\",\n \"city\": \"string (optional)\",\n \"region\": \"string (optional)\",\n \"county\": \"string (optional)\",\n \"state\": \"string (optional)\",\n \"postal_code\": \"string (optional)\",\n \"country\": \"string (optional)\",\n \"career\": \"string (optional)\",\n \"education_level\": \"string (optional)\",\n \"ethnicity\": \"string (optional)\",\n \"political_affiliation\": \"string (optional)\",\n \"employment_status\": \"string (optional)\",\n \"religion\": \"string (optional)\",\n \"attributes\": [\n {\"to be defined in the future\": null}\n ]\n }\n ]\n}\n\nA CSV file containing responses to survey questions, here are the highlights with greater detail following:
\n- \n
- One respondent per line, respondent ID in column PERSON_ID \n
- If a user wasn't shown a question no empty space should exist between the commas. \n
- Categorical values are represented by a 1 meaning selected, 0 meaning not selected or blank as not presented \n
- The header row must match the following format.
QuestionGroupingId_QuestionTemplateId_VariableId_VariableValue_ResponseOptionId\n - RFC 4180, UTF-8, no BOM \n
File formatting
\nWe require that respondent data CSV files be encoded as UTF-8 with no BOM at the start of the file.
Files should conform to RFC 4180. We do require a header at the start of each respondent CSV, explained below.
In a nutshell, RFC 4180 requires that fields be delimited by commas, and that no spaces should exist between the delimiting comma and the field: any spaces will be treated as part of the field. Fields may or may not be enclosed in double quotes (\"), but any fields that contain double quotes as part of the data must be enclosed in double quotes, and the double quotes in the data must be duplicated. For example, the data:
This is a \"sample\" field
\nWould need to be represented in the CSV as:
\n\"This is a \"\"sample\"\" field\"
\nFields that contain null values should be completely empty. That is, no character or other data whatsoever should be included between the delimiting commas or after the final comma in a row of data.
\nWe recommend that fields meant to represent an empty text string be enclosed in double quotes to differentiate them from null fields.
\nQuestion responses
\nFields containing categorical question responses should only contain either the character '1', the character '0',
or a null (empty) field. A 1 represents a positive response to the question. A 0 represents a negative response.
Note that these are both active responses. If a respondent was never shown the question at all, leave the field null.
Fields containing open-ended or text responses can contain any data.
\nFields for integer responses should contain only numeric values with no thousands separators or decimal points.
\nDecimal fields should always contain decimal points, even if the decimal component of the response is 0, like in \"10.0\" for example.
\nColumns and headers
\nColumns are not required to be in any particular order, except for the first column, which should be PERSON_ID.
\nPERSON_ID is meant to allow you to correlate responses in the data you are supplying with respondent information located in the Person dimension.
For this reason, we require that PERSON_ID contain a unique value for each respondent in the CSV. PERSON_ID values should be alphanumeric.
All successive columns after PERSON_ID are data columns, one per distinct question response.
\nA distinct question response is the unique combination of question grouping, question template, variable, variable value, and response option, as specified in the Survey dimension:
A question grouping links to one or more question templates, a question template may or may not link to a variable, and a variable contains values. A categorical question will contain response options.
The combination of identifiers for all of these components uniquely identifies a single response field.
\nWe require that each data column in the CSV correspond to one of these distinct fields and that the header field for that column contain the combined identifier in the following format:
\nQuestionGroupingId_QuestionTemplateId_VariableId_VariableValue_ResponseOptionId
\nIf any of these 5 components do not apply for a question, they should be left as '0'. Naturally, this means that the ID '0' is not permitted as an identifier in the Survey dimension specification.
\nFor example, as in the sample specification, say we have a question grouping Q1:
\n{\n \"id\": \"Q1\",\n \"order\": 1,\n \"questions\": [\n {\n \"question_template_id\": \"T1\",\n \"order\": 1\n }\n ]\n}\n\nand a corresponding question template T1:
\n{\n \"id\": \"T1\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R1\",\n \"text\": \"Red\"\n },\n {\n \"id\": \"R2\",\n \"text\": \"Green\"\n },\n {\n \"id\": \"R3\",\n \"text\": \"Blue\"\n }\n ],\n \"selection_limit\": 1,\n \"text\": \"What is your favorite color?\",\n \"visible\": true\n}\n\nThis specifies a single categorical question with no variables. The unique header fields we would expect for this question would be:
\nQ1_T1_0_0_R1, Q1_T1_0_0_R2, Q1_T1_0_0_R3
\nNote that there are no variables for this question, but there are response options. Therefore, we set VariableID and VariableValue
to '0' because they did not apply. We require that non-applicable IDs be set to '0' and not omitted to differentiate ambiguous headers.
As another example, let's say Q1 instead specifies a template ID of T11:
\n{
\"id\": \"T11\",
\"type\": \"OpenEnd\",
\"text\": \"Say hello to the world\"
}
In this case, there would be no response options: the question is open-ended. There are also no variables. Thus, we expect only one
header field: Q1_T11_0_0_0
If a variable were specified in the question template:
\n{\n \"id\": \"T10\",\n \"type\": \"Int\",\n \"text\": \"Please rank the following from best tasting (1) to least appetizing (5)\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ]\n}\n\nWith variable V1 being specified as:
\n{\n \"id\": \"V1\",\n \"name\": \"Candy Brands\",\n \"description\": \"A few popular brands of candy\",\n \"values\": [\n {\n \"id\": \"BRND1\",\n \"value\": \"Snickers\"\n },\n {\n \"id\": \"BRND2\",\n \"value\": \"Reese's Peanut Butter Cups\"\n },\n {\n \"id\": \"BRND3\",\n \"value\": \"Milky Way\"\n },\n {\n \"id\": \"BRND4\",\n \"value\": \"Hershey's Bar\"\n },\n {\n \"id\": \"BRND5\",\n \"value\": \"Milka\"\n }\n ]\n}\n\nThen we would expect, still using question grouping Q1 and template T10, 5 columns and header fields, one for each variable value:
\nQ1_T10_V1_BRND1_0, Q1_T10_V1_BRND2_0, Q1_T10_V1_BRND3_0, Q1_T10_V1_BRND4_0, Q1_T10_V1_BRND5_0
\nNote again that the field for ResponseOptionId was left as '0' because this was not a categorical question.
If it was a categorical question, for example with 5 possible responses, we would expect 25 fields, one for each combination
of variable value and response option ID.
For instance, this template specifies both variables and response options and would have 25 fields:
{\n \"id\": \"T8\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R24\",\n \"text\": \"Definitely\"\n },\n {\n \"id\": \"R25\",\n \"text\": \"Maybe\"\n },\n {\n \"id\": \"R26\",\n \"text\": \"Unsure\"\n },\n {\n \"id\": \"R27\",\n \"text\": \"Unlikely\"\n },\n {\n \"id\": \"R28\",\n \"text\": \"Won't\"\n }\n ],\n \"selection_limit\": 1,\n \"text\": \"Indicate your likelihood to buy [V1]\",\n \"display_text\": \"Indicate your likelihood to buy [brand]\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ]\n}\n\nIf there were more than one variable, for example, 3 variables each with 5 values, and also 5 categorical response options,
we would expect 75 headers/columns for that question.
Survey Dimension
\n{\n \"id\": \"DEMO1234\",\n \"description\": \"This sample survey was created to provide a practical guide to KnowledgeHound's data API\",\n \"type\": \"OneTime\",\n \"status\": \"Live\",\n \"start_date\": \"2020-04-08\",\n \"responses_as_of_date\": \"2020-05-23\",\n \"language\": \"eng\",\n \"base_description\": \"All respondents were imagined by a GAN\",\n \"base_size\": \"10\",\n \"response_count\": \"10\",\n \"source_url\": \"https://www.knowledgehound.com\",\n \"source_display_text\": \"KnowledgeHound Home\",\n \"question_templates\": [\n {\n \"id\": \"T1\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R1\",\n \"text\": \"Red\"\n },\n {\n \"id\": \"R2\",\n \"text\": \"Green\"\n },\n {\n \"id\": \"R3\",\n \"text\": \"Blue\"\n }\n ],\n \"selection_limit\": 1,\n \"text\": \"What is your favorite color?\",\n \"visible\": true\n },\n {\n \"id\": \"T2\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R4\",\n \"text\": \"France\"\n },\n {\n \"id\": \"R5\",\n \"text\": \"Spain\"\n },\n {\n \"id\": \"R6\",\n \"text\": \"United States\"\n },\n {\n \"id\": \"R7\",\n \"text\": \"China\"\n },\n {\n \"id\": \"R8\",\n \"text\": \"Italy\"\n }\n ],\n \"text\": \"Which countries have you visited?\"\n },\n {\n \"id\": \"T3\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R9\",\n \"text\": \"Gone with the Wind\",\n \"media_id\": \"M1\"\n },\n {\n \"id\": \"R10\",\n \"text\": \"The Wizard of Oz\",\n \"media_id\": \"M2\"\n },\n {\n \"id\": \"R11\",\n \"text\": \"One Flew Over the Cuckoo's Nest\",\n \"media_id\": \"M3\"\n },\n {\n \"id\": \"R12\",\n \"text\": \"Forrest Gump\",\n \"media_id\": \"M4\"\n },\n {\n \"id\": \"R13\",\n \"text\": \"The Sound of Music\",\n \"media_id\": \"M5\"\n },\n {\n \"id\": \"R14\",\n \"text\": \"West Side Story\",\n \"media_id\": \"M6\"\n }\n ],\n \"selection_limit\": 3,\n \"text\": \"What are your top three movies?\"\n },\n {\n \"id\": \"T4\",\n \"type\": \"Int\",\n \"text\": \"How old are you?\",\n \"visible\": false,\n \"tags\": [\"age\"],\n \"default_weighting\": true,\n \"weighting_label\": \"Respondent Age\"\n },\n {\n \"id\": \"T5\",\n \"type\": \"Decimal\",\n \"text\": \"Enter a decimal between 1 and 2\"\n },\n {\n \"id\": \"T6\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R15\",\n \"text\": \"Definitely\"\n },\n {\n \"id\": \"R16\",\n \"text\": \"Maybe\"\n },\n {\n \"id\": \"R17\",\n \"text\": \"Unsure\"\n },\n {\n \"id\": \"R18\",\n \"text\": \"Unlikely\"\n },\n {\n \"id\": \"R19\",\n \"text\": \"Won't\"\n }\n ],\n \"selection_limit\": 1,\n \"text\": \"Indicate your likelihood to buy each brand\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"T7\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R20\",\n \"text\": \"Convenience\"\n },\n {\n \"id\": \"R21\",\n \"text\": \"Super Market\"\n },\n {\n \"id\": \"R22\",\n \"text\": \"Gas Station\"\n },\n {\n \"id\": \"R23\",\n \"text\": \"Online\"\n }\n ],\n \"text\": \"Where have you purchased each brand\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"T8\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R24\",\n \"text\": \"Definitely\"\n },\n {\n \"id\": \"R25\",\n \"text\": \"Maybe\"\n },\n {\n \"id\": \"R26\",\n \"text\": \"Unsure\"\n },\n {\n \"id\": \"R27\",\n \"text\": \"Unlikely\"\n },\n {\n \"id\": \"R28\",\n \"text\": \"Won't\"\n }\n ],\n \"selection_limit\": 1,\n \"text\": \"Indicate your likelihood to buy [V1]\",\n \"display_text\": \"Indicate your likelihood to buy [brand]\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"T9\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R29\",\n \"text\": \"Convenience\"\n },\n {\n \"id\": \"R30\",\n \"text\": \"Super Market\"\n },\n {\n \"id\": \"R31\",\n \"text\": \"Gas Station\"\n },\n {\n \"id\": \"R32\",\n \"text\": \"Online\"\n }\n ],\n \"text\": \"Where have you purchased [v1]\",\n \"display_text\": \"Where have you purchased [brand]\",\n \"description\": \"Optional: Any additional information about the question\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"T10\",\n \"type\": \"Int\",\n \"text\": \"Please rank the following from best tasting (1) to least appetizing (5)\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"T11\",\n \"type\": \"OpenEnd\",\n \"text\": \"Say hello to the world\"\n }\n ],\n \"question_groupings\": [\n {\n \"id\": \"Q1\",\n \"order\": 1,\n \"questions\": [\n {\n \"question_template_id\": \"T1\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"Q2\",\n \"order\": 2,\n \"questions\": [\n {\n \"question_template_id\": \"T2\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"Q3\",\n \"order\": 3,\n \"questions\": [\n {\n \"question_template_id\": \"T3\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"Q4\",\n \"order\": 4,\n \"questions\": [\n {\n \"question_template_id\": \"T4\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"Q5\",\n \"order\": 5,\n \"questions\": [\n {\n \"question_template_id\": \"T5\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"Q6\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ],\n \"order\": 6,\n \"questions\": [\n {\n \"question_template_id\": \"T6\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"Q7\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ],\n \"order\": 7,\n \"questions\": [\n {\n \"question_template_id\": \"T7\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"Q8\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ],\n \"order\": 8,\n \"questions\": [\n {\n \"question_template_id\": \"T8\",\n \"order\": 1\n },\n {\n \"question_template_id\": \"T9\",\n \"order\": 2\n }\n ]\n },\n {\n \"id\": \"Q9\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ],\n \"order\": 9,\n \"questions\": [\n {\n \"question_template_id\": \"T10\",\n \"order\": 1\n }\n ]\n },\n {\n \"id\": \"Q10\",\n \"order\": 10,\n \"questions\": [\n {\n \"question_template_id\": \"T11\",\n \"order\": 1\n }\n ]\n }\n ],\n \"question_flow\": \"Future support for control logic\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"name\": \"Candy Brands\",\n \"description\": \"A few popular brands of candy\",\n \"values\": [\n {\n \"id\": \"BRND1\",\n \"value\": \"Snickers\"\n },\n {\n \"id\": \"BRND2\",\n \"value\": \"Reese's Peanut Butter Cups\"\n },\n {\n \"id\": \"BRND3\",\n \"value\": \"Milky Way\"\n },\n {\n \"id\": \"BRND4\",\n \"value\": \"Hershey's Bar\"\n },\n {\n \"id\": \"BRND5\",\n \"value\": \"Milka\"\n }\n ]\n }\n ],\n \"media\": [\n {\n \"id\": \"M1\",\n \"relative_path\": \"/images/gone_with_the_wind.png\",\n \"type\": \"image\"\n },\n {\n \"id\": \"M2\",\n \"relative_path\": \"/images/the_wizard_of_oz.png\",\n \"type\": \"image\"\n },\n {\n \"id\": \"M3\",\n \"relative_path\": \"/images/one_flew_over_the_cuckoos_nest.png\",\n \"type\": \"image\"\n },\n {\n \"id\": \"M4\",\n \"relative_path\": \"/images/forrest_gump.png\",\n \"type\": \"image\"\n },\n {\n \"id\": \"M5\",\n \"relative_path\": \"/images/the_sound_of_music.png\",\n \"type\": \"image\"\n },\n {\n \"id\": \"M6\",\n \"relative_path\": \"/images/west_side_story.png\",\n \"type\": \"image\"\n }\n ]\n}\n\nPerson Dimension
\n{\n \"attribute\": [],\n \"person\": [\n {\n \"id\": \"1\",\n \"first_name\": \"John\",\n \"last_name\": \"Stone\",\n \"gender\": \"Male\",\n \"age\": 55,\n \"income\": 84820,\n \"household_size\": 4,\n \"count_of_children\": 2,\n \"marital_status\": \"married\",\n \"home_ownership\": \"own\",\n \"postal_code\": \"12345\"\n },\n {\n \"id\": \"2\",\n \"first_name\": \"Ponnappa\",\n \"last_name\": \"Priya\",\n \"gender\": \"Female\",\n \"income\": 85322,\n \"household_size\": 6,\n \"count_of_children\": 4,\n \"marital_status\": \"married\",\n \"home_ownership\": \"own\",\n \"postal_code\": \"54321\",\n \"attributes\": []\n },\n {\n \"id\": \"3\",\n \"first_name\": \"Mia\",\n \"last_name\": \"Wong\",\n \"gender\": \"Non-Binary\",\n \"age\": 20,\n \"income\": 50931,\n \"household_size\": 1,\n \"marital_status\": \"single\",\n \"home_ownership\": \"rent\",\n \"postal_code\": \"23451\",\n \"attributes\": []\n },\n {\n \"id\": \"4\",\n \"first_name\": \"Peter\",\n \"last_name\": \"Stanbridge\",\n \"age\": 48,\n \"income\": 86422,\n \"household_size\": 3,\n \"count_of_children\": 2,\n \"marital_status\": \"widowed\",\n \"home_ownership\": \"own\",\n \"postal_code\": \"15432\"\n },\n {\n \"id\": \"5\",\n \"first_name\": \"Natalie\",\n \"last_name\": \"Lee-Walsh\",\n \"gender\": \"Female\",\n \"age\": 24,\n \"income\": 95804,\n \"household_size\": 3,\n \"count_of_children\": 1,\n \"marital_status\": \"married\",\n \"home_ownership\": \"rent\",\n \"postal_code\": \"34512\"\n },\n {\n \"id\": \"6\",\n \"first_name\": \"Ang\",\n \"last_name\": \"Li\",\n \"age\": 28,\n \"income\": 92764,\n \"household_size\": 3,\n \"count_of_children\": 1,\n \"marital_status\": \"married\",\n \"home_ownership\": \"own\",\n \"postal_code\": \"21543\"\n },\n {\n \"id\": \"7\",\n \"first_name\": \"Nguta\",\n \"last_name\": \"Ithya\",\n \"gender\": \"Male\",\n \"age\": 50,\n \"income\": 84820,\n \"household_size\": 1,\n \"marital_status\": \"separated\",\n \"home_ownership\": \"own\",\n \"postal_code\": \"45123\"\n },\n {\n \"id\": \"8\",\n \"first_name\": \"Tamzyn\",\n \"last_name\": \"French\",\n \"age\": 63,\n \"income\": 71047,\n \"household_size\": 5,\n \"count_of_children\": 3,\n \"marital_status\": \"married\",\n \"home_ownership\": \"own\",\n \"postal_code\": \"51234\"\n },\n {\n \"id\": \"9\",\n \"first_name\": \"Salome\",\n \"last_name\": \"Simoes\",\n \"gender\": \"Non-Binary\",\n \"age\": 28,\n \"income\": 92125,\n \"household_size\": 1,\n \"marital_status\": \"single\",\n \"home_ownership\": \"rent\",\n \"postal_code\": \"43215\"\n },\n {\n \"id\": \"10\",\n \"first_name\": \"Trevor\",\n \"last_name\": \"Virtue\",\n \"age\": 71,\n \"income\": 54415,\n \"household_size\": 2,\n \"marital_status\": \"married\",\n \"home_ownership\": \"own\",\n \"postal_code\": \"43251\"\n }\n ]\n}\n\nSurvey Response Dimension
\nPERSON_ID,Q1_T1_0_0_R1,Q1_T1_0_0_R2,Q1_T1_0_0_R3,Q2_T2_0_0_R4,Q2_T2_0_0_R5,Q2_T2_0_0_R6,Q2_T2_0_0_R7,Q2_T2_0_0_R8,Q3_T3_0_0_R9,Q3_T3_0_0_R10,Q3_T3_0_0_R11,Q3_T3_0_0_R12,Q3_T3_0_0_R13,Q3_T3_0_0_R14,Q4_T4_0_0_0,Q5_T5_0_0_0,Q6_T6_V1_BRND1_R15,Q6_T6_V1_BRND1_R16,Q6_T6_V1_BRND1_R17,Q6_T6_V1_BRND1_R18,Q6_T6_V1_BRND1_R19,Q6_T6_V1_BRND2_R15,Q6_T6_V1_BRND2_R16,Q6_T6_V1_BRND2_R17,Q6_T6_V1_BRND2_R18,Q6_T6_V1_BRND2_R19,Q6_T6_V1_BRND3_R15,Q6_T6_V1_BRND3_R16,Q6_T6_V1_BRND3_R17,Q6_T6_V1_BRND3_R18,Q6_T6_V1_BRND3_R19,Q6_T6_V1_BRND4_R15,Q6_T6_V1_BRND4_R16,Q6_T6_V1_BRND4_R17,Q6_T6_V1_BRND4_R18,Q6_T6_V1_BRND4_R19,Q6_T6_V1_BRND5_R15,Q6_T6_V1_BRND5_R16,Q6_T6_V1_BRND5_R17,Q6_T6_V1_BRND5_R18,Q6_T6_V1_BRND5_R19,Q7_T7_V1_BRND1_R20,Q7_T7_V1_BRND1_R21,Q7_T7_V1_BRND1_R22,Q7_T7_V1_BRND1_R23,Q7_T7_V1_BRND2_R20,Q7_T7_V1_BRND2_R21,Q7_T7_V1_BRND2_R22,Q7_T7_V1_BRND2_R23,Q7_T7_V1_BRND3_R20,Q7_T7_V1_BRND3_R21,Q7_T7_V1_BRND3_R22,Q7_T7_V1_BRND3_R23,Q7_T7_V1_BRND4_R20,Q7_T7_V1_BRND4_R21,Q7_T7_V1_BRND4_R22,Q7_T7_V1_BRND4_R23,Q7_T7_V1_BRND5_R20,Q7_T7_V1_BRND5_R21,Q7_T7_V1_BRND5_R22,Q7_T7_V1_BRND5_R23,Q8_T8_V1_BRND1_R24,Q8_T8_V1_BRND1_R25,Q8_T8_V1_BRND1_R26,Q8_T8_V1_BRND1_R27,Q8_T8_V1_BRND1_R28,Q8_T8_V1_BRND2_R24,Q8_T8_V1_BRND2_R25,Q8_T8_V1_BRND2_R26,Q8_T8_V1_BRND2_R27,Q8_T8_V1_BRND2_R28,Q8_T8_V1_BRND3_R24,Q8_T8_V1_BRND3_R25,Q8_T8_V1_BRND3_R26,Q8_T8_V1_BRND3_R27,Q8_T8_V1_BRND3_R28,Q8_T8_V1_BRND4_R24,Q8_T8_V1_BRND4_R25,Q8_T8_V1_BRND4_R26,Q8_T8_V1_BRND4_R27,Q8_T8_V1_BRND4_R28,Q8_T8_V1_BRND5_R24,Q8_T8_V1_BRND5_R25,Q8_T8_V1_BRND5_R26,Q8_T8_V1_BRND5_R27,Q8_T8_V1_BRND5_R28,Q8_T9_V1_BRND1_R29,Q8_T9_V1_BRND1_R30,Q8_T9_V1_BRND1_R31,Q8_T9_V1_BRND1_R32,Q8_T9_V1_BRND2_R29,Q8_T9_V1_BRND2_R30,Q8_T9_V1_BRND2_R31,Q8_T9_V1_BRND2_R32,Q8_T9_V1_BRND3_R29,Q8_T9_V1_BRND3_R30,Q8_T9_V1_BRND3_R31,Q8_T9_V1_BRND3_R32,Q8_T9_V1_BRND4_R29,Q8_T9_V1_BRND4_R30,Q8_T9_V1_BRND4_R31,Q8_T9_V1_BRND4_R32,Q8_T9_V1_BRND5_R29,Q8_T9_V1_BRND5_R30,Q8_T9_V1_BRND5_R31,Q8_T9_V1_BRND5_R32,Q9_T10_V1_BRND1_0,Q9_T10_V1_BRND2_0,Q9_T10_V1_BRND3_0,Q9_T10_V1_BRND4_0,Q9_T10_V1_BRND5_0,Q10_T11_0_0_0,Q11_T12_0_0_0\nalpha,1,0,0,1,1,0,0,0,0,0,1,1,0,1,22,1.12,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,1,0,1,1,1,0,1,1,1,0,1,1,1,0,1,1,1,0,1,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,2,3,4,5,Open ended response text here,1\n2,0,1,0,1,0,1,0,1,1,1,1,0,0,0,45,1.56,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,1,3,2,5,4,Open ended response text here,2\n3,0,1,0,0,1,0,1,1,0,1,1,0,0,1,64,1.99,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,5,3,2,4,1,Open ended response text here,3\n4,1,0,0,1,1,0,0,0,0,1,0,1,0,1,26,1.42,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,0,0,1,0,1,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,1,2,3,4,5,Open ended response text here,\n5,0,0,1,1,1,1,0,0,1,0,0,1,1,0,36,1.37,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,0,0,1,1,0,1,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,1,1,1,0,1,1,1,0,1,1,1,0,1,1,1,0,1,1,1,0,1,4,5,2,3,Open ended response text here,4\n6,,,,,,,,,0,1,1,0,0,1,19,1.71,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,0,1,1,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,1,3,2,4,5,Open ended response text here,5\n7,1,0,0,1,0,1,1,0,1,0,0,1,0,1,54,1.25,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,2,3,4,5,1,Open ended response text here,6\n8,0,1,0,0,1,1,0,0,0,0,1,1,0,1,42,1.83,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,2,4,5,3,1,Open ended response text here,\n9,1,0,0,1,1,1,1,1,1,1,0,1,0,0,33,1.92,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,0,5,2,4,3,1,Open ended response text here,7\n10,0,0,1,0,1,0,0,0,0,0,1,1,0,1,60,1.11,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,0,1,1,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0,4,3,1,5,2,Ӿ Ӹ Ӕ Ҩ,8\n\nThis section of the document provides the file specification for transferring data to KnowledgeHound.
\n- \n
- Files are UTF-8 encoded \n
- Dates use the W3.org recommended format of YYYY-MM-DDThh:mm:ss.sTZD\n \n
- Metadata is exchanged through RFC 7159 compliant JSON. http://www.rfc-editor.org/rfc/rfc7159.txt \n
- Data is exchanged through RFC 4180 compliant csv. https://tools.ietf.org/html/rfc4180
- \n
- Remember to handle open ends and other text that may have commas or quotes! \n
\n - The maximum size of the Survey Response dimension file is 2GB. \n
Dimension files describe the questions and metadata in a dataset (Survey Dimension), the demographic data of respondents (Person Dimension) and the raw response data of respondents (Survey Response Dimension). Each is described below.
\nAWS customers may provide an S3 bucket as the source of the dimension files. See Permissions Guide for how to setup your S3 bucket. If you can not provide an S3 bucket to transfer files, see the Data File Staging API
\n","_postman_id":"92e088b0-7c27-439b-8e27-fe3ab487b257"},{"name":"Permissions Guide","item":[],"id":"73c7121e-8764-4f3a-8b8d-e0de5ea68a2d","description":"S3 Permissions
\nKnowledgeHound needs read access to your files in S3 to process them. We recommend Object ACLs or Bucket Policies to grant access by KnowledgeHound.
\nObject ACL
\nObject ACLs can be set through either the AWS Console or the AWS CLI. The KnowledgeHound Canonical ID is: 7b8f485aec57cb9e3956763470093ea2e329b5531544d78ad6618ecdf1deffba.
Example CLI command:\naws s3api put-object-acl --bucket mybucket --key path/to/object --grant-read id=7b8f485aec57cb9e3956763470093ea2e329b5531544d78ad6618ecdf1deffba
Bucket Policy
\nAlternatively, you can also set a bucket policy in the AWS Console or the AWS CLI. The KnowledgeHound Account ID is: 548906291368.
Example policy:
\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Principal\": {\n \"AWS\": \"arn:aws:iam::548906291368:root\"\n },\n \"Action\": \"s3:GetObject\",\n \"Resource\": [\n \"arn:aws:s3:::mybucket/path/to/object\",\n \"arn:aws:s3:::mybucket/path/to/directory/*\"\n ]\n }\n ]\n}\nExample CLI command:\naws s3api put-bucket-policy --bucket mybucket --policy file://bucket_policy.json
jsonThe Survey Dimension is a template based schema designed to allow flexible reuse of common survey components such as
list of products or brands. This guide demonstrates how the simplest common survey data use cases map to the
Sample data and how to map to corresponding CSV Headers and values.
After understanding these basic use cases, you should be able to extrapolate reuse of templates across multiple
questions in a survey to reduce duplication in the survey specification.
Each use case is broken down in to the respective sections in the Survey Dimension using keys 'question_templates',
'question_groupings' amd 'variables'
The CSV section demonstrates how the relevant columns would be represented in the CSV file associated with the
sample survey dimension.
Single Select Question : What is your favorite color?
\nQuestion Template T1:
\n{\n \"id\": \"T1\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R1\",\n \"text\": \"Red\"\n },\n {\n \"id\": \"R2\",\n \"text\": \"Green\"\n },\n {\n \"id\": \"R3\",\n \"text\": \"Blue\"\n }\n ],\n \"selection_limit\": 1,\n \"text\": \"What is your favorite color?\",\n \"visible\": true\n}\n\nNote: The selection_limit of 1 indicates that this is a single select question and that respondents could only select
one response option.
Question Grouping Q1:
\n{\n \"id\": \"Q1\",\n \"order\": 1,\n \"questJSions\": [\n {\n \"question_template_id\": \"T1\",\n \"order\": 1\n }\n ]\n}\n\nCSV:
\n(1 = Respondent Selected, 0 = Respondent saw response option and did not select, null = Respondent did not see option)
\nPERSON_ID,Q1_T1_0_0_R1,Q1_T1_0_0_R2,Q1_T1_0_0_R3alpha,1,0,02,0,1,03,0,1,04,1,0,05,0,0,16,,,7,1,0,08,0,1,09,1,0,0\n\nMulti Select Question : Which countries have you visited?
\nQuestion Template T2:
\n{\n \"id\": \"T2\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R4\",\n \"text\": \"France\"\n },\n {\n \"id\": \"R5\",\n \"text\": \"Spain\"\n },\n {\n \"id\": \"R6\",\n \"text\": \"United States\"\n },\n {\n \"id\": \"R7\",\n \"text\": \"China\"\n },\n {\n \"id\": \"R8\",\n \"text\": \"Italy\"\n }\n ],\n \"text\": \"Which countries have you visited?\"\n}\n\nNote: The absence of a selection_limit indicates the respondent may select as few or as many response options as they
wish. You may also indicate an upper limit, E.G., 'selection_limit': 3
Question Grouping Q2:
\n{\n \"id\": \"Q2\",\n \"order\": 2,\n \"questions\": [\n {\n \"question_template_id\": \"T2\",\n \"order\": 1\n }\n ]\n}\n\nCSV:
\n(1 = Respondent Selected, 0 = Respondent saw response option and did not select, null = Respondent did not see option)
\nPERSON_ID,Q2_T2_0_0_R4,Q2_T2_0_0_R5,Q2_T2_0_0_R6,Q2_T2_0_0_R7,Q2_T2_0_0_R8alpha,1,1,0,0,02,1,0,1,0,13,0,1,0,1,14,1,1,0,0,05,1,1,1,0,06,,,,,7,1,0,1,1,08,0,1,1,0,09,1,1,1,1,1\n\nOpen Ended/Text: Say hello to the world
\nQuestion Template T11:
\n{\n \"id\": \"T11\",\n \"type\": \"OpenEnd\",\n \"text\": \"Say hello to the world\"\n} \"id\": \"T11\", \"type\": \"OpenEnd\", \"text\": \"Say hello to the world\"}\n\nQuestion Grouping Q10:
\n{\n \"id\": \"Q10\",\n \"order\": 10,\n \"questions\": [\n {\n \"question_template_id\": \"T11\",\n \"order\": 1\n }\n ]\n}\n\nCSV
\n(1 = Respondent Selected, 0 = Respondent saw response option and did not select, null = Respondent did not see option)
\nPERSON_ID,Q10_T11_0_0_0alpha,Open ended response text here2,Open ended response text here3,Open ended response text here4,Open ended response text here5,Open ended response text here6,Open ended response text here7,Open ended response text here8,Open ended response text here9,Open ended response text here\n\nNumeric Question: How old are you?
\nQuestion Template T4:
\n{\n \"id\": \"T4\",\n \"type\": \"Int\",\n \"text\": \"How old are you?\",\n \"visible\": false,\n \"tags\": [\n \"age\"\n ],\n \"default_weighting\": true,\n \"weighting_label\": \"Respondent Age\"\n}\n\nNote: The type may be \"Int\" or \"Decimal\", and this example defines this numeric question as the default weighting
variable for the dataset, and the label which describes the weighting.
Question Grouping Q4:
\n{\n \"id\": \"Q4\",\n \"order\": 4,\n \"questions\": [\n {\n \"question_template_id\": \"T4\",\n \"order\": 1\n }\n ]\n}\n\nCSV
\nPERSON_ID,Q4_T4_0_0_0alpha,222,453,644,265,366,197,548,429,33\n\nGrid/Matrix Question: Where have you purchased each brand?
\nGrid/Matrix questions use an additional element called 'variables' which represent the rows in a table-like
survey question which is being asked of a list of related things - commonly products or brands etc.
Question Template T7:
\n{\n \"id\": \"T7\",\n \"type\": \"Categorical\",\n \"categorical_response_options\": [\n {\n \"id\": \"R20\",\n \"text\": \"Convenience\"\n },\n {\n \"id\": \"R21\",\n \"text\": \"Super Market\"\n },\n {\n \"id\": \"R22\",\n \"text\": \"Gas Station\"\n },\n {\n \"id\": \"R23\",\n \"text\": \"Online\"\n }\n ],\n \"text\": \"Where have you purchased each brand?\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ]\n}\n\nQuestion Grouping Q7:
\n{\n \"id\": \"Q7\",\n \"variables\": [\n {\n \"id\": \"V1\",\n \"type\": \"survey\",\n \"order\": 1\n }\n ],\n \"order\": 7,\n \"questions\": [\n {\n \"question_template_id\": \"T7\",\n \"order\": 1\n }\n ]\n}\n\nGrid/Matrix Variables V1:
\n{\n \"id\": \"V1\",\n \"name\": \"Candy Brands\",\n \"description\": \"A few popular brands of candy\",\n \"values\": [\n {\n \"id\": \"BRND1\",\n \"value\": \"Snickers\"\n },\n {\n \"id\": \"BRND2\",\n \"value\": \"Reese's Peanut Butter Cups\"\n },\n {\n \"id\": \"BRND3\",\n \"value\": \"Milky Way\"\n },\n {\n \"id\": \"BRND4\",\n \"value\": \"Hershey's Bar\"\n },\n {\n \"id\": \"BRND5\",\n \"value\": \"Milka\"\n }\n ]\n}\n\nCSV
\n(1 = Respondent Selected, 0 = Respondent saw response option and did not select, null = Respondent did not see option)
\nPERSON_ID,Q7_T7_V1_BRND1_R20,Q7_T7_V1_BRND1_R21,Q7_T7_V1_BRND1_R22,Q7_T7_V1_BRND1_R23,Q7_T7_V1_BRND2_R20,Q7_T7_V1_BRND2_R21,...alpha,1,1,0,1,1,1,...2,1,0,0,0,1,0,...3,0,1,0,0,0,1,...4,1,0,1,0,1,0,...5,0,1,0,0,0,1,...6,1,1,1,1,1,1,...7,1,0,0,0,1,0,...8,1,0,0,0,1,0,...9,0,0,1,1,0,0,...\n\nThe Request Staged Upload API allows you to request upload URLs for multiple files. You provide a JSON object with the list of filenames inside a \"files\" key.
\nIn a single request, you can fetch the upload URLs necessary to provide the survey dimension, person dimenson and survey response files necessary for the Data API.
\nIt is recommended that customers provide a prefix folder (\"survey_123\" in the example) to distinguish files for different datasets.
\nThe response will include for each file:
\n- \n
- The upload URL \n
- AWS provided form data to use as part of the upload. \n
- The S3 \"staging\" URL to include in the dimensions list of the Dataset APIs \n
E.G.
\n{\n \"files\": {\n \"survey_123/survey.json\": {\n \"post\": {\n \"url\": \"<file upload url>\",\n \"fields\": {\n \"key\": \"<upload key>\",\n \"AWSAccessKeyId\": \"<AWSAccessKeyId>\",\n \"policy\": \"<aws policy>\",\n \"signature\": \"<aws request signature>\"\n }\n },\n \"staging_url\": \"<file url>\"\n }\n },\n \"errors\": {}\n}\n\nEach 'staging_url' returned is a time limited (presigned) URL, valid for 5 minutes only.
\nThis API is an authenticated API. See Authentication API to authenticate.
\nNote, this API uses domain api-v2.knowledgehound.com
\n","urlObject":{"protocol":"https","path":["v2","data-upload",""],"host":["api-v2","knowledgehound","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"4cf3f8c5-cd8f-4d6b-9c9d-22f9fb601e02"},{"name":"Data File Upload","id":"1ed733b4-618a-4f93-a4c9-3cb71439ca3a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-amz-server-side-encryption","value":"AES256","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"key","value":"This is an example of the request needed to use with the AWS Transfer API. It is important to include the header 'x-amz-server-side-encryption' and set it to 'AES256' in addition to the form-data fields provided in the Staged Upload Request.
\n","urlObject":{"protocol":"https","path":[""],"host":["kh-production-data-ingestion","s3-accelerate","amazonaws","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"1ed733b4-618a-4f93-a4c9-3cb71439ca3a"}],"id":"54b6ffdf-6f5e-485c-bbbb-cf59b0aee623","description":"The Data File Staging (DFS) API provides the ability to load data into the KnowledgeHound platform for use with the Data API without providing an AWS S3 bucket.
\nIt is provided for customers based on cloud providers other than AWS (E.G. Azure or Google Cloud Platform, etc). If you are a user of AWS, it is recommended that you provide your own S3 bucket which prevents the need to use this API.
\nThe DFS API leverages the AWS S3 Transfer Acceleration API to provide a direct, regional upload capability to AWS S3 without you needing an AWS account, leveraging local AWS data centers to accelerate transfer.
\nThe flow for using DFS to stage files is as follows:
\n- \n
- Request Staged Upload URLs \n
- Upload files using Upload Data File \n
- Use the Staged URLs for each dimension of the Dataset APIs \n
This document defines the specification for data ingestion of survey data.
\nGuiding Principles and Assumptions
\n- \n
- Data sizes can vary significantly by study. Some studies contain a few KB of data, others contain several gigabytes of content. This API is optimized for our largest datasets. \n
- Metadata is exchanged through RFC 7159 compliant JSON. http://www.rfc-editor.org/rfc/rfc7159.txt \n
- To enable the exchange of large datasets, files are exchanged through an S3 bucket. \n
- Data can be uploaded directly from AWS S3 or through a file staging API. \n
Datasets
\nProvides the ability to list, access, create, or modify the datasets this account has access to.
\nList Datasets
\n- \n
URL:
\n/v2/dataset/\nMethod:
\nGET\nOptional Parameters
\n- \n
filter=[string]\nlimit=[int:100]\npage=[int:0]\n
\nSuccess Response:
\n{\n \"count\": 300,\n \"pages\": 3,\n \"next\": \"url\",\n \"previous\": \"url\",\n \"results\": [\n {\n \"id\": \"dataset_id\",\n \"url\": \"url\",\n \"name\": \"The dataset name\",\n \"description\": \"A description of the dataset\"\n }\n ]\n}\n\n\n
Create a dataset
\n- \n
URL:
\n/v2/dataset/\nMethods:
\nPOST\nPost Body:
\n{\n \"source_dataset_id\": \"source_dataset_id\",\n \"name\": \"The dataset name\",\n \"description\": \"A description of the dataset (optional)\",\n \"dimensions\":\n {\n \"survey\": \"The relative path to the file in S3 - valid URL\",\n \"person\": \"The relative path to the file in S3 - valid URL\",\n \"survey_response\": [\"The relative path to the file(s) in S3 - valid URL\"]\n },\n \"callback_url\": \"The URL for the success/failure callback- valid URL\"\n}\n\n\nResponse:
\n{\n\"status\": \"processing|validation_failure\",\n\"dataset_id\": \"\"\n}\n\n\nCallback:
\n{\n\"dataset\": \"\",\n\"success\": true,\n\"exceptions\": [\"error/exception messages\", \"...\"]\n} \n\nModify a dataset
\n \nThis API accepts the full JSON dataset specification and supports updating dimensions only,
\n
other field updates will be supported soon. \nURL:
\n/v2/dataset/{source_dataset_id}(or deprecated/v2/dataset/{dataset_id}) \nMethods:
\nPUT\nPost Body:
\n{\n \"source_dataset_id\": \"source_dataset_id\",\n \"name\": \"The dataset name\",\n \"description\": \"A description of the dataset (optional)\",\n \"dimensions\":\n {\n \"survey\": \"The relative path to the file in S3 - valid URL\",\n \"person\": \"The relative path to the file in S3 - valid URL\",\n \"survey_response\": [\"The relative path to the file(s) in S3 - valid URL\"]\n },\n \"callback_url\": \"The URL for the success/failure callback- valid URL\"\n}\n\n\nResponse:
\n{\n\"status\": \"processing|validation_failure\",\n\"dataset_id\": \"\"\n}\n\n\n
Get dataset details
\n- \n
- URL:
/v2/dataset/{source_dataset_id}(or deprecated/v2/dataset/{dataset_id}) \n - Methods:
GET\n - { \"client\": \"\", \"created\": \"\", \"created_by\": \"\", \"modified\": \"\", \"modified_by\": \"\", \"source_dataset_id\": \"source_dataset_id\", \"name\": \"The dataset name\", \"description\": \"A description of the dataset\", \"dimensions\": { \"survey\": \"The relative path to the file in S3\", \"person\": \"The relative path to the file in S3\", \"survey_response\": [\"The relative path to the file(s) in S3\"] }} \n
For partners who want to provide a more customized search and analysis experience, KnowledgeHound supports a partner provided Data Indexing webhook and an embedded analysis component for their web based UI.
\nData Indexing
\nKnowledgeHound will publish to a configured webhook for any newly published, updated or deleted data. Initial setup requires a historical data dump which can be arranged upon request.
\nThe partner must implement a webhook that accepts JSON data with the GET, POST and DELETE verbs. Updates will be delivered as entirely new data via a POST.
\nEach POST will be in the form of a JSON file upload on a study basis, which can be considered a collection of questions, typically named :
\nsearch_<client portal id>_<study number>.json
\nThe JSON structure uploaded will be of the following form:
\n[\n {\n \"client\": \"<client portal ID>\",\n “key”: “<question Key>”,\n \"url\": \"<question URL>\",\n \"question_text\": \"<Question Text>\",\n \"responses\": [<String>...],\n \"breakouts\": [“Matrix Row Name”...],\n “image_url”: “<URL of preview image>”\n \"study_url\": \"<URL to Study>\",\n \"weighting_label\": \"<English description of weighting>\",\n },\n…\nEvery time cleaned data is newly updated or uploaded, the configured webhook will be used to deliver to the partner the study data for search purposes.
\nThis structure provides enough data to display search results and deep links back to the KnowledgeHound platform for analysis, or to use the embedded analysis package within their own site(s) as an integrated UI. The “key” uniquely identifies a question in the KnowledgeHound platform and should be used to disambiguate questions in search results and passed to the embedded analysis component to begin analysis with.
\n","_postman_id":"076163ff-9506-4e63-a8eb-e056c0b24714"},{"name":"Federated Search","item":[{"name":"Search","id":"b651c5c9-57ce-43f0-a7fd-cad83cddc1a5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"The federated search API returns the most relevant results for the given query and entity type in a paginated fashion. The response contains descriptions of what text fragments matched the data and the list of metadata aggregations that can be used to re-execute search with filters.
\nPlease note that type and group_duplicates are needed for future API enhancements but currently only support question option.
\nBefore we get into the details of the Search API, we need to go over metadata - a core concept used throughout this API. Metadata is a set of (case sensitive) fields with hierarchical values that describe studies. Metadata fields and their values are fully configurable per customer and, aside from a few common fields, tend to be different between customers. A typical example of a metadata field (and one of the common ones) is geography. It is a field that reflects what geographies the given study was conducted in and typically reflects how the given customer structured their market research regions. For example, a study might have been conducted in United States, Canada, and China with the first two being a part of North America region. Hierarchical relationships in metadata are represented as lists of strings and the set of all choices for a given metadata field (e.g., a study was done in all three - U.S., Canada, and China) is represented as a list of lists. In this example, the geography metadata field would look like [ [\"North America\", \"United States\"], [\"North America\", \"Canada\"], [\"China\"] ].
Now let's go over the response JSON and its structure. It consists of two main elements - metadata_aggregations and results. The former is a list of metadata fields with values and the count of how many total results (for the whole query, not just for current page) have this value. These values can be used to redo the search query with filtering (see the use case below for details).
There are two different counts that will appear as part of metadata_aggregations - count and result_count. Given that metadata, as described above, is an attribute of a given study, the count aggregation for a given piece of metadata reflects the number of studies that are tagged with that metadata. result_count, on the other hand, reflects the number of results as described below that are linked to that metadata via a particular study. For example, a study tagged with a geography field value of North America might contribute 1 to the count aggregation under North America , but because there were 5 questions belonging to that study that were relevant to your search, the result_count aggregation would have a value of at least 5.
Because of the hierarchical nature of metadata, as described above, result_count and count are aggregated for each combination, and there may not be a single aggregation just for one particular metadata value. To get the total number of studies or results that belong to only a single metadata value, you can sum the value of count or result_count for each metadata entry that includes the single value you are interested in. Continuing the example above, the metadata_aggregations for your search may only include [\"North America\", \"United States\"] and [\"North America\", \"Canada\"], while you might only be interested in \"North America\". You can sum the result_count or count for the two former categories to arrive at the total for just \"North America\".
results is the list of all result types (with only question supported at the moment). Question type objects have the following fields. link is a URL field and is the deeplink to KnowledgeHound site page for this question. question is the name / title of the question.
study object contains the details of the study the question belongs to (you may get multiple questions with the same study information). Besides study name, date, and the link to KnowledgeHound's study details page, study object contains the metadata describing this study.
explanation is the list of objects that detail what matched the search query. Each object has a type, display name for the type, and the list of matches that are string snippets with marking the matched text. The possible values for type are question, question_responses, xtab_responses, xtabs, study_name, study_metadata, and study_number. For example, if you searched for paper products and that matched the question and study name you will get the following explanation:
`[ { \"type\": \"question\", \"display_name\": \"Question\", \"matches\": [\"we researched _paper products_ and\"] }, { \"type\": \"study_name\", \"display_name\": \"Study Name\", \"matches\": [\"Variances in _Paper Products_ Between\"] } ]`
\nduplicates is the list of questions with exact question text match, most often from different studies. It is common to ask the same question over time to see how consumer preferences change and for the best user experience we recommend that your UI shows the main question with a note that this question was asked in other studies. The questions that are included in this duplicates list will not appear in search results otherwise.
Finally, let's go over the use case where a user does a basic search, reviews search results, and then filters them down based on the metadata_aggregation. We want to highlight the suggested user experience in addition to the API integration.
\n![](\"https://s3-us-west-2.amazonaws.com/kh-api-docs/media/search_api.png\")
\n\n- \n
Once the user does a search and you get response back from
\n/search/__, show the results and filters to the user. Note, that filters are not required for the search functionality to work, however they let users hone in on the data they're really looking for. \nAfter the user selects and applies filter(s), re-execute the
\n/search/with the same query but includefiltersobject with the values frommetadata_aggregationsfrom the response JSON. \nFilters can be changed by the user as much as needed and
\n/search/needs to be re-executed for every filter change. \nParameters
\n- \n
- query (string) - URL encoded search query. Required field. \n
- type (string) - The desired result type to be returned. Only
questionis supported currently. Required field. \n group_duplicates(string) - Specifies whattyperesults to group for better user experience. Onlyquestionis supported currently. Required field. \npage_size(int) - The number of results to be returned. Optional. Defaults to 25. \n- page (int) - The page number to be returned. Optional. Defaults to 1. \n
- filters (json-decodable string) - A list of
filterobjects. Afilteris an object where the key is the field name and the selected values are an array of arrays. Example filter:{\"Geography\": [[\"Asia\", \"China\"], [\"Europe\"]}\n
\n
Search (GET)
\n- \n
Request
\n- \n
Headers
\n_`Authorization: Bearer ZnJlZDpmcmVk.KjKJHDFk.KJHksdf84`_\n\n\n
\nResponse 200 (application/json)
\n_`{ \"metadata_aggregations\": [ { \"name\": \"Geography\", \"values\": [ { \"value\": [ \"North America\", \"Canada\" ], \"count\": 3 }, { \"value\": [ \"North America\", \"United States\" ], \"count\": 10 } ] }, { \"name\": \"Brand\", \"values\": [ { \"value\": [ \"Brand 1\" ], \"count\": 7 }, { \"value\": [ \"Brand 2\" ], \"count\": 15 } ] } ], \"count\": 341, \"next\": \"http://clientname.knowledgehound.com/#/results?query=test&type=question&page=2&page_size=25\", \"previous\": null, \"results\": [ { \"id\": \"question_id\", \"link\": \"http://clientname.knowledgehound.com/#/analysis/question_id\", \"question\": \"What was the question?\", \"type\": \"question\", \"study\": { \"name\": \"Study name\", \"id\": \"STU001\", \"study_date\": \"2017-01-01\", \"link\": \"http://clientname.knowledgehound.com/studies/STU001\", \"metadata\": [ { \"name\": \"Geography\", \"value\": [[\"North America\", \"USA\"], [\"North America\", \"Canada\"]] }, { \"name\": \"Brand\", \"value\": [[\"Brand1\"], [\"Brand2\"]] } ] }, \"duplicates\": [ {Question object} ], \"explanation\": [ { \"type\": \"response\", \"display_name\": \"Question Responses\", \"matches\": [\"bla bla bla _this matched_ bla\", \"foo bar _this also matched_ bar foo\"] }, { \"type\": \"study_metadata\", \"display_name\": \"Study Metadata\", \"matches\": [\"bla bla bla _this matched_ bla\", \"foo bar _this also matched_ bar foo\"] } ] } ] }`_\n\n\nResponse 403 (text/plain)
\n_`You do not have permission to access this API`_\n\n\n
The Preview Image API provides images that represent items found in search results and is commonly used in conjunction with the data indexing webhook and the embedded analytics component to provide a custom or Knowledge Management solution.
\nWhen using the search data indexing capabilities, an image_url is provided to allow you to embed a preview image alongside the search result. KnowledgeHound provides two image sizes to facilitate different needs, thumbnail and full. The preview images use a 16:9 image ratio and the dimensions of each are:
\nThe image_url may be used in an authenticated GET with the KnowledgeHound JWT. The KnowledgeHound platform does not return the image directly from the image_url - it relies on its CDN to supply the image content.
\nThe preview API may return a JSON object containing the CDN URL (typically used in frontend applications and the default behavior) or a direct HTTP Redirect (302) with the CDN URL (typically backend solutions) by passing \"redirect=true\" as a query parameter.
\nThe CDN URL is a time limited signed URL (1 hour) - See the following flows:
\n![\"Typical](\"https://s3-us-west-2.amazonaws.com/kh-api-docs/media/search_preview_json.png\")
![\"Typical](\"https://s3-us-west-2.amazonaws.com/kh-api-docs/media/search_preview.png\")
Note: If the CDN does not have an image, a placeholder URL will be returned.
\nTo use the thumbnail image, pass a query parameter “size=thumbnail” to the preview endpoint.
\nThe redirected URL (shown as redirect_url below) may be used in the img tag or used in javascript to update the src of the img DOM element.
\n<img width=1280 src=”<preview_url>” />
\n","_postman_id":"23ccb496-a200-4777-9381-fdd0546dd1a6"},{"name":"Rate Controls","item":[],"id":"92361e90-5225-4fa2-a25f-4cd5d5ebcb38","description":"All KnowledgeHound APIs are subject to rate controls. Rate controls are applied on a per source IP basis. We allow 1000 API calls per second (per source IP).
\nIf you exceed this limit, the API will return an HTTP Status Code 429 (Too Many Requests) with a Retry-After header set to 300 (seconds)
\n","_postman_id":"92361e90-5225-4fa2-a25f-4cd5d5ebcb38"}]}