.. _resource-count:

Collect Resource Count Stats
==============================

.. admonition:: API Endpoint: get_resource_count
   
   Collects Resource 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
   * - ``query``
     - Parameter used to list nested parameters within the dictionary in the parameter
     - **Required**
   * - ``query_group``
     -  Parameter used to create a nested dictionary to query fields. 
     - **Required**
   * - ``start_date``
     - Start date of the query date range
     - **Required**
   * - ``end_date``
     - End date of the query date range. Cannot be greater than the current date
     - **Required**
   * - ``date_field``
     - Field that is queried to match the value within the date range
     - **Required**

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




|
|

Parameter Definitions for ``query_group`` within User Table
-------------------------------------------------------------

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

   * - Parameter Name
     - Description
     - Required Fields
   * - ``id``
     - User ID number associated with the resource
     - *Optional*
   * - ``url``
     - URL path to the resource
     - *Optional*
   * - ``format``
     - Format of the resource (Ex: PDF, JPG, MP3,CSV,PNG, etc.)
     - *Optional*
   * - ``description``
     - Description of the resource
     - *Optional*
   * - ``position``
     - Integer position of the resource within the submission
     - *Optional*
   * - ``revision_id``
     - ID of the resource revision of resource metadata
     - *Optional*
   * - ``hash``
     - MD5 hash used to ensure data integrity
     - *Optional*
   * - ``state``
     - State of the resource within a submission 
     - *Optional*
   * - ``operator``
     - Filters the "WHERE" clause within the ``state`` field
     - *Optional*
   * - ``extras``
     - "Extras" column data stored within the resource table
     - *Optional*
   * - ``name``
     - Name of the resource
     - *Optional*
   * - ``resource_type``
     - The type of resource and how it was obtained (Ex: file.upload)
     - *Optional*
   * - ``mimetype``
     - Mime type of the resource (Ex: image)
     - *Optional*
   * - ``mimetype_inner``
     - Inner mime type of the resource (Ex: image/jpeg)
     - *Optional*
   * - ``size``
     - Big Integer data for the size of the resource
     - *Optional*
   * - ``last_modified``
     - Date of last modification to a resource
     - *Optional*
   * - ``cache_url``
     - Project number associated with a submission within a workspace
     - *Optional*
   * - ``cache_last_updated``
     - Date of the last update to the cache URL
     - *Optional*
   * - ``webstore_url``
     - Deprecated Column
     - *Optional*
   * - ``webstore_last_updated``
     - Deprecated column
     - *Optional*
   * - ``created``
     - Date the resource was created
     - *Optional*
   * - ``url_type``
     - State of the resource (Ex: state : active)
     - *Optional*
   * - ``package_id``
     - ID of the resource revision of resource metadata
     - *Optional*
   * - ``license_type``
     - Type of the submission within the workspace
     - *Optional*
   * - ``owner_org``
     - Organization associated with the owner of the resource 
     - *Optional*
   * - ``folder_id``
     - Folder ID associated with the resource
     - *Optional*
   * - ``recycle_removed``
     - Boolean to determine if the resource was removed via recycle bin
     - *Optional*
   * - ``rating``
     - Numeric rating the resource has been given
     - *Optional*
   * - ``fgdc_metadata``
     - Boolean to determine if the resource contains  fgdc metadata
     - *Optional*
   * - ``owner``
     - Owner of the resource
     - *Optional*
   * - ``key``
     - Location of the actual file
     - *Optional*
   

|
|

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

.. 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 (=)``




|
|

Example 1: Simplified Resource 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>',
        "User-Agent": 'EDX-USER',
        'Content-Type': 'application/json',
        'Accept':'application/json'
      }

      data = {
        'query': [
            {                                         
              'query_group': [{'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}, {'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}],
            }
          ], # Required. Must be a list of dictionaries. 
          # Ex: WHERE (mimetype = 'image/svg+xml' OR mimetype = 'image/png') AND (owner ='admin' OR owner = 'tjones') AND state = 'active'
        '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_resource_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_resource_count', 'success': True, 'result': {'count': 1819}}

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

        {'help': '/api/3/action/help_show?name=get_resource_count', 'error': {'date_field': ['Please enter correct value.'], '__type': 'Validation Error'}, 'success': False}


|
|

Example 2: Advanced Resource Stat Collection with Multiple Query Parameters
--------------------------------------------------------------------------------

.. 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>',
        "User-Agent": 'EDX-USER',
        'Content-Type': 'application/json',
        'Accept':'application/json'
      }

      data = {
        'query': [
            {                                         
              'query_group': [{'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}, {'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}],
            },
            #AND
            {                                
              'query_group': [{'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}, {'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}]
            },
            #AND
            {
              'query_group': [{'<ENTER-PARAMETER-HERE>': '<ENTER-PARAMETER-VALUE-HERE>'}]
            }
          ], # Required. Must be a list of dictionaries. 
          # Ex: WHERE (mimetype = 'image/svg+xml' OR mimetype = 'image/png') AND (owner ='admin' OR owner = 'tjones') AND state = 'active'
        '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_resource_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_resource_count', 'success': True, 'result': {'count': 1819}}

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

        {'help': '/api/3/action/help_show?name=get_resource_count', 'error': {'date_field': ['Please enter correct value.'], '__type': 'Validation Error'}, 'success': False}