Get hands-on with PolisOrbis.

• 1: Try PolisOrbis
• 1.1: PolisOrbis sandbox privacy policy
• 1.2: Term of use of PolisOrbis sandbox
• 2: Using a managed service
• 3: Deploy
• 3.1: Configuration
• 4: Best Practices
• 5: APIs
• 5.1: Comments API
• 5.2: Conversations API
• 5.3: Math/PCA API

1 - Try PolisOrbis

You can try PolisOrbis at https://demo.polisorbis.eu/ . This is a sandbox installation that is not suitable for production.

The PolisOrbis sandbox has the following limitations:

• its database it is cleared every week
• it runs the latest code version (potentialli instable)
• e-mail dispaching and verification is disabled
• no Open Id SSO nor EUDI authentication is available

The sandbox service is installed and maintained using the Deploy Blueprint infrastructure as a code, using the aws-ecs2 manifest under the responsibility of Copernicani association.

1.1 - PolisOrbis sandbox privacy policy

This privacy policy (this “Policy”) describes the collection of personal information by the Copernicani Association, a nonprofit association (“the Copernicani Association,” “we,” or “us”) from users of our Web site at “https://demo.polisorbis.eu/" (the “Site”), as well as all related applications, widgets, software, tools, and other services provided by us and on which a link to this Policy is displayed (collectively, together with the Site, our “Services”). This Policy also describes our use and disclosure of such information. By using our Services, you consent to the collection, use, and disclosure of personal information in accordance with this Policy. This Policy is incorporated by reference into the Terms of Use and subject to the provisions of the Terms of Use. If you reside in the European Economic Area or Switzerland, please see International Visitors and Supplemental Notice to EU Data Subjects, below, which contains information about your rights and how to contact us.

Personal Information

“Personal Information” as used in this Policy, is information that specifically identifies an individual, such as an individual’s name, or e-mail address.

Personal Information does not include “aggregate” or other non-personally identifiable information. Aggregate information is information that we collect about a group or category of products, services, or users that is not personally identifiable or from which individual identities are removed. We may use and disclose aggregate information, and other non-personally identifiable information, for various purposes.

Collection of Information

Collection of Voluntarily-Provided Information

We collect Personal Information that our users provide to us in a variety of ways on our Services. These include the following:

1. User Accounts and Profiles.   Our Services may give you the ability to register for a Company account or to create and update a user profile on the applicable Service. If we offer user account or profile functionality on the Services, we will collect the Personal Information that you provide to us in the course of registering for an account or creating or updating a user profile. This information may include e-mail address, and other information about you. We may indicate that some personal information is required for you to register for the account or to create the profile, while some is optional.

2. Interactive Features.   Our Services may contain interactive functionality that allows you to engage with other users on the Services, post questions to other users, answer questions of other users, post comments to questions and other forums, to upload other content (the ‘User Materials’), participate in surveys, and otherwise to interact with the Services and with other users. If you use any interactive functionality on our Services that request or permit you to provide us with personal information (including, for example, any services that allow you to post User Materials on any of our Services), we collect the Personal Information that you provide to us in the course of using these interactive features.

3. Correspondence.   If you contact us by e-mail, using a contact form on the Services, or by mail, fax, or other means, we collect the Personal Information contained within, and associated with, your correspondence.

Automatically Collected Information

When you visit our Services, some information is collected automatically. For example, when you access our Services, we may automatically collect your browser’s Internet Protocol (IP) address, your browser type, the nature of the device from which you are visiting the Services (e.g., a personal computer or a mobile device), the identifier for any handheld or mobile device that you may be using, the Web site that you visited immediately prior to accessing any Web-based Services, the actions you take on our Services, and the content, features, and activities that you access and participate in on our Services. We may collect this information automatically using technologies such as cookies. We use automatically-collected information to administer, operate, and improve the Website and our other services and systems. We may use and disclose information collected by automatic means in aggregate form or otherwise in a non-personally identifiable form.

Information from Other Sources

We may receive information about you, including Personal Information, from third parties and third party application programming interfaces, as well as authentication service providers, and may combine this information with other Personal Information we maintain about you. If we do so, this Policy governs any combined information that we maintain in personally identifiable format.

Use of Personal Information

We use Personal Information to provide services and information that you request; to enhance, improve, operate, and maintain our Services, our programs, services, Web sites, and other systems; to prevent fraudulent use of our Services and other systems; to prevent or take action against activities that are, or may be, in violation of our Terms of Use or applicable law; to tailorcontent, and other aspects of your experience on and in connection with the Services; to maintain a record of our dealings with you; for other administrative purposes; and for any other purposes that we may disclose to you at the point at which we request your Personal Information, and pursuant to your consent.

We may also use your Personal Information:

