API Callout Examples

---

Routes

1. /comments
2. /classifications
3. /classifications/users/:id
4. /classifications/user_groups/:id

---

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 (YYYY-MM-DD)	Starting date of comments you want to query from	No
end_date	string of Date Format (YYYY-MM-DD)	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

Authentication

None

URL

GET /classifications

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: We do NOT allow 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 (NOTE: We do NOT allow query by both project_id/s AND workflow_id/s)	No
start_date	string of Date Format (YYYY-MM-DD)	Starting date of comments you want to query from	No
end_date	string of Date Format (YYYY-MM-DD)	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 total_count of classifications of all time 
GET https://eras-staging.zooniverse.org/classifications

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

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

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

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

Response Parameters

Parameter	Type	Description
total_count	integer	Total count of classifications given request parameters
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

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

/classifications/users/:id

Authentication

Authorization Header Required

Authorizations

Fairly simple authorization, the querying user either has to be a

• querying his/her/their own stats
• or a Panoptes admin

URL

GET /classifications/users/:id (where :id is the id of the user 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: We do NOT allow 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 (NOTE: We do NOT allow query by both project_id/s AND workflow_id/s)	No
start_date	string of Date Format (YYYY-MM-DD)	Starting date of comments you want to query from	No
end_date	string of Date Format (YYYY-MM-DD)	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
time_spent	boolean	Boolean that dictates whether to show total time spent for user	No
project_contributions	boolean	Boolean that dictates whether to show all project_contributions (and counts per project) of the user	No

Example Request/s

## query to get total_count of classifications of all time for user with id 1
GET https://eras-staging.zooniverse.org/classifications/users/1

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

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

## query to get count of all classifications for user with id 1 created by Workflow with id 1
GET https://eras-staging.zooniverse.org/classifications/users/1?workflow_id=1

## query to get count of all classifications of user with id 1 of all time bucketed by week 
GET https://eras-staging.zooniverse.org/classifications/users/1?period=week

## query to get total_count and total time_spent (IN SECONDS) of all classifications of user with id 1
GET https://eras-staging.zooniverse.org/classifications/users/1?time_spent=true

## query to get total_count and project_contributions (and counts per project) of all classifications of user with id 1
GET https://eras-staging.zooniverse.org/classifications/users/1?project_contributions=true

Response Parameters

Parameter	Type	Description
total_count	integer	Total count of classifications of queried user given request parameters
time_spent	float	Total session time IN SECONDS of total classifications of user Only in response if we have request params time_spent=true
project_contributions	array	Array of all project contributions (project_id and count) of user given request parameters. If project_id or workflow_id is a parameter, response will NOT include project_contributions Only in response if we have project_contributions=true in request params
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}

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

• When time_spent=true

{
	"total_count": 4123,
	"time_spent": 3004
}

• When period=day and time_spent=true is a request param

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

• When project_contributions=true

{
	"total_count": 4123,
        "project_contributions": [
		{ "project_id": 123, "count": 4000 },
		{ "project_id": 234, "count": 100 },
                { "project_id": 345, "count": 20 },
                { "project_id": 456, "count": 3 }
	]
}

/classifications/user_groups/:id

Authentication

Dependent on what you are querying. See below for more info

Authorizations

Permissions are dependent on 3 factors (unless you are a panoptes_admin, then you have full permission):

1. what stats requests you are querying from ERAS (group aggregate stats vs individual stats breakdown),
2. the user group's stats visibility level,
3. and who you are related to the group

If you are querying group aggregate stats (i.e. individual_stats_breakdown is false or not a parameter in your request):

• If the user_group's stats visibility level is public_show_all
  • anyone can view these stats (No auth required)
• If the user_group's stats visibility level is public_agg_show_ind_if_member
  • anyone can view these stats (No auth required)
• If the user_group's stats visibility level is public_agg_only
  • anyone can view these stats (No auth required)
• If the user_group's stats visibility level is private_show_agg_and_ind
  • querying user is either a group_admin or a group_member (Auth required)
• If the user_group's stats visibility level is private_agg_only
  • querying user is either a group_admin or a group_member (Auth required)

If you are querying individual stats breakdown (i.e. individual_stats_breakdown is true):

• If the user_group's stats visibility level is public_show_all
  • anyone can view these stats (No auth required)
• If the user_group's stats visibility level is public_agg_show_ind_if_member
  • Only group_members and group_admins can see these stats (Auth required)
• If the user_group's stats visibility level is public_agg_only
  • querying user is a group_admin (Auth required)
• If the user_group's stats visibility level is private_show_agg_and_ind
  • querying user is either a group_admin or a group_member (Auth required)
• If the user_group's stats visibility level is private_agg_only
  • querying user is either a group_admin (Auth required)

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: We do NOT allow 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 (NOTE: We do NOT allow query by both project_id/s AND workflow_id/s)	No
start_date	string of Date Format (YYYY-MM-DD)	Starting date of classifications you want to query from	No
end_date	string of Date Format (YYYY-MM-DD)	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 the response to show a roster stats report per each individual user for the 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": 12,
  "time_spent": 71.304,
  "active_users": 1,
  "project_contributions": [
                            {
                              "project_id": 5110,
                              "count": 9,
                              "session_time": 41.304
                            },
                            {
                              "project_id": 15698,
                              "count": 1
                              "session_time": 10
                            },
                            {
                              "project_id": 9908,
                              "count": 1,
                              "session_time": 10
                            },
                            {
                              "project_id": 12767,
                              "count": 1,
                              "session_time": 10
                            }
                         ]
}

• When period is a request param

{
  "total_count": 6,
  "time_spent": 507,
  "active_users": 1,
  "project_contributions": [
                            {
                              "project_id": 5110,
                              "count": 3,
                              "session_time": 400
                            },
                            {
                              "project_id": 15698,
                              "count": 1,
                              "session_time": 50
                            },
                            {
                              "project_id": 9908,
                              "count": 1,
                              "session_time": 50
                            },
                            {
                              "project_id": 12767,
                              "count": 1
                              "session_time": 7
                            }
                         ],
 "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
            }
        ]
}

• When top_contributors is a param

{
  "total_count": 12,
  "time_spent": 71.304,
  "active_users": 1,
  "project_contributions": [
    {
      "project_id": 593,
      "count": 12,
      "session_time": 71.304
    }
  ],
  "top_contributors": [
    {
      "user_id": 1234,
      "count": 12,
      "session_time": 71
    }
  ]
}

Example Response/s (When individual_stats_breakdown=true)

{
  "group_member_stats_breakdown": [
    {
      "user_id": 1234,
      "count": 12,
      "session_time": 71.304,
      "project_contributions": [
        {
          "project_id": 593,
          "count": 12,
          "session_time": 71.304
        }
      ]
    }
  ]
}