API Callout Examples

Querying Comments Stats (/comments)

Querying Comment counts based on provided params.

Authentication

None

URL

GET /comments

Request Parameters

Parameter	Type	Description	Required?
project_id	integer (or integers separated by , if querying for multiple project_id/s)	ID/s of a Panoptes project	No
user_id	integer (or integers separated by , if querying for multiple user_id/s)	ID/s of a Panoptes User	No
start_date	string of Date Format	Starting date of comments you want to query from	No
end_date	string of Date Format	Ending date range of comments you want to query from	No
period	string (either day, week, month, year)	Time Bucket on how you want to bucket response data	No

Example Request/s

## query to get count of all comments of all time
GET https://eras-staging.zooniverse.org/comments 

## query to get count of all comments relating to Project with id 1
GET https://eras-staging.zooniverse.org/comments?project_id=1

## query to get count of all comments relating to Projects with ids 1 or 2
GET https://eras-staging.zooniverse.org/comments?project_id=1,2  

## query to get count of all comments created by User with id 1
GET https://eras-staging.zooniverse.org/comments?user_id=1

## query to get count of all comments of all time bucketed by week 
GET https://eras-staging.zooniverse.org/comments?period=week

## query to get count of all comments relating to Project with id 1 and created by User with id 1  
GET https://eras-staging.zooniverse.org/comments?project_id=1&user_id=1

Response Parameters

Parameter	Type	Description
total_count	integer	Total count of comments given request parameters
data	array	Only returned when period is a request parameter. This shows the breakdown of comments bucketed by period that make up the response's total_count

Example Response/s

{
	"total_count": 4123
}

• When period is a request param

{
	"total_count": 4123,
	"data": [
		{
                       "period": "2023-05-27T00:00:00Z",
			"count": 4000,
                 },
		{
			"period": "2023-05-28T00:00:00Z",
			"count": 123
                }
	]
}

Querying Classification Stats

/classifications

/classifications/users/:id

/classifications/user_groups/:id

Authentication

Authorization Header Required

Authorizations

TODO!

URL

GET /classifications/user_groups/:id (where :id is the id of the user_group one wants to query)

Request Parameters

Parameter	Type	Description	Required?
project_id	integer (or integers separated by , if querying for multiple project_id/s)	ID/s of a Panoptes project (NOTE: One cannot query by both project_id/s AND workflow_id/s)	No
workflow_id	integer (or integers separated by , if querying for multiple workflow_id/s)	ID/s of a Panoptes Workflow	No
start_date	string of Date Format	Starting date of classifications you want to query from	No
end_date	string of Date Format	Ending date range of classifications you want to query from	No
period	string (either day, week, month, year)	Time Bucket on how you want to bucket response data	No
top_contributors	integer	Limit that dictates whether response will show top_contributors of user_group and how many	No
individual_stats_breakdown	boolean	Boolean that dictates whether to show a stats report vs a roster stats report per individual user of a user group	No

Example Request/s

## query to get classification stats report (total_count, time_spent, active_users, project_contributions) of user_group
GET https://eras-staging.zooniverse.org/classifications/user_groups/1234

## query to get classification stats report (total_count, time_spent, active_users) of user_group relating to Project with id 1
GET https://eras-staging.zooniverse.org/classifications/user_groups/1234?project_id=1

## query to get classification stats report (total_count, time_spent, active_users) of user_group relating to Project with ids 1 or 2
GET https://eras-staging.zooniverse.org/classifications/user_groups/1234?project_id=1,2  

## query to get classification stats report (total_count, time_spent, active_users) of user_group relating to Workflow with id 1
GET https://eras-staging.zooniverse.org/classifications/user_groups/1234?workflow_id=1  

## query to get classification stats report (total_count, time_spent, active_users and data) of all classifications of all time for user_group with id=1234, where data is bucketed by week 
GET https://eras-staging.zooniverse.org/classifications/user_groups/1234?period=week

## query to get classification stats report (total_count, time_spent, active_users and top_contributors[in this case top 10 contributors]) relating to Project with id 1
GET https://eras-staging.zooniverse.org/comments?project_id=1&top_contributors=10

Response Parameters (When individual_stats_breakdown is not a parameter)

Parameter	Type	Description
total_count	integer	Total count of classifications of queried user group given request parameters
time_spent	float	Total session time IN SECONDS of total classifications of user group
active_users	integer	Total active users (users who have made a classification given request parameters) of user group
project_contributions	array	Array of all project contributions (project_id and count) of user group given request parameters. If project_id or workflow_id is a parameter, response will NOT include project_contributions
data	array	Only returned when period is a request parameter. This shows the breakdown of classifications bucketed by period that make up the response's total_count. Array of objects that look like {"period": date, "count": integer, "session_time": float}

Response Parameters (When individual_stats_breakdown=true)

Parameter	Type	Description
group_member_stats_breakdown	array	Array of each user's (who is a member of given user group) stats Array of objects that look like {"user_id": integer, "count": integer, "session_time": float, "project_contributions": array [{"project_id": integer, "count": integer}] }

Example Response/s (When individual_stats_breakdown is false or not given)

{
  "total_count": 6,
  "time_spent": 507,
  "active_users": 1,
  "project_contributions": [
                            {
                              "project_id": 5110,
                              "count": 3
                            },
                            {
                              "project_id": 15698,
                              "count": 1
                            },
                            {
                              "project_id": 9908,
                              "count": 1
                            },
                            {
                              "project_id": 12767,
                              "count": 1
                            }
                         ]
}

• When period is a request param

{
  "total_count": 6,
  "time_spent": 507,
  "active_users": 1,
  "project_contributions": [
                            {
                              "project_id": 5110,
                              "count": 3
                            },
                            {
                              "project_id": 15698,
                              "count": 1
                            },
                            {
                              "project_id": 9908,
                              "count": 1
                            },
                            {
                              "project_id": 12767,
                              "count": 1
                            }
                         ],
 "data": [
           {
             "period": "2021-11-01T00:00:00.000Z",
             "count": 2,
             "session_time": 29
            },
            {
              "period": "2021-12-01T00:00:00.000Z",
              "count": 4,
              "session_time": 478
            }
        ]
}

Example Response/s (When individual_stats_breakdown=true)