• To process information you have directed us to process.
• To communicate with you (such as through email) about services you have subscribed for, changes to our policies (such as this Privacy Policy and our Terms of Service), or to provide important notices.
• To provide information or content that you’ve subscribed to receive.
• To set up and maintain your account, and to do all other things required for providing our services, such as backing up and restoring your data.
• To understand how our services are used, to monitor and prevent problems with our Site and/or services, and to improve our Site and/or services.
• To provide customer support.
• To update, modify, and analyze our records, and to identify prospective customers with their consent.
• To identify and analyze trends, track user activity on the Site, and understand what Site visitors are looking for with their consent where necessary.
• To create, monitor, and improve marketing campaigns with visitor consent.
• To inform you of new services, upcoming events, offers, and other information that we believe will be of interest to you, with your consent.
• To ask you to participate in a poll or survey, or to request feedback about our services, with your consent.
• For any other purpose that we describe to you when you provide information to us and for which you provide your consent.

Disclosure of Personal Information

Except as described in this Policy, we will not disclose your Personal Information that we collect on the Services to third parties without your consent. We may disclose information to third parties if you consent to us doing so, as well as in the following circumstances:

Service Providers

We may disclose Personal Information to third-party service providers (e.g., data storage and processing resources) that assist us in our work. We limit the Personal Information provided to these service providers to that which is reasonably necessary for them to perform their functions, and we require them to agree to maintain the confidentiality of such Personal Information.

Technical Infrastructure

• We use AMAZON AWS’s cloud services, including a hosted Postgres database, where we store all information. Information about how AWS handles: https://aws.amazon.com/privacy/

To Protect our Interests

We also disclose Personal Information if we believe that doing so is legally required, or is in our interest to protect our property or other legal rights (including, but not limited to, enforcement of our agreements), or the rights or property of others, or otherwise to help protect the safety or security of our Services and other users of the Services.

Choice

We may allow you to post User Materials in an anonymous or non-anonymous manner, which may affect which User Materials may be shared with third party advertisers. Please review the relevant settings before posting User Materials. Please note that some interactions on the Service are dedicated non-anonymous by the moderators of those interactions. You will be notified that a given interaction is non-anonymous before posting any User Materials to such an interaction.

Additionally, we may allow you to view and modify settings relating to the nature and frequency of promotional communications that you receive from us. Please be aware that if you opt-out of receiving commercial e-mail from us, it may take up to ten business days for us to process your opt-out request, and you may receive commercial e-mail from us during that period. Additionally, even after you opt-out from receiving commercial messages from us, you will continue to receive administrative messages from us regarding our Services.

Access

If we offer the ability to create temporary user accounts or profiles on our Services, you may have the ability to access and update many categories of personal information that you provide to us by logging in to your account and accessing your account settings. Your data will be cleared at leas every week.

Links

The Services may contain links to other Web sites, products, or services that we do not own or operate. The Services may contain links to Third-Party Sites such as social networking services. If you choose to visit or use any Third-Party Sites or products or services available on or through such Third-Party Sites, please be aware that this Policy will not apply to your activities or any information you disclose while using those Third-Party Sites or any products or services available on or through such Third-Party Sites. We are not responsible for the privacy practices of these Third-Party Sites or any products or services on or through them. Additionally, please be aware that the Services may contain links to Web sites and services that we operate but that are governed by different privacy policies. We encourage you to carefully review the privacy policies applicable to any Web site or service you visit other than the Services before providing any Personal Information on them.

Updates to this Policy

We may occasionally update this Policy. When we do, we will also revise the ’last updated’ date at the beginning of the Policy. Your continued use of our Services after such changes will be subject to the then-current policy. If we change this Policy in a manner that is materially less restrictive of our use or disclosure of your Personal Information, we will use reasonable efforts to notify you of the change and to obtain your consent prior to applying the change to any Personal Information that we collected from you prior to the date the change becomes effective. We encourage you to periodically review this Policy to stay informed about how we collect, use, and disclose personal information.

Contacting Us

If you have any questions or comments about this Policy, please contact us using the following contact information available on https://copernicani.it/ site

1.2 - Term of use of PolisOrbis sandbox

The service available at https://demo.polisorbis.eu (the “sandbox”) is managed by the Copernicani Association ( “Copernicani” ) on behalf of the Orbis Project (“Orbis”).

The objective of the sandbox is to allow people to gain an idea of how the PolisOrbis project works in a simulated environment that is reset every week.

YOU MUST NOT USE the sandbox for any real poll.

All data, polls and registrations, in the sandbox is cleared at least every week, but more frequent clearing could happens.

Eligibility

You must be at least sixteen (16) years of age to use the Service. By agreeing to these Terms, you represent and warrant to us: (i) that you are at least sixteen (16) years of age; (ii) that you have not previously been suspended or removed from the Service; and (iii) that your registration and your use of the Service is in compliance with any and all applicable laws and regulations. If you are using the Service on behalf of an entity, organization, or company, you represent and warrant that you have the authority to bind such organization to these Terms and you agree to be bound by these Terms on behalf of such organization.

Accounts and Registration

To access some features of the Service, you must register for an account. When you register for an account, you may be required to provide us with some information about yourself as further described in our Privacy Policy. You are solely responsible for maintaining the confidentiality of your account and password. Copernicani will not be held liable for actions which occur under your account due to your credentials having been discovered due to no fault of PolisOrbis project.

