-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
b44c41e
commit 558f568
Showing
2 changed files
with
113 additions
and
108 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| --- | ||
| title: Querying Classification Counts By User (Authenticated) | ||
| layout: page | ||
| nav_order: 4 | ||
| --- | ||
|
|
||
| # Querying Classification Counts By User (Authenticated) | ||
|
|
||
| Our stats API allows querying for a volunteer’s personal classification stats as long as the person querying has proper authorizations._ In other words, querying classification counts by user requires an authentication token to be supplied. _ | ||
|
|
||
| This authentication token is known as a bearer token and is usually supplied as a HTTP `Authorization` header with the value prefixed by `Bearer` and then the token data. | ||
|
|
||
| For example: | ||
|
|
||
| These tokens are generated by our main backend Panoptes. For more information on retrieving a Bearer token from Panoptes, please refer to our Panoptes documentation, specifically [https://zooniverse.github.io/panoptes/#example-using-postman](https://zooniverse.github.io/panoptes/#example-using-postman). | ||
|
|
||
|
|
||
| ### Example: Retrieving Bearer Token From Panoptes | ||
|
|
||
| The easiest way to get started is to use client credentials OAuth flow. | ||
|
|
||
| You will need to create an OAuth application within our system via : [https://signin.zooniverse.org/oauth/applications/new](https://signin.zooniverse.org/oauth/applications/new) | ||
|
|
||
| **Note that it is imperative that you do NOT share the OAuth application secret **as it can gain access to your Zooniverse account as if you were using the system. | ||
|
|
||
| Once you have your OAuth application set up, you can do the following: | ||
|
|
||
|
|
||
| --- | ||
|
|
||
| When calling out to Stats API’s `/classifications/users/?` route, you will not have access to another person’s classification stats through this route; you will only have access to view your own classification counts. More information can be found in our full documentation: [https://github.com/zooniverse/eras/wiki/API-Callout-Examples#classificationsusersid](https://github.com/zooniverse/eras/wiki/API-Callout-Examples#classificationsusersid) | ||
|
|
||
| You can query personal classification counts filtering by any of the following: | ||
|
|
||
|
|
||
|
|
||
| * project_id/s | ||
| * can search by multiple project_ids when entering a `,` separated string of ids | ||
| * eg. `?project_id=1,2,3,4` | ||
| * workflow_id/s | ||
| * can search by multiple workflow_ids when entering a `,` separated string of ids | ||
| * eg. `?workflow_id=1,2,3,4` | ||
| * Start_date | ||
| * Date Format must be in `YYYY-MM-DD` | ||
| * End_date | ||
| * Date Format must be in `YYYY-MM-DD` | ||
| * Period | ||
| * If this is a parameter, the response will include a `data` key which shows the breakdown of classification counts bucketed by your entered period. | ||
| * Allowable buckets are either: | ||
| * `day` | ||
| * `week` | ||
| * `month` | ||
| * `year` | ||
| * Time_spent (true/false) | ||
| * Boolean that dictates whether your response will calculate the approximate time spent **<span style="text-decoration:underline;">in seconds</span>** on your classifications. | ||
| * Note that this calculation does not include any time you have spent on Talk | ||
| * Project_contributions (true/false) | ||
| * Boolean that dictates whether your response will display all your project contributions broken down. | ||
| * This list is ordered by top contributing projects, by classification count | ||
| * This list does not include any time and efforts you may have spent on Talk | ||
|
|
||
| **CAVEATS** | ||
|
|
||
|
|
||
|
|
||
| * **We do not allow you to query by BOTH project_id AND workflow_id (either one or the other)** | ||
| * **We do not allow you to query by both `project_id`/`workflow_id` AND `?project_contributions=true`. ** | ||
|
|
||
| For the following examples, we use the user_id `1234` | ||
|
|
||
|
|
||
| ### Example: Query Personal Classification Counts | ||
|
|
||
| If you were interested in your own personal classification counts of all time. You will need your user_id and run the following: | ||
|
|
||
| Response: | ||
|
|
||
|
|
||
| ### Example: Query Personal Classification Counts and Approximate Time Spent | ||
|
|
||
| If you were interested in both your own personal classification counts of all time and approximate time spent on those classifications, you would query the following: | ||
|
|
||
| Response will look something like this: | ||
|
|
||
| **Noting that `time_spent` calculation is time in _<span style="text-decoration:underline;">seconds</span>_** | ||
|
|
||
|
|
||
| ### Example: Query Personal Classification Counts, Time Spent, and Breakdown of Classification Counts | ||
|
|
||
| If interested in querying for your own personal classification counts of all time, approximate time spent on those classifications, also interested in the yearly counts that make up the total count of the response, we can query the following: | ||
|
|
||
| Response: | ||
|
|
||
|
|
||
| ### Example: Query Personal Classification Counts, Time Spent, And All Project Contributions | ||
|
|
||
| If interested in querying for your own personal classification counts of all time, approximate time spent on those classifications, and also interested in your project contributions in terms of classification count, we can query the following: | ||
|
|
||
| Response will look something like this: | ||
|
|
||
| Note that the list of `project_contributions` is in order by `count`; which is your classification count per project. | ||
|
|
||
|
|
||
| ### Example: Query Personal Classification Counts For A Specific Project/s | ||
|
|
||
| If interested in querying for your own personal classification counts during a date range for a specific project, along approximate time spent on those classifications, we can query the following: | ||
|
|
||
|
|
||
|
|
||
| In this example, we use the user with id `1234`’s project classification counts for project with id `1972` in between the date range of `2022-03-10` (March 10, 2022) through `2023-03-10` (March 10, 2023) | ||
|
|
||
| Response: | ||
|
|