A survey’s machine readable information can be obtained through the PolisOrbis component “server” API using the APIs that returns the same data that build up the report (see example here) but as a json object.
This is the multi-page printable view of this section. Click here to print.
APIs
Access to Survey data from machines
1 - Comments API
get all survey’s comments and votes.
This API is used to get all survey’s comments and votes. This route gives the information contained in the report’s All Statement table, specifically for the STATEMENT and OVERALL columns.
This page contains an example of a request and a response given from the API, with a schema describing the significant fields that can be found in the response.
Example: Survey on ice cream
Request example
GET http://<polisorbis-server-domain>/api/v3/comments?moderation=true&mod_gt=-1&include_voting_patterns=true&conversation_id=<survey-id>
Response example
This JSON is partial: an actual response contains other fields that are not specified here. The following are the more commonly used properties.
[
{
"txt": "Mint chocolate chip is the perfect blend of refreshing mint and rich chocolate, making every scoop a delightful experience!",
"tid": 7,
"created": "1730728052425",
"is_seed": false,
"lang": null,
"pid": 7,
"mod": 1,
"agree_count": 6,
"disagree_count": 2,
"pass_count": 0,
"count": 8,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Strawberry ice cream is my favorite; its perfect balance of sweet and tart brings summer to every scoop!",
"tid": 2,
"created": "1730728043381",
"is_seed": false,
"lang": null,
"pid": 2,
"mod": 1,
"agree_count": 4,
"disagree_count": 0,
"pass_count": 4,
"count": 8,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Mint chocolate chip is the worst flavor; it ruins ice cream with its toothpaste-like taste and confusing chocolate chunks!",
"tid": 3,
"created": "1730728045074",
"is_seed": false,
"lang": null,
"pid": 3,
"mod": 1,
"agree_count": 2,
"disagree_count": 6,
"pass_count": 0,
"count": 8,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Chocolate fudge brownie is my favorite ice cream flavor; its rich chocolate and chewy brownie bites create the perfect indulgence!",
"tid": 1,
"created": "1730728041973",
"is_seed": false,
"lang": null,
"pid": 1,
"mod": 1,
"agree_count": 4,
"disagree_count": 2,
"pass_count": 2,
"count": 8,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Mint chocolate chip is the perfect blend of refreshing mint and rich chocolate—an irresistible combo in every scoop!",
"tid": 9,
"created": "1730728056829",
"is_seed": false,
"lang": null,
"pid": 9,
"mod": 0,
"agree_count": 6,
"disagree_count": 2,
"pass_count": 1,
"count": 9,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Mint chocolate chip is my favorite ice cream flavor; the refreshing mint paired with chocolatey goodness is simply irresistible!",
"tid": 5,
"created": "1730728048538",
"is_seed": false,
"lang": null,
"pid": 5,
"mod": 0,
"agree_count": 5,
"disagree_count": 3,
"pass_count": 1,
"count": 9,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Chocolate fudge brownie is my favorite ice cream flavor; it perfectly combines rich chocolate and chewy brownie pieces!",
"tid": 8,
"created": "1730728054437",
"is_seed": false,
"lang": null,
"pid": 8,
"mod": 0,
"agree_count": 3,
"disagree_count": 2,
"pass_count": 3,
"count": 8,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Cream ice cream: it's even in the name!",
"tid": 0,
"created": "1730727998217",
"is_seed": true,
"lang": null,
"pid": 0,
"mod": 1,
"agree_count": 7,
"disagree_count": 0,
"pass_count": 2,
"count": 9,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Chocolate fudge brownie is my favorite ice cream flavor—indulgent, rich, and perfectly satisfying every time!",
"tid": 6,
"created": "1730728050318",
"is_seed": false,
"lang": null,
"pid": 6,
"mod": 0,
"agree_count": 5,
"disagree_count": 2,
"pass_count": 1,
"count": 8,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Mint chocolate chip is the perfect balance of refreshing mint and rich chocolate in every delicious bite!",
"tid": 10,
"created": "1730728058984",
"is_seed": false,
"lang": null,
"pid": 10,
"mod": 0,
"agree_count": 5,
"disagree_count": 2,
"pass_count": 1,
"count": 8,
"conversation_id": "6njerhau9r"
...
},
{
"txt": "Mint chocolate chip is my favorite ice cream flavor—refreshing, creamy, and the perfect blend of sweet and cool!",
"tid": 4,
"created": "1730728046871",
"is_seed": false,
"lang": null,
"pid": 4,
"mod": 1,
"agree_count": 5,
"disagree_count": 3,
"pass_count": 0,
"count": 8,
"conversation_id": "6njerhau9r"
...
}
]
The following JSON schema provides a description of the fields listed above
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "array",
"items": {
"type": "object",
"properties": {
"txt": {
"type": "string",
"description": "The text content of the comment"
},
"tid": {
"type": "integer",
"description": "The unique identifier for the comment",
"example": 7
},
"created": {
"type": "string",
"description": "Timestamp of when the comment was created (epoch format)"
"example": "1730728052425"
},
"is_seed": {
"type": "boolean",
"description": "Indicates whether this comment is a seed comment"
},
"lang": {
"type": ["string", "null"],
"description": "Language code of the comment, if available",
"example": null
},
"pid": {
"type": "integer",
"description": "The unique identifier for the user that wrote the comment"
},
"mod": {
"type": "integer",
"description": "Moderator level or status associated with this response (0 - unmoderated; 1 - accepted)",
},
"agree_count": {
"type": "integer",
"description": "Number of participants who agree with this comment",
"minimum": 0
},
"disagree_count": {
"type": "integer",
"description": "Number of participants who disagree with this comment",
"minimum": 0
},
"pass_count": {
"type": "integer",
"description": "Number of participants who chose to pass on this comment",
"minimum": 0
},
"count": {
"type": "integer",
"description": "Total number of interactions with this comment",
"minimum": 0
},
"conversation_id": {
"type": "string",
"description": "Unique identifier for the survey this comment belongs to"
}
},
"required": [
"txt",
"tid",
"created",
"is_seed",
"lang",
"pid",
"mod",
"agree_count",
"disagree_count",
"pass_count",
"count",
"conversation_id"
]
}
}
2 - Conversations API
get all survey’s comments and votes.
This API is used to get a survey’s parameters and settings, such as the topic, the description and the participant count.
This page contains an example of a request and a response given from the API, with a schema describing the significant fields that can be found in the response.
Example: Survey on ice cream
Request example
GET http://<polisorbis-server-domain>/api/v3/conversations?conversation_id=<survey-id>
Response example
This JSON is partial: an actual response contains other fields that are not specified here. The following are the more commonly used properties.
{
"topic": "Ice cream",
"description": "What is your favorite ice cream flavor?",
"participant_count": 11,
"auth_needed_to_vote": false,
"auth_needed_to_write": false,
"modified": "1730728069749",
"created": "1730727970376",
"auth_opt_openid": false,
"ownername": "Anonymous",
"is_owner": false,
"conversation_id": "6njerhau9r"
}
The following JSON schema provides a description of the fields listed above
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"topic": {
"type": "string",
"description": "The topic of the survey"
},
"description": {
"type": "string",
"description": "A description of the survey"
},
"participant_count": {
"type": "integer",
"description": "The number of participants in the survey",
"minimum": 0
},
"auth_needed_to_vote": {
"type": "boolean",
"description": "Whether authentication is required to vote",
"example": false
},
"auth_needed_to_write": {
"type": "boolean",
"description": "Whether authentication is required to comment",
"example": false
},
"modified": {
"type": "string",
"description": "Timestamp of the last modification (epoch format)",
"example": "1730726628003"
},
"created": {
"type": "string",
"description": "Timestamp of the survey creation (epoch format)",
"example": "1730726395388"
},
"auth_opt_openid": {
"type": "boolean",
"description": "Whether OpenID authentication is enabled",
"example": false
},
"ownername": {
"type": "string",
"description": "Display name of the survey owner",
"example": "Anonymous"
},
"is_owner": {
"type": "boolean",
"description": "Whether the current user is the owner of the survey",
"example": false
},
"conversation_id": {
"type": "string",
"description": "Unique identifier for the survey conversation"
}
},
"required": [
"topic",
"description",
"participant_count",
"auth_needed_to_vote",
"auth_needed_to_write",
"modified",
"created",
"auth_opt_openid",
"ownername",
"is_owner",
"conversation_id"
]
}
3 - Math/PCA API
opunion groups and PCA analysis (advanced).
This API is used to get all grouping information produced by the PCA algorithm. This route gives the information contained in the reports All Statement table, specifically for the groups columns, as well as all other information in the report, although not in a machine readable format.
This page contains an example of a request and a response given from the API, with a schema describing the significant fields that can be found in the response (we will describe just the “group-votes”).
Example: Survey on ice cream
Request example
GET http://<polisorbis-server-domain>/api/v3/math/pca2?lastVoteTimestamp=0&conversation_id=<survey-id>
Response example
This JSON is partial: an actual response contains other fields that are not specified here. The following are the more commonly used properties.
{
"n": 10,
"tids": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
"mod-in": [7, 1, 4, 3, 2],
"n-cmts": 11,
"in-conv": [7, 1, 4, 6, 3, 2, 9, 5, 10, 8],
"mod-out": [],
"group-votes": {
"0": {
"votes": {
"0": {
"A": 5,
"D": 0,
"S": 5
},
"1": {
"A": 3,
"D": 0,
"S": 5
},
"2": {
"A": 4,
"D": 0,
"S": 5
},
"3": {
"A": 0,
"D": 5,
"S": 5
},
"4": {
"A": 3,
"D": 2,
"S": 5
},
"5": {
"A": 4,
"D": 2,
"S": 6
},
"6": {
"A": 5,
"D": 0,
"S": 5
},
"7": {
"A": 5,
"D": 0,
"S": 5
},
"8": {
"A": 3,
"D": 0,
"S": 5
},
"9": {
"A": 5,
"D": 0,
"S": 6
},
"10": {
"A": 4,
"D": 0,
"S": 5
}
},
"n-members": 7,
"id": 0
},
"1": {
"votes": {
"0": {
"A": 1,
"D": 0,
"S": 2
},
"1": {
"A": 0,
"D": 2,
"S": 2
},
"2": {
"A": 0,
"D": 0,
"S": 3
},
"3": {
"A": 2,
"D": 1,
"S": 3
},
"4": {
"A": 2,
"D": 1,
"S": 3
},
"5": {
"A": 1,
"D": 1,
"S": 3
},
"6": {
"A": 0,
"D": 2,
"S": 3
},
"7": {
"A": 1,
"D": 2,
"S": 3
},
"8": {
"A": 0,
"D": 2,
"S": 3
},
"9": {
"A": 1,
"D": 2,
"S": 3
},
"10": {
"A": 1,
"D": 2,
"S": 3
}
},
"n-members": 3,
"id": 1
}
},
"group-clusters": [
{
"id": 0,
"center": [-1.0729096569696, 0.0648828125178037],
"members": [3, 5, 6, 8, 9, 11]
},
{
"id": 1,
"center": [2.27779024648904, -0.4714273062786],
"members": [0, 10, 12]
}
],
"lastVoteTimestamp": 1730728069749,
"comment-priorities": {
"0": 7.18329418948676,
"1": 5.02356276961004,
"2": 1.15593698880458,
"3": 17.2447553781763,
"4": 22.6101843262524,
"5": 12.6261367613404,
"6": 12.013416432267,
"7": 15.8755313882589,
"8": 3.30400426158883,
"9": 9.97027674129075,
"10": 10.889094606946
}
}
The following JSON schema provides a description of the fields listed above
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"n": {
"type": "integer",
"description": "Number of users grouped by PCA (is not necessarily equal to participant count)"
},
"tids": {
"type": "array",
"items": { "type": "integer" },
"description": "Array of comment IDs in the survey"
},
"mod-in": {
"type": "array",
"items": { "type": "integer" },
"description": "Comment IDs accepted by moderators"
},
"n-cmts": {
"type": "integer",
"description": "Number of comments in the survey"
},
"in-conv": {
"type": "array",
"items": { "type": "integer" },
"description": "Array of user IDs who participated in the survey"
},
"mod-out": {
"type": "array",
"items": { "type": "integer" },
"description": "Comment IDs rejected by moderators"
},
"group-votes": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"votes": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"A": {
"type": "integer",
"description": "Agree votes count"
},
"D": {
"type": "integer",
"description": "Disagree votes count"
},
"S": {
"type": "integer",
"description": "Sum count (agree + disagree + pass)"
}
},
"required": ["A", "D", "S"]
},
"description": "Vote breakdown per topic per group"
},
"n-members": {
"type": "integer",
"description": "Number of members in the group",
"example": 7
},
"id": {
"type": "integer",
"description": "Unique identifier for the group",
"example": 0
}
},
"required": ["votes", "n-members", "id"]
},
"description": "Votes breakdown by group"
},
"group-clusters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Cluster ID"
},
"center": {
"type": "array",
"items": { "type": "number" },
"description": "Coordinates of the cluster center in PCA space"
},
"members": {
"type": "array",
"items": { "type": "integer" },
"description": "List of user IDs in the cluster"
}
},
"required": ["id", "center", "members"]
},
"description": "Array of clusters with PCA centers and member IDs"
},
"lastVoteTimestamp": {
"type": "string",
"description": "Timestamp of the last vote (epoch format)",
"example": "1730728069749"
},
"comment-priorities": {
"type": "object",
"additionalProperties": {
"type": "number",
"description": "Priority score for each comment"
},
"description": "Mapping of comment IDs to priority scores: the highest priority comments are visualized first"
}
},
"required": [
"n",
"tids",
"mod-in",
"n-cmts",
"in-conv",
"mod-out",
"group-votes",
"group-clusters",
"lastVoteTimestamp",
"comment-priorities"
]
}