If you have reason to believe that your account is no longer secure, then you must immediately notify us at privacy@copernicani.it.

User Content

User Content Generally

Certain features of the Service may permit users to post content, including messages, questions, responses, data, text, and other types of works (collectively, “User Content”) and to publish User Content on the Service. You retain copyright and any other proprietary rights that you may hold in the User Content that you post to the Service, but grant the limited licenses below.

Limited License Grant to the Copernicani Association

By posting or publishing User Content, you grant Orbis Project a worldwide, irrevocable, perpetual, non-exclusive, royalty-free, fully-paid-up right and license (with the right to sublicense) to host, store, transfer, display, perform, reproduce, modify, and distribute your User Content, in whole or in part, in any media formats and through any media channels (now known or hereafter developed). Any such use of your User Content by Orbis project may be without any compensation paid to you.

Limited License Grant to Other Users

By posting User Content or sharing User Content with another user of the Service, you hereby grant to other users of the Service a non-exclusive license to access and use such User Content as permitted by these Terms and the functionality of the Service.

User Content Representations and Warranties

You are solely responsible for your User Content and the consequences of posting or publishing User Content. By posting and publishing User Content, you affirm, represent, and warrant that: - you are the creator and owner of, or have the necessary licenses, rights, consents, and permissions to use and to authorize Orbis project and users of the Service to use and distribute your User Content as necessary to exercise the licenses granted by you in this Section and in the manner contemplated by the Copernicani Association and these Terms; - and your User Content, and the use thereof as contemplated herein, does not and will not: (i) infringe, violate, or misappropriate any third-party right, including any copyright, trademark, patent, trade secret, moral right, privacy right, right of publicity, or any other intellectual property or proprietary right; - or (ii) slander, defame, libel, or invade the right of privacy, publicity or other property rights of any other person.

User Content Disclaimer

We are under no obligation to edit or control User Content that you or other users post or publish, and will not be in any way responsible or liable for User Content. The Copernicani Association may, however, at any time and without prior notice, screen, remove, edit, or block any User Content that in our sole judgment violates these Terms or is otherwise objectionable. You understand that when using the Service you will be exposed to User Content from a variety of sources and acknowledge that User Content may be inaccurate, offensive, indecent or objectionable. You agree to waive, and hereby do waive, any legal or equitable rights or remedies you have or may have against the Copernicani Association with respect to User Content. We expressly disclaim any and all liability in connection with User Content. If notified by a user or content owner that User Content allegedly does not conform to these Terms, we may investigate the allegation and determine in our sole discretion whether to remove the User Content, which we reserve the right to do at any time and without notice. For clarity, Copernicani Association does not permit copyright-infringing activities on the Service.

DMCA Takedown Requests

If you believe your copyright-protected work was posted to our Service without authorization, you may notify in accordance with the Digital Millenium Copyright Act at the following email address: privacy@copernicani.it.

Prohibited Conduct

BY USING THE SERVICE YOU AGREE NOT TO:

• use the service for any purpose different to test the PolisOrbis functionalities
• use the Service for any illegal purpose, or in violation of any local, state, national, or international law;
• violate, or encourage others to violate, the rights of third parties, including by infringing or misappropriating third party intellectual property rights;
• post, upload, or distribute any User Content or other content that is unlawful, defamatory, libelous, inaccurate, or that a reasonable person could deem to be objectionable, profane, indecent, pornographic, harassing, threatening, embarrassing, hateful, or otherwise inappropriate;
• interfere with security-related features of the Service, including without limitation by (i) disabling or circumventing features that prevent or limit use or copying of any content, or (ii) reverse engineering or otherwise attempting to discover the source code of the Service or any part thereof except to the extent that such activity is expressly permitted by applicable law;
• interfere with the operation of the Service or any user’s enjoyment of the Service, including without limitation by (i) uploading or otherwise disseminating viruses, adware, spyware, worms, or other malicious code, (ii) making unsolicited offers or advertisements to other users of the Service, (iii) attempting to collect, personal information about users or third parties without their consent; or (iv) interfering with or disrupting any networks, equipment, or servers connected to or used to provide the Service, or violating the regulations, policies, or procedures of such networks, equipment, or servers;
• perform any fraudulent activity including impersonating any person or entity, claiming false affiliations, accessing the Service accounts of others without permission, or falsifying your age or date of birth;
• sell or otherwise transfer the access granted herein or any Materials (as defined in Section below) or any right or ability to view, access, or use any Materials; or
• attempt to do any of the foregoing in this Section , or assist or permit any persons in engaging in any of the activities described in this Section.

Termination of Use; Discontinuation and Modification of the Service

If you violate any provision of these Terms, your permission to use the Service will be terminated. Additionally, COpernicani Association, in its sole discretion may terminate your user account on the Service or suspend or terminate your access to the Service at any time, with or without notice. We also reserve the right to modify or discontinue the Service at any time (including, without limitation, by limiting or discontinuing certain features of the Service) without notice to you. We will have no liability whatsoever on account of any change to the Service or any suspension or termination of your access to or use of the Service. Your account is automatically terminated every service reset (one a week).

