diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..accc458 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +_site +.jekyll-cache \ No newline at end of file diff --git a/_config.yml b/_config.yml index bce87b2..c1ad2da 100644 --- a/_config.yml +++ b/_config.yml @@ -1,5 +1,5 @@ -title: Test ERAS Doc -description: Test ERAS API Doc for Zooniverse's Stats Service +title: ERAS API Docs +description: ERAS API Documentation for Zooniverse's Stats Service theme: just-the-docs aux_links: diff --git a/examples-in-other-languages.md b/examples-in-other-languages.md new file mode 100644 index 0000000..edc35ea --- /dev/null +++ b/examples-in-other-languages.md @@ -0,0 +1,52 @@ +--- +title: Examples in Other Languages +layout: page +nav_order: 6 +--- + +# Quick Examples in Other Languages + + +## Python +``` +import requests + +api_url = 'https://eras.zooniverse.org/classifications' +headers = {'authorization': f"Bearer {_YOUR_BEARER_TOKEN_}"} + +user_classification_counts_url = api_url + '/users/1234' +r = requests.get(user_classification_counts_url, headers=headers) + +if r.status_code == 200: + data = r.json() + # Do something with data +else: + print('Error with retrieving data') +``` + +## Javascript + +The following example is an authenticated callout to `/users` where `user_id=1234` +``` +import fetch from 'node-fetch' + +const apiUrl = 'https://eras.zooniverse.org/classifications' +const headers = { authorization: `Bearer ${_YOUR_BEARER_TOKEN_}` +} + +fetch(apiUrl + '/users/1234', { headers }) + .then(response => { + if (!response.ok) { + throw new Error('Network response was not ok') + } + return response.json(); + }) + .then(data => { + console.log('Data : ', data); + // Do something with the data + }) + .catch(error => { + console.error('There was an error with fetching data') + }); + +``` \ No newline at end of file diff --git a/index.md b/index.md index 12d683d..590aa68 100644 --- a/index.md +++ b/index.md @@ -39,94 +39,3 @@ If you are familiar with our older stats service ([https://github.com/zooniverse * [https://eras.zooniverse.org](https://eras.zooniverse.org) Response Example: * [https://stats.zooniverse.org](https://stats.zooniverse.org) Response Example: - -## Querying Classification Counts By User Group - - -### What Are User Groups? - -As a new feature of our stats service, we introduce the idea of user groups so that a group of volunteers can set shared goals and celebrate milestones. Whether it’s a classroom, after school club, a group of friends, or corporate volunteering program, this new group feature provides new avenues for fostering community and collaboration for our volunteers and contributors. - -For more documentation on user groups within our stats service, you can view our documentation: here (https://github.com/zooniverse/eras/wiki/API-Callout-Examples#classificationsuser_groupsid) - -Our stats API allows querying for a user group’s classification stats as long as the person querying has proper authorizations to access the group statistics. _In other words, querying classification counts by user group 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. - - ---- - -You can query user group 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` -* top_contributors (integer) - * Limit that dictates whether your response will show top contributors of the user group -* individual_stats_breakdown (true/false) - * Boolean that dictates whether your response will shows show a roster stats report per each individual member for the user group - - -### Example: Query User Group Classification Counts - -If you were interested in the user group with user_group id=1234’s classification counts of all time. You will need your user_group_id and run the following: - -Response: - -The response for querying user group classification counts will look a bit different than the other queries from the previous examples. By default, querying user group classification counts will return the following: - - - -* Total_count - * Integer - * The total count of classifications of queried user group -* Time_spent - * Float - * Total session time IN SECONDS of total classifications of user group -* Active_users - * Integer - * Total active users of the user group - * Active users being users who have made a classification given request parameters -* Project_contributions - * List - * List of all project contributions (project_id and count) of user group given request parameters - * NOTE: if `project_id` or `workflow_id` is a parameter in your request, the response will NOT include this list -* data - * Only returned when `period` is a request parameter - * This shows the total breakdown of classifications of the user group bucketed by `period` that make up the response’s `total_count` - - -### Example: Query User Group’s Group Member Stats Breakdown - -If you were interested in the user group with user_group id=1234’s group member stats breakdown of all time, we can utilize the `?individual_stats_breakdown=true` parameter and request the following: - -Response: - -Note that in this particular response, it returns a list of each group member’s project contributions, session time and classification count, ordered by top total classification count of members in the group. - - -## Examples in Other Languages - - -### Python - - -### Javascript - -The following example is an authenticated callout to `/users` where `user_id=1234` diff --git a/query-classification-counts-auth.md b/query-classification-counts-auth.md index b4cf2c0..e7b7ad3 100644 --- a/query-classification-counts-auth.md +++ b/query-classification-counts-auth.md @@ -1,34 +1,46 @@ --- -title: Querying Classification Counts By User (Authenticated) +title: Classification Counts By User 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. _ +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: +``` +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c +``` -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). +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 +## 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. +**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: +``` +curl -X POST 'https://panoptes.zooniverse.org/oauth/token' \ +--header 'Content-Type: application/json' \ +--data '{ + "grant_type":"client_credentials", + "client_id" : "_YOUR_CLIENT_ID_", + "client_secret": "_YOUR_CLIENT_SECRET_" +}' +``` --- -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) +When calling out to ERAS' 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 Github repo Wiki for ERAS: [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: @@ -64,50 +76,202 @@ You can query personal classification counts filtering by any of the following: * **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` +* **We do not allow you to query by both `project_id`/`workflow_id` when `?project_contributions=true`.** -### Example: Query Personal Classification Counts +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: +``` +curl -G https://eras.zooniverse.org/classifications/users/1234 \ +--header 'Authorization: Bearer $YOUR_BEARER_TOKEN' +``` Response: +``` +{ + "total_count": 3003 +} +``` - -### Example: Query Personal Classification Counts and Approximate Time Spent +## 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: +``` +curl -G https://eras.zooniverse.org/classifications/users/1234?time_spent=true \ +--header 'Authorization: Bearer $YOUR_BEARER_TOKEN' +``` Response will look something like this: +``` +{ + "total_count": 112, + "time_spent": 7625.88 +} +``` **Noting that `time_spent` calculation is time in _seconds_** -### Example: Query Personal Classification Counts, Time Spent, and Breakdown of Classification Counts +## 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: +``` +curl -G https://eras.zooniverse.org/classifications/users/1234?time_spent=true&period=year \ +--header 'Authorization: Bearer $YOUR_BEARER_TOKEN' +``` Response: - - -### Example: Query Personal Classification Counts, Time Spent, And All Project Contributions +``` +{ + "total_count": 112, + "time_spent": 7625.88, + "data": [ + { + "period": "2022-01-01T00:00:00.000Z", + "count": 70, + "session_time": 5737.0 + }, + { + "period": "2023-01-01T00:00:00.000Z", + "count": 42, + "session_time": 1888.88 + } + ] +} +``` + + +## 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: +``` +curl -G https://eras.zooniverse.org/classifications/users/1234?time_spent=true&project_contributions=true \ +--header 'Authorization: Bearer $YOUR_BEARER_TOKEN' +``` Response will look something like this: +``` +{ + "total_count": 112, + "time_spent": 7625.88, + "project_contributions": [ + { + "project_id": 1974, + "count": 24 + }, + { + "project_id": 335, + "count": 23 + }, + { + "project_id": 1968, + "count": 15 + }, + { + "project_id": 1952, + "count": 12 + }, + { + "project_id": 1634, + "count": 9 + }, + { + "project_id": 1862, + "count": 3 + }, + { + "project_id": 1810, + "count": 3 + }, + { + "project_id": 1771, + "count": 3 + }, + { + "project_id": 1783, + "count": 2 + }, + { + "project_id": 1767, + "count": 2 + }, + { + "project_id": 1663, + "count": 2 + }, + { + "project_id": 908, + "count": 2 + }, + { + "project_id": 1946, + "count": 2 + }, + { + "project_id": 1876, + "count": 2 + }, + { + "project_id": 1874, + "count": 2 + }, + { + "project_id": 1315, + "count": 2 + }, + { + "project_id": 1989, + "count": 1 + }, + { + "project_id": 1967, + "count": 1 + }, + { + "project_id": 1901, + "count": 1 + }, + { + "project_id": 1779, + "count": 1 + } + ] +} +``` 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 +## 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: - +``` +curl -G https://eras.zooniverse.org/classifications/users/1234?time_spent=true&project_id=1972&period=day&start_date=2022-03-10&end_date=2023-03-10 \ +--header 'Authorization: Bearer $YOUR_BEARER_TOKEN +``` 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: +``` +{ + "total_count": 24, + "time_spent": 487.0, + "data": [ + { + "period": "2022-09-09T00:00:00.000Z", + "count": 23, + "session_time": 471 + }, + { + "period": "2022-09-20T00:00:00.000Z", + "count": 1, + "session_time": 16 + } + ] +} +``` \ No newline at end of file diff --git a/query-user-group-counts.md b/query-user-group-counts.md new file mode 100644 index 0000000..90db21b --- /dev/null +++ b/query-user-group-counts.md @@ -0,0 +1,210 @@ +--- +title: Classification Counts By User Group +layout: page +nav_order: 5 +--- + +# Querying Classification Counts By User Group + + +### What Are User Groups? + +As a new feature of our stats service, we introduce the idea of user groups so that a group of volunteers can set shared goals and celebrate milestones. Whether it’s a classroom, after school club, a group of friends, or corporate volunteering program, this new group feature provides new avenues for fostering community and collaboration for our volunteers and contributors. + +For more documentation on user groups within our stats service, you can view our Github repository Wiki: here (https://github.com/zooniverse/eras/wiki/API-Callout-Examples#classificationsuser_groupsid) + +Our stats API allows querying for a user group’s classification stats as long as the person querying has proper authorizations to access the group statistics. _In other words, querying classification counts by user group 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. + + +--- + +You can query user group 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` +* top_contributors (integer) + * Limit that dictates whether your response will show top contributors of the user group +* individual_stats_breakdown (true/false) + * Boolean that dictates whether your response will shows show a roster stats report per each individual member for the user group + + +## Example: Query User Group Classification Counts + +If you were interested in the user group with user_group id=1234’s classification counts of all time. You will need your user_group_id and run the following: + +``` +curl -G https://eras.zooniverse.org/classifications/user_groups/1234 +--header 'Authorization: Bearer $YOUR_BEARER_TOKEN' +``` + +Response: + +``` +{ + "total_count": 18, + "time_spent": 4895.192, + "active_users": 2, + "project_contributions": [ + { + "project_id": 335, + "count": 4, + "session_time": 61.971000000000004 + }, + { + "project_id": 1613, + "count": 3, + "session_time": 4744.13 + }, + { + "project_id": 1952, + "count": 3, + "session_time": 50.400999999999996 + }, + { + "project_id": 1663, + "count": 2, + "session_time": 6.649000000000001 + }, + { + "project_id": 1767, + "count": 2, + "session_time": 4.567 + }, + { + "project_id": 1783, + "count": 2, + "session_time": 4.545 + }, + { + "project_id": 1634, + "count": 1, + "session_time": 17.469 + }, + { + "project_id": 631, + "count": 1, + "session_time": 5.46 + } + ] +} +``` + +The response for querying user group classification counts will look a bit different than the other queries from the previous examples. By default, querying user group classification counts will return the following: + + + +* Total_count + * Integer + * The total count of classifications of queried user group +* Time_spent + * Float + * Total session time IN SECONDS of total classifications of user group +* Active_users + * Integer + * Total active users of the user group + * Active users being users who have made a classification given request parameters +* Project_contributions + * List + * List of all project contributions (project_id and count) of user group given request parameters + * NOTE: if `project_id` or `workflow_id` is a parameter in your request, the response will NOT include this list +* data + * Only returned when `period` is a request parameter + * This shows the total breakdown of classifications of the user group bucketed by `period` that make up the response’s `total_count` + + +## Example: Query User Group’s Group Member Stats Breakdown + +If you were interested in the user group with user_group id=1234’s group member stats breakdown of all time, we can utilize the `?individual_stats_breakdown=true` parameter and request the following: +``` +curl -G https://eras.zooniverse.org/classifications/user_groups/1234?individual_stats_breakdown=true +--header 'Authorization: Bearer $YOUR_BEARER_TOKEN' +``` + +Response: +``` +{ + "group_member_stats_breakdown": [ + { + "user_id": 1325316, + "count": 12, + "session_time": 121.761, + "project_contributions": [ + { + "project_id": 1952, + "count": 3, + "session_time": 50.400999999999996 + }, + { + "project_id": 1783, + "count": 2, + "session_time": 4.545 + }, + { + "project_id": 1767, + "count": 2, + "session_time": 4.567 + }, + { + "project_id": 1663, + "count": 2, + "session_time": 6.649000000000001 + }, + { + "project_id": 335, + "count": 2, + "session_time": 38.129999999999995 + }, + { + "project_id": 1634, + "count": 1, + "session_time": 17.469 + } + ] + }, + { + "user_id": 1326056, + "count": 6, + "session_time": 4773.4310000000005, + "project_contributions": [ + { + "project_id": 1613, + "count": 3, + "session_time": 4744.13 + }, + { + "project_id": 335, + "count": 2, + "session_time": 23.841 + }, + { + "project_id": 631, + "count": 1, + "session_time": 5.46 + } + ] + } + ] +} +``` + +Note that in this particular response, it returns a list of each group member’s project contributions, session time and classification count, ordered by top total classification count of members in the group. + diff --git a/querying-classification-counts-unauth.md b/querying-classification-counts-unauth.md index d260c01..17b3e59 100644 --- a/querying-classification-counts-unauth.md +++ b/querying-classification-counts-unauth.md @@ -1,5 +1,5 @@ --- -title: Querying Classification Counts (Unauthenticated) +title: Classification Counts (Without Authentication) layout: page nav_order: 2 --- diff --git a/querying-comment-counts.md b/querying-comment-counts.md index 103b089..a2bbdbc 100644 --- a/querying-comment-counts.md +++ b/querying-comment-counts.md @@ -1,10 +1,10 @@ --- -title: Querying Comment Counts +title: Comment Counts layout: page nav_order: 3 --- -## Querying Comment Counts +# Querying Comment Counts We also allow querying comment counts without Authentication (i.e. No Authorization Header within your request). @@ -31,7 +31,7 @@ With comment counts you can also filter your count query by the following parame * `year` -### Example: Querying Comment Counts +## Example: Querying Comment Counts If one was curious on how many total comments we currently have on the Zooniverse, you could query with the following: ``` @@ -46,7 +46,7 @@ Response will look something like this: ``` -### Example: Querying Comment Counts By Project With Count Breakdown +## Example: Querying Comment Counts By Project With Count Breakdown Similar to querying classification counts, our stats API allows querying comment counts by project. The following example shows how one would query for comment counts for a specific project (eg. project with id `1234`) broken down by month.