Skip to content

API Callout Examples

Jump to bottom
yuenmichelle1 edited this page Aug 3, 2023 · 23 revisions

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

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 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 query by both project_id/s AND workflow_id/s) 		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 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 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 query by both project_id/s AND workflow_id/s) 		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
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

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: We do NOT 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)
(NOTE: We do NOT query by both project_id/s AND 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
            }
        ]
}
  • When top_contributors is a param
{
   "total_count": 3,
   "time_spent": 348,
   "active_users": 1,
   "top_contributors": [
                        {
                          "user_id": 2294610,
                          "count": 3
                        }
                       ]
}

Example Response/s (When individual_stats_breakdown=true)

Are you... Ready for it?

Overview

Home
User Groups Stats Visibility Levels
Data Tables
Mappings from Source Tables to ERAS
Continuous Aggregates
Decisions Around Session Time Caps

API Documentation

Routes and Params
Examples
Troubleshooting

Clone this wiki locally