Privacy Policy; Additional Terms

Please read Privacy Policy carefully for information relating to our collection, use, storage and disclosure of your personal information. The Privacy Policy is hereby incorporated by reference into, and made a part of, these Terms.

Additional Terms

Your use of the Service is subject to any and all additional terms, policies, rules, or guidelines applicable to the Service or certain features of the Service that we may post on or link to on the Service (the “Additional Terms”), such as end-user license agreements for any downloadable applications that we may offer, or rules applicable to particular features or content on the Service, subject to Section 9 below. All such Additional Terms are hereby incorporated by reference into, and made a part of, these Terms.

Modification of these Terms

We reserve the right, at our discretion, to change these Terms on a going-forward basis at any time. Please check these Terms periodically for changes. In the event that a change to these Terms materially modifies your rights or obligations, you will be required to accept such modified terms in order to continue to use the Service. Material modifications are effective upon your acceptance of such modified Terms. Immaterial modifications are effective upon publication. For the avoidance of doubt, disputes arising under these Terms will be resolved in accordance with these Terms in effect that the time the dispute arose.

Indemnity

You agree that you will be responsible for your use of the Service, and you agree to defend, indemnify, and hold harmless The Copernicani Association and its officers, directors, employees, consultants, affiliates, subsidiaries and agents (collectively, the The Orbis Project) from and against any and all claims, liabilities, damages, losses, and expenses, including reasonable attorneys’ fees and costs, arising out of or in any way connected with (i) your access to, use of, or alleged use of the Service; (ii) your violation of these Terms or any representation, warranty, or agreements referenced herein, or any applicable law or regulation; (iii) your violation of any third-party right, including without limitation any intellectual property right, publicity, confidentiality, property or privacy right; or (iv) any disputes or issues between you and any third party. We reserve the right, at our own expense, to assume the exclusive defense and control of any matter otherwise subject to indemnification by you (and without limiting your indemnification obligations with respect to such matter), and in such case, you agree to cooperate with our defense of such claim.

Disclaimers

No Warranties THE SERVICE AND ALL MATERIALS AND CONTENT AVAILABLE THROUGH THE SERVICE ARE PROVIDED “AS IS” AND ON AN “AS AVAILABLE” BASIS, WITHOUT WARRANTY OR CONDITION OF ANY KIND, EITHER EXPRESS OR IMPLIED. THE MATH & DEMOCRACY ENTITIES SPECIFICALLY (BUT WITHOUT LIMITATION) DISCLAIM ALL WARRANTIES OF ANY KIND, WHETHER EXPRESS OR IMPLIED, RELATING TO THE SERVICE AND ALL MATERIALS AND CONTENT AVAILABLE THROUGH THE SERVICE, INCLUDING BUT NOT LIMITED TO (i) ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, QUIET ENJOYMENT, OR NON-INFRINGEMENT; AND (ii) ANY WARRANTIES ARISING OUT OF COURSE OF DEALING, USAGE, OR TRADE. THE MATH & DEMOCRACY ENTITIES DO NOT WARRANT THAT THE SERVICE OR ANY PART THEREOF, OR ANY MATERIALS OR CONTENT OFFERED THROUGH THE SERVICE, WILL BE UNINTERRUPTED, SECURE, OR FREE OF ERRORS, VIRUSES, OR OTHER HARMFUL COMPONENTS, AND DO NOT WARRANT THAT ANY OF THE FOREGOING WILL BE CORRECTED. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, OBTAINED BY YOU FROM THE SERVICE OR ANY MATERIALS OR CONTENT AVAILABLE ON OR THROUGH THE SERVICE WILL CREATE ANY WARRANTY REGARDING ANY OF THE MATH & DEMOCRACY ENTITIES OR THE SERVICE THAT IS NOT EXPRESSLY STATED IN THESE TERMS. YOU ASSUME ALL RISK FOR ALL DAMAGES THAT MAY RESULT FROM YOUR USE OF OR ACCESS TO THE SERVICE, YOUR DEALINGS WITH OTHER SERVICE USERS, AND ANY MATERIALS OR CONTENT AVAILABLE THROUGH THE SERVICE. YOU UNDERSTAND AND AGREE THAT YOU USE THE SERVICE AND USE, ACCESS, DOWNLOAD, OR OTHERWISE OBTAIN MATERIALS OR CONTENT THROUGH THE SERVICE AND ANY ASSOCIATED SITES OR SERVICES AT YOUR OWN DISCRETION AND RISK, AND YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR PROPERTY (INCLUDING YOUR COMPUTER SYSTEM USED IN CONNECTION WITH THE SERVICE) OR LOSS OF DATA THAT RESULTS FROM THE USE OF THE SERVICE OR THE DOWNLOAD OR USE OF SUCH MATERIALS OR CONTENT. SOME JURISDICTIONS MAY PROHIBIT A DISCLAIMER OF WARRANTIES AND YOU MAY HAVE OTHER RIGHTS THAT VARY FROM JURISDICTION TO JURISDICTION.

