.. _group-count:

Collect Group Count Stats
============================

.. admonition:: API Endpoint: get_group_count
   
   Collects User Count Stats

.. important:: 
  An API Key is required for ALL private workspace activities
    
  The API Key name component can be added to your header using any of the following ways, "X-CKAN-API-Key", "EDX-API-Key", or "Authorization".


.. note::
    Only System Admins can user the stats collection APIs

|
|

Parameter Definitions
-------------------------

.. list-table:: 
   :header-rows: 1

   * - Parameter Name
     - Description
     - Required Fields
   * - ``name``
     - Name of the group
     - *Optional*
   * - ``id``
     - User ID number associated with EDX group
     - *Optional*
   * - ``title``
     - Title of submission found within the group
     - *Optional*
   * - ``description``
     - Description of the submission found within the group
     - *Optional*
   * - ``created``
     - Date the group was created
     - *Optional*
   * - ``state``
     - State of the group
     - *Optional*
   * - ``operator``
     - Filters the "WHERE" clause within the ``state`` field
     - *Optional*
   * - ``revision_id``
     - ID of the revision of a submission within the group
     - *Optional*
   * - ``type``
     - Type of the submission within the group
     - *Optional*
   * - ``approval_status``
     - Approval status of a submission within the group
     - *Optional*
   * - ``image_url``
     - URL of an image resource found within the group
     - *Optional*
   * - ``owner_id``
     - ID of the owner for a submission in a group
     - *Optional*
   * - ``landing_page``
     - String text name of the landing page for a group
     - *Optional*
   * - ``group_reviewed``
     - Boolean to determine if the submission is group reviewed
     - *Optional*
   * - ``open_access``
     - Boolean to determine if the group has open access
     - *Optional*
   * - ``netl_only``
     - Boolean to determine if the group is only available to access by NETL-only users
     - *Optional*
   * - ``last_modified``
     - Date of last modification to a submission within the group
     - *Optional*
   * - ``project_number``
     - Project number associated with a submission within a group
     - *Optional*
   
.. important::
  The ``landing_page`` parameter value should be set to ``dashboard`` if using this field, unless another page has been specified as the landing page

|
|

.. note::
    The ``date_field`` parameter must be set to a valid column type
      * ``last_modified``
      * ``created``

.. important::
    The ``operator`` parameter must come after the column name for the parameter in the ``query_group``


.. note::
  Values for the ``operator`` parameter are as follows:
    * less than (<)
    * greater than (>)
    * less than equal to (<=)
    * greater than equal to (>=)
    * like 
    * not equals (!)
    * equals (=) 

    By deafult the operator parameter to ``equals (=)``




|
|

.. note::
    Within the ``query`` parameter, the values must be set up as a list of dictionaries nested within the main ``query``'s main dictionary

.. important::
    Within the ``query`` parameter dictionary:
        * Multiple requests for ``query_group`` can be called within the main ``query`` dictionary
        * Within each ``query_group`` request, the value will be placed within its own dictionary
            * Within the ``query_group`` request, values stored within the nested dictionary will be comma separated
            * The comma separation works as an "OR" condition to check the value of the first field "OR" the value of the second field
            * Ex: 'query_group': [{'state': 'active'}, {'state': 'pending'}]


|
|

Example 1: Simplified Group Count Stat Collection
-----------------------------------------------------------

.. attention:: 
   * Add the ``"User-Agent":`` parameter within the ``headers`` of the API request
   * Set  ``"User-Agent":`` to the value ``"EDX-USER"``


.. tabs:: lang3

    .. code-tab:: python

      import requests

      headers = {
        "EDX-API-Key": '<YOUR_EDX_API_KEY>',
      #    "EDX-API-Key": '<YOUR_EDX_API_KEY>',
        "User-Agent": 'EDX-USER',
        'Content-Type': 'application/json',
        'Accept':'application/json'
      }

      data = {
        'query': [{'query_group': [{'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}]}], # Required.
        'start_date': '<START-DATE>', # Required. Date must be in date format (E.g. YYYY-MM-DD) and not greater than current date. 
                                    # start_date cannot be greater than end_date 
        'end_date': '<END-DATE>', # Required. Date must be in date format (E.g. YYYY-MM-DD) and not greater than current date.
                                  # end_date cannot be less than start_date
        'date_field': '<ENTER-DATE-FIELD-PARAMETER-HERE>'
      }

      url = 'https://edx.netl.doe.gov/api/3/action/get_group_count'
      r = requests.post(
        url, # URL to API endpoint
        headers=headers, # Headers dictionary
        json=data, # Dictionary of data params

      )
      r_json = r.json()
      print (r.json())



    .. code-tab:: output
        :caption: Successful Output

        {'help': '/api/3/action/help_show?name=get_group_count', 'success': True, 'result': {'count': 1}}
    
    .. code-tab:: output
        :caption: Failed Output

        {'help': '/api/3/action/help_show?name=get_group_count', 'error': {'query': 'Field "test" not recognized in group table.', '__type': 'Validation Error'},
        'success': False}

|
|

Example 2: Advanced Group Count Stat Collection 
--------------------------------------------------------

.. attention:: 
   * Add the ``"User-Agent":`` parameter within the ``headers`` of the API request
   * Set  ``"User-Agent":`` to the value ``"EDX-USER"``


.. tabs:: lang3

    .. code-tab:: python

      import requests

      headers = {
        "EDX-API-Key": '<YOUR_EDX_API_KEY>',
      #    "EDX-API-Key": '<YOUR_EDX_API_KEY>',
        "User-Agent": 'EDX-USER',
        'Content-Type': 'application/json',
        'Accept':'application/json'
      }

      data = {
        'query': [{'query_group': [{'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}]}, {'query_group': [{'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}]}], # Required.
        'start_date': '<START-DATE>', # Required. Date must be in date format (E.g. YYYY-MM-DD) and not greater than current date. 
                                    # start_date cannot be greater than end_date 
        'end_date': '<END-DATE>', # Required. Date must be in date format (E.g. YYYY-MM-DD) and not greater than current date.
                                  # end_date cannot be less than start_date
        'date_field': '<ENTER-DATE-FIELD-PARAMETER-HERE>'
      }

      url = 'https://edx.netl.doe.gov/api/3/action/get_group_count'
      r = requests.post(
        url, # URL to API endpoint
        headers=headers, # Headers dictionary
        json=data, # Dictionary of data params

      )
      r_json = r.json()
      print (r.json())


    .. code-tab:: output
        :caption: Successful Output

        {'help': '/api/3/action/help_show?name=get_group_count', 'success': True, 'result': {'count': 1}}
    
    .. code-tab:: output
        :caption: Failed Output

        {'help': '/api/3/action/help_show?name=get_group_count', 'error': {'query': 'Field "test" not recognized in group table.', '__type': 'Validation Error'},
        'success': False}

|
|