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:

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.

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

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

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 in seconds 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
Order_project_contributions_by (Recents/Count)
- Takes either ‘recents’ or ‘count’. Defaults to ‘count’
- Dictates whether your response’s project_contributions will display project contributions ordered by count or by most recently contributed.
- Note that if you order by ‘recents’, it is RECOMMENDED to set period=day as a parameter to your request. This will give you most recent project.
  - This is due to our queries utilizing a binning function [https://docs.timescale.com/api/latest/hyperfunctions/time_bucket/] to query data.
  - When setting your period time bucket to a bigger time bucket (week, month, or the default of year), the ordering of your most recents may not be consistent on your time bucket.
    - As an example, if you classified to a project with id 1 on Wednesday if this week and contributed to a different project with id 2 the following day on Thursday, if we set period=week&order_project_contributions_by=recents, both projects will show up in the response’s project_contributions, but the ordering not be consistent, sometimes project with id 2 will show up first and sometimes project with id 1 will show up first.
      - HOWEVER, within this same example, say you classified to a third project with id 3 the week prior (and did not classify on the third project on the current week) the ordering of project_contributions will vary between projects with id 1 or 2 coming first but project with id 3 will always come after that.

CAVEATS

Note that if you order by ‘recents’, it is RECOMMENDED to set period=day as a parameter to your request. This will give you most recent project.
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 when ?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:

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

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

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:

{
    "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

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