Limitation of Liability

IN NO EVENT WILL THE POLISORBIS AUTHORS, COPERNICANI AND ORBIS PROJECT BE LIABLE TO YOU FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, GOODWILL, USE, DATA, OR OTHER INTANGIBLE LOSSES) ARISING OUT OF OR RELATING TO YOUR ACCESS TO OR USE OF, OR YOUR INABILITY TO ACCESS OR USE, THE SERVICE OR ANY MATERIALS OR CONTENT ON THE SERVICE, WHETHER BASED ON WARRANTY, CONTRACT, TORT (INCLUDING NEGLIGENCE), STATUTE OR ANY OTHER LEGAL THEORY, WHETHER OR NOT THE MATH & DEMOCRACY ENTITIES HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES. ACCORDINGLY, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. EACH PROVISION OF THESE TERMS THAT PROVIDES FOR A LIMITATION OF LIABILITY, DISCLAIMER OF WARRANTIES, OR EXCLUSION OF DAMAGES IS TO ALLOCATE THE RISKS UNDER THESE TERMS BETWEEN THE PARTIES. THIS ALLOCATION IS AN ESSENTIAL ELEMENT OF THE BASIS OF THE BARGAIN BETWEEN THE PARTIES. EACH OF THESE PROVISIONS IS SEVERABLE AND INDEPENDENT OF ALL OTHER PROVISIONS OF THESE TERMS. THE LIMITATIONS IN THIS SECTION 13 WILL APPLY EVEN IF ANY LIMITED REMEDY FAILS OF ITS ESSENTIAL PURPOSE.

Governing Law

These Terms shall be governed by the laws of Italy in the EU without regard to conflict of law principles. To the extent that any lawsuit or court proceeding is permitted hereunder, you and Copernicani Association agree to submit to the personal and exclusive jurisdiction of the courts of Milan, ITALY for the purpose of litigating all such disputes. We operate the Service from our offices in Milan, and we make no representation that Materials included in the Service are appropriate or available for use in other locations.

General

These Terms, together with the Privacy Policy and any other agreements expressly incorporated by reference herein, constitute the entire and exclusive understanding and agreement between you and Copernicani Association regarding your use of and access to the Service, and except as expressly permitted above may be amended only by a written agreement signed by authorized representatives of all parties to these Terms. You may not assign or transfer these Terms or your rights hereunder, in whole or in part, by operation of law or otherwise, without our prior written consent. We may assign these Terms at any time without notice. The failure to require performance of any provision will not affect our right to require performance at any time thereafter, nor shall a waiver of any breach or default of these Terms or any provision of these Terms constitute a waiver of any subsequent breach or default or a waiver of the provision itself. Use of section headers in these Terms is for convenience only and shall not have any impact on the interpretation of particular provisions. In the event that any part of these Terms is held to be invalid or unenforceable, the unenforceable part shall be given effect to the greatest extent possible and the remaining parts will remain in full force and effect. Upon termination of these Terms, any provision that by its nature or express terms should survive will survive such termination or expiration, including, but not limited to, Sections 1, 3,.

Dispute Resolution and Arbitration

Generally

In the interest of resolving disputes between you and the Copernicani Association in the most expedient and cost effective manner, you and the Copernicani Association agree that any and all disputes arising in connection with these Terms shall be resolved by binding arbitration. Arbitration is more informal than a lawsuit in court. Arbitration uses a neutral arbitrator instead of a judge or jury, may allow for more limited discovery than in court, and can be subject to very limited review by courts. Arbitrators can award the same damages and relief that a court can award. Our agreement to arbitrate disputes includes, but is not limited to all claims arising out of or relating to any aspect of these Terms, whether based in contract, tort, statute, fraud, misrepresentation or any other legal theory, and regardless of whether the claims arise during or after the termination of these Terms. YOU UNDERSTAND AND AGREE THAT, BY ENTERING INTO THESE TERMS, YOU AND COPERNICANI ASSOCIATION ARE EACH WAIVING THE RIGHT TO A TRIAL BY JURY OR TO PARTICIPATE IN A CLASS ACTION.

Exceptions

Notwithstanding, we both agree that nothing herein will be deemed to waive, preclude, or otherwise limit either of our right to (i) bring an individual action in small claims court, (ii) pursue enforcement actions through applicable federal, state, or local agencies where such actions are available, (iii) seek injunctive relief in a court of law, or (iv) to file suit in a court of law to address intellectual property infringement claims.

Consent to Electronic Communications

By using the Service, you consent to receiving certain electronic communications from us as further described in the service Privacy Policy. Please read the service Privacy Policy to learn more about your choices regarding our electronic communications practices. You agree that any notices, agreements, disclosures, or other communications that we send to you electronically will satisfy any legal communication requirements, including that such communications be in writing.

Contact Information

