From b44c41ef7eecbe4ebaa9905aac2601b3e4f88ef2 Mon Sep 17 00:00:00 2001 From: yuenmichelle1 Date: Fri, 15 Dec 2023 12:05:23 -0600 Subject: [PATCH] docs push --- Gemfile | 7 + Gemfile.lock | 86 ++++++++ LICENSE | 21 ++ README.md | 174 ++++++++++++++++ _config.yml | 36 ++++ index.md | 240 +++++++++++++++++++++ querying-classification-counts-unauth.md | 252 +++++++++++++++++++++++ querying-comment-counts.md | 94 +++++++++ 8 files changed, 910 insertions(+) create mode 100644 Gemfile create mode 100644 Gemfile.lock create mode 100644 LICENSE create mode 100644 README.md create mode 100644 _config.yml create mode 100644 index.md create mode 100644 querying-classification-counts-unauth.md create mode 100644 querying-comment-counts.md diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..1db6833 --- /dev/null +++ b/Gemfile @@ -0,0 +1,7 @@ +source 'https://rubygems.org' + +gem "jekyll", "~> 4.3.2" # installed by `gem jekyll` +# gem "webrick" # required when using Ruby >= 3 and Jekyll <= 4.2.2 + +gem "just-the-docs", "0.7.0" # pinned to the current release +# gem "just-the-docs" # always download the latest release diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000..a2d4391 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,86 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.8.5) + public_suffix (>= 2.0.2, < 6.0) + colorator (1.1.0) + concurrent-ruby (1.2.2) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.15.5) + forwardable-extended (2.6.0) + google-protobuf (3.24.3-arm64-darwin) + google-protobuf (3.24.3-x86_64-linux) + http_parser.rb (0.8.0) + i18n (1.14.1) + concurrent-ruby (~> 1.0) + jekyll (4.3.2) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + just-the-docs (0.7.0) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.8.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (5.0.3) + rake (13.0.6) + rb-fsevent (0.11.2) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.6) + rouge (4.1.3) + safe_yaml (1.0.5) + sass-embedded (1.67.0-arm64-darwin) + google-protobuf (~> 3.23) + sass-embedded (1.67.0-x86_64-linux-gnu) + google-protobuf (~> 3.23) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.4.2) + webrick (1.8.1) + +PLATFORMS + arm64-darwin-23 + x86_64-darwin-20 + x86_64-linux + +DEPENDENCIES + jekyll (~> 4.3.2) + just-the-docs (= 0.7.0) + +BUNDLED WITH + 2.3.26 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7d510d0 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2022 just-the-docs + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..362efd4 --- /dev/null +++ b/README.md @@ -0,0 +1,174 @@ +# just-the-docs-template + +This is a *bare-minimum* template to create a [Jekyll] site that: + +- uses the [Just the Docs] theme; +- can be built and published on [GitHub Pages]; +- can be built and previewed locally, and published on other platforms. + +More specifically, the created site: + +- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem; +- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages. + +To get started with creating a site, simply: + +1. click "[use this template]" to create a GitHub repository +2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions + +If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](#hosting-your-docs-from-an-existing-project-repo). + +After completing the creation of your new site on GitHub, update it as needed: + +## Replace the content of the template pages + +Update the following files to your own content: + +- `index.md` (your new home page) +- `README.md` (information for those who access your site repo on GitHub) + +## Changing the version of the theme and/or Jekyll + +Simply edit the relevant line(s) in the `Gemfile`. + +## Adding a plugin + +The Just the Docs theme automatically includes the [`jekyll-seo-tag`] plugin. + +To add an extra plugin, you need to add it in the `Gemfile` *and* in `_config.yml`. For example, to add [`jekyll-default-layout`]: + +- Add the following to your site's `Gemfile`: + + ```ruby + gem "jekyll-default-layout" + ``` + +- And add the following to your site's `_config.yml`: + + ```yaml + plugins: + - jekyll-default-layout + ``` + +Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`. + +## Publishing your site on GitHub Pages + +1. If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to: + + ```yaml + title: YOUR TITLE + description: YOUR DESCRIPTION + theme: just-the-docs + + url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME + + aux_links: # remove if you don't want this link to appear on your pages + Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME + ``` + +2. Push your updated `_config.yml` to your site on GitHub. + +3. In your newly created repo on GitHub: + - go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`. + - if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`. + +## Building and previewing your site locally + +Assuming [Jekyll] and [Bundler] are installed on your computer: + +1. Change your working directory to the root directory of your site. + +2. Run `bundle install`. + +3. Run `bundle exec jekyll serve` to build your site and preview it at `localhost:4000`. + + The built site is stored in the directory `_site`. + +## Publishing your built site on a different platform + +Just upload all the files in the directory `_site`. + +## Customization + +You're free to customize sites that you create with this template, however you like! + +[Browse our documentation][Just the Docs] to learn more about how to use this theme. + +## Hosting your docs from an existing project repo + +You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the [just-the-docs template](https://github.com/just-the-docs/just-the-docs-template), you can copy the template files into your existing repo and configure the template's Github Actions workflow to build from a `docs` directory. You can clone the template to your local machine or download the `.zip` file to access the files. + +### Copy the template files + +1. Create a `.github/workflows` directory at your project root if your repo doesn't already have one. Copy the `pages.yml` file into this directory. GitHub Actions searches this directory for workflow files. + +2. Create a `docs` directory at your project root and copy all remaining template files into this directory. + +### Modify the GitHub Actions workflow + +The GitHub Actions workflow that builds and deploys your site to Github Pages is defined by the `pages.yml` file. You'll need to edit this file to that so that your build and deploy steps look to your `docs` directory, rather than the project root. + +1. Set the default `working-directory` param for the build job. + + ```yaml + build: + runs-on: ubuntu-latest + defaults: + run: + working-directory: docs + ``` + +2. Set the `working-directory` param for the Setup Ruby step. + + ```yaml + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.1' + bundler-cache: true + cache-version: 0 + working-directory: '${{ github.workspace }}/docs' + ``` + +3. Set the path param for the Upload artifact step: + + ```yaml + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: "docs/_site/" + ``` + +4. Modify the trigger so that only changes within the `docs` directory start the workflow. Otherwise, every change to your project (even those that don't affect the docs) would trigger a new site build and deploy. + + ```yaml + on: + push: + branches: + - "main" + paths: + - "docs/**" + ``` + +## Licensing and Attribution + +This repository is licensed under the [MIT License]. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use! + +The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party [starter workflows]. A copy of their MIT License is available in [actions/starter-workflows]. + +---- + +[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). + +[Jekyll]: https://jekyllrb.com +[Just the Docs]: https://just-the-docs.github.io/just-the-docs/ +[GitHub Pages]: https://docs.github.com/en/pages +[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ +[Bundler]: https://bundler.io +[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate +[`jekyll-default-layout`]: https://github.com/benbalter/jekyll-default-layout +[`jekyll-seo-tag`]: https://jekyll.github.io/jekyll-seo-tag +[MIT License]: https://en.wikipedia.org/wiki/MIT_License +[starter workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml +[actions/starter-workflows]: https://github.com/actions/starter-workflows/blob/main/LICENSE diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..bce87b2 --- /dev/null +++ b/_config.yml @@ -0,0 +1,36 @@ +title: Test ERAS Doc +description: Test ERAS API Doc for Zooniverse's Stats Service +theme: just-the-docs + +aux_links: + ERAS: https://eras.zooniverse.org + +# Enable or disable the site search +# Supports true (default) or false +search_enabled: true +search: + # Split pages into sections that can be searched individually + # Supports 1 - 6, default: 2 + heading_level: 2 + # Maximum amount of previews per search result + # Default: 3 + previews: 2 + # Maximum amount of words to display before a matched word in the preview + # Default: 5 + preview_words_before: 3 + # Maximum amount of words to display after a matched word in the preview + # Default: 10 + preview_words_after: 3 + # Set the search token separator + # Default: /[\s\-/]+/ + # Example: enable support for hyphenated search words + tokenizer_separator: /[\s/]+/ + # Display the relative url in search results + # Supports true (default) or false + rel_url: true + # Enable or disable the search button that appears in the bottom right corner of every page + # Supports true or false (default) + button: false + +# For copy button on code +enable_copy_code_button: true diff --git a/index.md b/index.md new file mode 100644 index 0000000..3f36391 --- /dev/null +++ b/index.md @@ -0,0 +1,240 @@ +--- +title: Home +layout: home +has_toc: true +nav_order: 1 +--- + +# How to Use Our Stats Service API + +Our stats service API allows our volunteers, project owners and project contributors to view their efforts and contributions to project/s. + +Our Stats API uses HTTP GET requests with JSON arguments and JSON responses. You can view here ([https://github.com/zooniverse/eras/wiki/API-Callout-Examples](https://github.com/zooniverse/eras/wiki/API-Callout-Examples)) for full documentation and more callout examples. + +In this site, we provide common examples project owners or user group admins might use in order to query specific volunteer classification/comment counts. + + +### Differences Between eras.zooniverse.org vs Defunct stats.zooniverse.org + +If you are familiar with our older stats service ([https://github.com/zooniverse/zoo-event-stats](https://github.com/zooniverse/zoo-event-stats); [https://stats.zooniverse.org/](https://stats.zooniverse.org/)), there are some key differences between the new service [https://eras.zooniverse.org](https://eras.zooniverse.org) and the old service [https://stats.zooniverse.org/](https://stats.zooniverse.org/). + + + +* **Differences in the Requests** + * URL changes + * No need to include `/counts` in URL for eras.zooniverse.org + * Period is now a parameter (`?period`) vs a fixed part of URL + * Period is not a required parameter in eras.zooniverse.org + * Eras.zooniverse.org uses pluralized version of `classifications` and `comments` + * Eg. [https://eras.zooniverse.org/classifications?period=week](https://eras.zooniverse.org/classifications?period=week) vs [https://stats.zooniverse.org/counts/classification/week](https://eras.zooniverse.org/classification/week) + * Valid `period`s are now only: + * Day + * Week + * Month + * Year + * Some requests in eras.zooniverse.org will require an Authorization Header +* **Differences in Responses** + * Responses of [https://eras.zooniverse.org](https://eras.zooniverse.org) will only return the total counts unless you specify a `period` you want to bucket your data by. + * Response keys are different + * [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 (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 **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 + +**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 _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: + +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: + + +## 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/querying-classification-counts-unauth.md b/querying-classification-counts-unauth.md new file mode 100644 index 0000000..d260c01 --- /dev/null +++ b/querying-classification-counts-unauth.md @@ -0,0 +1,252 @@ +--- +title: Querying Classification Counts (Unauthenticated) +layout: page +nav_order: 2 +--- + +# Querying Classification Counts (Unauthenticated) + +We allow querying classification counts without Authentication (i.e. No Authorization Header within your request) if you are querying by 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` + +**One caveat is that we do not allow you to query by BOTH project_id AND workflow_id (either one or the other).** + + +### Example: Querying Classification Counts in total for Zooniverse + +If one was curious on how many total classifications we currently have on the Zooniverse, you could query the following: + +``` +curl -G https://eras.zooniverse.org/classifications +``` + +This will return the total count of classifications of the entire Zooniverse. + +Response will look like: +``` +{ + "total_count": 770,522,706 +} +``` + + +### Example: Querying Classifications for a Specific Project + +If interested in querying classification count for a specific project, we can do the following: +``` +curl -G https://eras.zooniverse.org/classifications?project_id=1234 +``` + +Response will look like: +``` +{ + "total_count": 22,083 +} +``` + + +### Example: Querying Classifications for a Specific Project With Count Breakdown + +If interested in querying for classification count for a specific project (for eg. project with id `1234`) and also interested in the monthly counts that make up the total count of the response, we can query the following: +``` +curl -G https://eras.zooniverse.org/classifications?project_id=1234&period=month +``` + +Here, we utilize the `?period` parameter to bucket by month. Allowable `period`s are `day`, `week`, `month`, `year`. + +Response will look like: +``` +{ + "total_count": 377, + "data": [ + { + "period": "2022-12-01T00:00:00.000Z", + "count": 11 + }, + { + "period": "2023-01-01T00:00:00.000Z", + "count": 21 + }, + { + "period": "2023-02-01T00:00:00.000Z", + "count": 35 + }, + { + "period": "2023-03-01T00:00:00.000Z", + "count": 79 + }, + { + "period": "2023-04-01T00:00:00.000Z", + "count": 16 + }, + { + "period": "2023-05-01T00:00:00.000Z", + "count": 47 + }, + { + "period": "2023-06-01T00:00:00.000Z", + "count": 29 + }, + { + "period": "2023-07-01T00:00:00.000Z", + "count": 16 + }, + { + "period": "2023-08-01T00:00:00.000Z", + "count": 59 + }, + { + "period": "2023-09-01T00:00:00.000Z", + "count": 64 + } + ] +} +``` + + +### Example: Querying Classification Counts for a Specific Project With Count Breakdown Within A Certain Date Range + +If interested in querying for classification count for a specific project (for eg. project with id `1234`) between the days of September 18, 2023 and September 22, 2023, and also interested in the daily counts that make up the total count of the response, we can query the following: +``` +curl -G https://eras.zooniverse.org/classifications?project_id=1234&period=day&start_date=2023-09-17&end_date=2023-09-24 +``` + +**It is important to note that when entering a date range (a `start_date` or an `end_date` or both), dates entered MUST be in the format YYYY-MM-DD** + +Response: +``` +{ + "total_count": 41, + "data": [ + { + "period": "2023-09-18T00:00:00.000Z", + "count": 2 + }, + { + "period": "2023-09-19T00:00:00.000Z", + "count": 19 + }, + { + "period": "2023-09-20T00:00:00.000Z", + "count": 19 + }, + { + "period": "2023-09-22T00:00:00.000Z", + "count": 1 + } + ] +} +``` + +**The API uses UTC and are strings in the ISO 8601 “combined date and time representation” format (https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) :** + +`2015-05-15T15:50:38Z` + + +### Example: Querying Classification Counts of Multiple Projects With Count Breakdowns Within A Certain Date Range + +If interested in querying the classification counts of multiple projects (for eg. if one was the owner of projects with ID `1234` and `4321`) and were interested in total classification for both projects altogether between the days of May 05, 2015 and June 05, 2015, and also interested in the daily counts that make up the total count of the response, we can query the following: + +``` +curl -G https://eras.zooniverse.org/classifications?project_id=1234,4321&period=day&start_date-2015-05-05&end_date=2015-08-05 +``` + +**Note that the two project ids are separated by a `,`.** + +**We expect the response to give the TOTAL classification count of both projects** + + + +* **i.e. classification counts of project with id 1234 + classification counts of project with id 4321** + +Response: +``` +{ + "total_count": 76, + "data": [ + { + "period": "2015-04-24T00:00:00.000Z", + "count": 5 + }, + { + "period": "2015-04-25T00:00:00.000Z", + "count": 8 + }, + { + "period": "2015-04-28T00:00:00.000Z", + "count": 2 + }, + { + "period": "2015-04-29T00:00:00.000Z", + "count": 12 + }, + { + "period": "2015-05-06T00:00:00.000Z", + "count": 6 + }, + { + "period": "2015-05-13T00:00:00.000Z", + "count": 9 + }, + { + "period": "2015-05-17T00:00:00.000Z", + "count": 1 + }, + { + "period": "2015-05-19T00:00:00.000Z", + "count": 2 + }, + { + "period": "2015-05-20T00:00:00.000Z", + "count": 11 + }, + { + "period": "2015-05-21T00:00:00.000Z", + "count": 7 + }, + { + "period": "2015-05-22T00:00:00.000Z", + "count": 5 + }, + { + "period": "2015-05-23T00:00:00.000Z", + "count": 2 + }, + { + "period": "2015-05-26T00:00:00.000Z", + "count": 2 + }, + { + "period": "2015-05-28T00:00:00.000Z", + "count": 1 + }, + { + "period": "2015-06-02T00:00:00.000Z", + "count": 1 + }, + { + "period": "2015-06-03T00:00:00.000Z", + "count": 2 + } + ] +} +``` \ No newline at end of file diff --git a/querying-comment-counts.md b/querying-comment-counts.md new file mode 100644 index 0000000..103b089 --- /dev/null +++ b/querying-comment-counts.md @@ -0,0 +1,94 @@ +--- +title: Querying Comment Counts +layout: page +nav_order: 3 +--- + +## Querying Comment Counts + +We also allow querying comment counts without Authentication (i.e. No Authorization Header within your request). + +With comment counts you can also filter your count query by the following parameters: + + + +* project_id/s + * can search by multiple project_ids when entering a `,` separated string of ids + * eg. `?project_id=1,2,3,4` +* user_id/s + * can search by multiple user_ids when entering a `,` separated string of ids + * eg. `?user_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 comment counts bucketed by your entered period. + * Allowable buckets are either: + * `day` + * `week` + * `month` + * `year` + + +### 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: +``` +curl -G https://eras.zooniverse.org/comments +``` + +Response will look something like this: +``` +{ + "total_count":1637 +} + +``` + +### 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. + +``` +curl -G https://eras.zooniverse.org/comments?period=month&project_id=1234 +``` + +Similar to `/classifications` endpoint, valid `period` buckets are either by `day`, `week`, `month`, `year`. + +Response: +``` +{ + "total_count": 70, + "data": [ + { + "period": "2022-04-01T00:00:00.000Z", + "count": 5 + }, + { + "period": "2022-05-01T00:00:00.000Z", + "count": 6 + }, + { + "period": "2022-06-01T00:00:00.000Z", + "count": 34 + }, + { + "period": "2022-07-01T00:00:00.000Z", + "count": 19 + }, + { + "period": "2022-08-01T00:00:00.000Z", + "count": 1 + }, + { + "period": "2022-12-01T00:00:00.000Z", + "count": 1 + }, + { + "period": "2023-01-01T00:00:00.000Z", + "count": 4 + } + ] +} +``` \ No newline at end of file