The services hereunder are offered by the Copernicani Association, located at PPiazza Repubblica, 1 - 20121 Milano - ITALY You may contact us by sending correspondence to the foregoing address using one of the meand described in the the https://copernicani.it site.

2 - Using a managed service

If you do not want to create your instance of poll web application, you can consider to use one of the services provided by some associations.

The https://polisorbis.copernicani.it/ is the reference deployment of the PolisOrbis codebase, it is is provided by the Copernicani Association, it is scalable, GDPR compliant and requires a signed agreement with the Copernicani Association before to be used.

Besides the PolisOrbis, https://pol.is/ services that is the reference deployment for the original Polis project. This services is provided by The Computational Democracy Project and suitable for small polls and it is free upon registration but it is based in US and it is not GDPR compliant.

See more info in the Best Practice section

3 - Deploy

PolisOrbis is a cloud-native application that consists of a set of containers built with Docker and some backing services running by a container orchestrator in a cloud infrastructure.

The type of infrastructure and orchestration depends mainly on the audience size for the polls you want to conduct. The PolisOrbis project natively supports three different types of deployment:

• A scalable production deployment, suitable for large polls involving many thousands of users (potentially millions).
• A minimal production deployment, suitable for test and small polls involving up to less than 200 users and where security and availability is not critical.
• A local deployment aimed at code developers.

For the first two types of deployment, the code (Infrastructure as Code) is provided directly using Terraform and ready to run on the AWS Cloud. The deploy blueprints are contained in the deployment repository

The third type of deployment is described in the readme of the PolisOrbis codebase.

If you want to deploy PolisOrbis in different infrastructure you can refer to the code in the deployment repository as an example.

All deploy blueprints is released with a Free Open Source License

3.1 - Configuration

WARNING: this page is just for advanced configuration options. You normally do not need to change defauts values

PolisOrbis application follows the twelve-factor app methodology storing config in the environment.

Overview

First things first, it helps to understand a bit how the system is set up.

While this document will try to outline some of the more important configuration options, you’ll need to see the individual READMEs for more detailed descriptions of how to configure these components.

Environment variables

Quickstart

In development, the default values of example.env should work as-is.

cp example.env .env

By default, docker compose will look for and use an .env file if one exists. However, any value present in your environment or passed in on the command line will overwrite those in the file. Thus you should be able to set your configuration values in whatever way suits your given scenario. (A plain text .env file is not always appropriate in production deployments.)

If you are running these applications without Docker, just make sure that any environment variables you need are set in the environment where the application is running.

If you are doing development on a url other than localhost or localhost:5000, you need to update the API_DEV_HOSTNAME value to your development hostname:port, e.g. myhost:8000 or api.testserver.net. DEV_MODE should be true.

If you are deploying to a custom domain (not pol.is) then you need to update both the API_PROD_HOSTNAME and DOMAIN_OVERRIDE values to your custom hostname (omitting http(s):// protocol). DEV_MODE should be false.

General Settings

• ADMIN_UIDS an array of user UUIDs for site admins. These users will have moderator capabilities on all conversations hosted on the site.
• EMAIL_TRANSPORT_TYPES comma-separated list of email services to use (see Email Transports below)
• GIT_HASH Set programmatically using git rev-parse HEAD (e.g. in Makefile) to tag docker container versions and other release assets. Can be left blank.
• MATH_ENV Set to prod (default), preprod, dev or arbitrary feature flag. In cases where a single database is used for multiple environments, this value is used by the API service to request the correct data. (Using a single DB for multiple environments in this fashion is no longer recommended, and so the default value of prod is recommended.)
• SERVER_ENV_FILE The name of an environment file to be passed into the API Server container by docker compose. Defaults to .env if left blank. Used especially for building a test version of the project for end-to-end testing.
• SERVER_LOG_LEVEL Used by Winston.js in the API server to determine how much logging to output. Reasonable values are debug, info, and error. Defaults to info.

Database

• READ_ONLY_DATABASE_URL (optional) Database replica for reads.
• POSTGRES_DB database name (e.g. PolisOrbis-dev)
• POSTGRES_HOST database host (e.g. postgres:5432 if using docker compose, localhost:5432 if using local db)
• POSTGRES_PASSWORD database password
• POSTGRES_PORT typically 5432
• POSTGRES_USER typically postgres. Any username will be used by the docker container to create a db user.
• DATABASE_URL should be the combination of above values, postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}/${POSTGRES_DB}

Docker Concerns

• TAG used by COMPOSE_PROJECT_NAME below. Defaults to dev.
• COMPOSE_PROJECT_NAME Used by docker compose to label containers and volumes. Useful in development if you are (re)-building and deleting groups of docker assets.

Ports

• API_SERVER_PORT typically 5000. Used internally within a docker network and/or behind a proxy. A PORT value is used as a fallback if API_SERVER_PORT is not set (for Heroku compatibility).
• HTTP_PORT typically 80. Port exposed by Nginx reverse proxy.
• HTTPS_PORT typically 443. Port exposed by Nginx reverse proxy.
• STATIC_FILES_PORT typically 8080. Used internally within a docker network and/or behind a proxy.
• STATIC_FILES_ADMIN_PORT same as STATIC_FILES_PORT unless you are hosting client-admin separately from file-server. Useful in local development.
• STATIC_FILES_PARTICIPATION_PORT same as STATIC_FILES_PORT unless you are hosting client-participation separately from file-server. Useful in local development.

Email Addresses

• ADMIN_EMAIL_DATA_EXPORT email address from which data export emails are sent.
• ADMIN_EMAIL_DATA_EXPORT_TEST email address to receive periodic export test results, if configured below.
• ADMIN_EMAIL_EMAIL_TEST email address to receive backup email system test.
• ADMIN_EMAILS array of email addresses to receive team notifications.
• POLIS_FROM_ADDRESS email address from which other emails are sent.

Boolean Flags

(All can be left blank, or false)

• BACKFILL_COMMENT_LANG_DETECTION Set to true, if Comment Translation was enabled, to instruct the server upon the next initialization (reboot) to backfill detected language of stored comments. Default false.
• CACHE_MATH_RESULTS Set this to true to instruct the API server to use LRU caching for results from the math service. Default is true if left blank.
• DEV_MODE Set this to true in development and false otherwise. Used by API Server to make a variety of assumptions about HTTPS, logging, notifications, etc.
• RUN_PERIODIC_EXPORT_TESTS Set this to true to run periodic export tests, sent to the ADMIN_EMAIL_DATA_EXPORT_TEST address.
• SERVER_LOG_TO_FILE Set this to true to tell Winston.js to also write log files to server/logs/. Defaults to false. Note that if using docker compose, server/logs is mounted as a persistent volume.
• SHOULD_USE_TRANSLATION_API Set this to true if using Google translation service. See Enabling Comment Translation below.

URL/Hostname Settings

• API_DEV_HOSTNAME typically localhost unless you are running a development instance elsewhere.
• API_PROD_HOSTNAME the hostname of your site (e.g. pol.is, or example.com). Should match DOMAIN_OVERRIDE. (In the future these two options may be combined into one.)
• DOMAIN_OVERRIDE the hostname of your site. Should match API_PROD_HOSTNAME.
• DOMAIN_WHITELIST_ITEM_01 - 08 up to 8 possible additional whitelisted domains for client applications to make API requests from. Typical setups that use the same URL for the API service as for the public-facing web sites do not need to configure these.
• EMBED_SERVICE_HOSTNAME should match API_DEV_HOSTNAME in production, or API_DEV_HOSTNAME in development. Embedded conversations make API requests to this host.
• SERVICE_URL used by client-report to make API calls. Only necessary if client-report is hosted separately from the API service. Can be left blank.
• STATIC_FILES_HOST Used by the API service to fetch static assets (the compiled client applications) from a static file server. Within the docker compose setup this is file-server, but could be an external hostname, such as a CDN or S3 bucket.

Third Party API Credentials

(All are optional, and omitting them will disable the related feature.)

• AWS_REGION Used for S3 data import/export.
• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY If using Amazon SES as an email transport.
• MAILGUN_API_KEY, MAILGUN_DOMAIN If using Mailgun as an email transport.

User interface

PolisOrbis supports a configurable UI in order to be deployed by a specific service provider. These variables affects the UI:

• P_LOGO_ICO_URL: [URL] defaults to docs/polisorbis-logo-square.png
• P_LOGO_URL: [URL] defaults to docs/polisorbis-logo.png
• P_TITLE: [URL] (defaults to “PolisOrbis”
• P_CLAIM: [URL] (defaults to “Input Crowd, Output Meaning”
• P_DESCRIPTION:[String] defaults to “PolisOrbis is a real-time system for gathering, analyzing and understanding what large groups of people think in their own words, enabled by advanced statistics and machine learning”
• sign_in
• P_DOC_URL: [String] defaults to “Read more about [PolisOrbis](https://doc.polisorbis.copernicani.it]”
• P_REPO_URL:[String] defaults to “Explore the code and join the developer community on GitLab”
• P_TOS_URL: [HTML] defaults to “Term of services”
• P_PRIVACY_POLICY_URL: [HTML] defaults to “Privacy policy”

Deprecated

• ENCRYPTION_PASSWORD_00001 (deprecated) a password used to encrypt and decrypt participants’ IP addresses. Can be left blank.

• WEBSERVER_PASS (deprecated) basic auth setting for certain requests sent between math and api services.

• WEBSERVER_USERNAME (deprecated) basic auth setting for certain requests sent between math and api services.

• FB_APP_ID Must register with Facebook to get an ID to enable Facebook App connectivity.

• AKISMET_ANTISPAM_API_KEY Comment spam detection and filtering.

• ENABLE_TWITTER_WIDGETS set to true to enable twitter widgets on the client-admin authentication pages.

• GA_TRACKING_ID For using Google Analytics on client pages.

• GOOGLE_CREDENTIALS_BASE64 Required if using Google Translate API. (See below).

• GOOGLE_CREDS_STRINGIFIED Alternative to GOOGLE_CREDENTIALS_BASE64 (See below).

• MAXMIND_LICENSEKEY, MAXMIND_USERID If using IP Geolocation service Maxmind.

• TWITTER_CONSUMER_KEY, TWITTER_CONSUMER_SECRET For Twitter integration.

Email Transports

We use Nodemailer to send email. Nodemailer uses various built-in and packaged email transports to send email via SMTP or API, either directly or via third-party platforms.

Each transport needs a bit of hardcoded scaffold configuration to make it work, which we welcome via code contribution. But after this, others can easily use the same email transport by setting some configuration values via environment variable or otherwise.

We use EMAIL_TRANSPORT_TYPES to set email transports and their fallback order. Each transport has a keyword (e.g., maildev). You may set one or more transports, separated by commas. If you set more than one, then each transport will “fallback” to the next on failure.

For example, if you set aws-ses,mailgun, then we’ll try to send via aws-ses, but on failure, we’ll try to send via mailgun. If Mailgun fails, the email will not be sent.

Configuring transport: maildev

Note: The MailDev email transport is for development purposes only. Ensure it’s disabled in production!

1. Add maildev into the EMAIL_TRANSPORT_TYPES configuration.

This transport will work automatically when running via Docker Compose with the development overlay, accessible on port 1080.

Configuring transport: aws-ses

1. Add aws-ses into the EMAIL_TRANSPORT_TYPES configuration.
2. Set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY configuration.

Configuring transport: mailgun

1. Add mailgun into the EMAIL_TRANSPORT_TYPES configuration.
2. Set the MAILGUN_API_KEY and MAILGUN_DOMAIN configuration.

Adding a new transport

1. Find a transport for the service you require (or write your own!)

2. Add any new transport configuration to getMailOptions(...) in server/email/senders.js.

3. Submit a pull request.

4 - Best Practices

If you need to conduct a survey using PolisOrbis you have two alternatives:

• run your own instance of PolisOrbis Service in your infrastructure
• use an existing managed services asking permission to the service provider

Even if PolisOrbis code is free, to conduct an on-line opinions’ survey always requires some resources:

• you must plan effort to setup, moderate, summarize and close the survey (depending from the survey characteristics)
• you must provide resources to publicize your survey
• if you opt to use a 3rd party service, you probably have to pay some service fees
• if you opt to deploy your PolisOrbis service you must pay your infrastructure and service operation costs, by your personnel and/or external technical consultants

You must also take into account that running an on-line service always implies some responsibilities

Using your own instance of PolisOrbis

Pros:

• attached to the identity service of your choice
• complete control on user access
• complete access to the internal DB
• great degree of UI customization
• optimized scalability support for big survey ( > 10000 users)
• you can expand the code with your own functionality for a better integration with your system
• no external services costs
• no license cost (Open source License)

Cons:

• you need your own hw & network infrastructure
• you must have good skills as a service provider and you must know cloud services, kubernetes, docker and Postgress
• no support on operation: you have to pay a consultant
• infrastructure requires a minimum capacity that can be oversized for just some small surveys ( < 1000 users): there are some fixed infrastructure cost you have to pay even if no surveys are done.

Using a 3rd party service

Pros:

• You do not have to manage technical infrastructure and concentrate only on survey contents
• Troubles in operations are managed by the service providers according defined SLA (service level agreement)
• cost are convenient for short term, low number of participants surveys because the fixed cost are shared.
• high availability

Cons:

• you relay on the Identity server chosen by the service provider
• yoy have only a limited control on user access (depending from the service configuration) complete access to the internal DB
• no UI customization
• operation fee

using PolisOrbis sandbox

The PolisOrbis sandbox service (https://demo.polisorbis.eu/) is free for all to test the latest version of the PolisOrbis service. See privacy policy and Term of Use

using PolisOrbis Copernicani Instance

The Copernicani PolisOrbis service can be used by Orbis pilots by:

• Using the Orbis identity provider under the responsibility of the Orbis Consortium (as soon ass it will be available).
• Signing a contract containing SLA and a waiver, releasing Copernicani from liability for the content of your survey. [Example document link TBD]
• Contributing to the service operation cost (details in Basecamp)

Responsibilities

Besides this running an on-line service requires some legal responsibilities:

• you must write and execute your policies to moderate/control user behavior inside your survey
• you must ensure that no sensitive data are shared inside the user generated comments

If you run your instance of PolisOrbis:

• you need to plan legal effort to write your Term of Services and Your Privacy policy

If you use a 3rd-party service:

• you will probably have to sign a waiver for the provider, releasing it from liability for the content of your survey.
• you will have to negotiate with the service provider a SLA and service costs
• you must agree with the service provider TOS and Privacy Policy

other best practices

For a detailed methods paper, see Polis: Scaling Deliberation by Mapping High Dimensional Opinion Spaces.

5 - APIs

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.

5.1 - Comments API

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"
    ]
  }
}

5.2 - Conversations API

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"
  ]
}

5.3 - Math/PCA API

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"
  ]
}