.. _download-stats:


Get Resource Download Stats 
=============================

.. admonition:: API Endpoint: revision_download_stats_show
   
   Gets Stats for Resource or Resource Revision

This endpoint returns the download stats of a resource or revision as a list of dictionaries containing the datetime and count variables for the resource

|

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

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

   * - Parameter Definition
     - Description
     - Type
   * - ``id``
     - The id of the resource
     - ``string``
   * - ``revision_id``
     - The id of the resource revision
     - ``string``
   * - ``format_dates``
     - if true, dates will be formatted by month and year and download counts will be grouped
     - ``boolean``

.. note::
    The ``format_dates`` parameter is optional when running the API script


 
   

.. important::
    * When using ``id`` **ONLY**, the query will return the entire resource download history
    * When using ``revision_id`` **ONLY**, the query only return stats for a specific revision

.. warning::
    You must provide either ``id`` or ``revision_id``, but **NOT** both


|

Example 1: Get Download Stats for Latest Revision of a Resource and History of All Revisions of the Resource
-------------------------------------------------------------------------------------------------------------

.. tabs:: lang3

    .. code-tab:: 
      :caption: Input

        import requests

        headers = {
            "EDX-API-Key": 'YOUR-API-KEY-HERE',
            "User-Agent": 'EDX-USER',
            'Content-Type': 'application/json',
            'Accept':'application/json'
        }
                    
        data = {
            'id': 'RESOURCE-ID-HERE'  
        }

        url = 'https://edx.netl.doe.gov/api/3/action/resource_download_stats_show'
        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: Output

        {'help': '/api/3/action/help_show?name=resource_download_stats_show', 'success': True, 
        'result': {'count': 13, 'stats': [{'datetime': '2024-07-10T13:27:25.393476'}, 
        {'datetime': '2024-07-10T13:27:46.722838'}, {'datetime': '2024-07-10T13:27:48.764149'}, 
        {'datetime': '2024-07-11T15:53:41.581132'}, {'datetime': '2024-07-11T15:53:43.772783'}, {'datetime': '2024-07-11T15:53:45.481481'}, 
        {'datetime': '2024-07-11T15:53:47.087822'}, {'datetime': '2024-07-17T15:48:48.964589'}, {'datetime': '2024-07-17T15:48:51.294180'}, 
        {'datetime': '2024-07-17T15:48:52.807274'}, {'datetime': '2024-07-23T16:13:23.378989'}, {'datetime': '2024-07-25T16:55:10.881878'}, 
        {'datetime': '2024-08-01T10:52:56.585289'}]}}

|

Example 2: Get Download Stats for a Specific Resource Revision
--------------------------------------------------------------------

.. tabs:: lang3

    .. code-tab:: 
      :caption: Input

        import requests

        headers = {
            "EDX-API-Key": 'YOUR-API-KEY-HERE',
            "User-Agent": 'EDX-USER',
            'Content-Type': 'application/json',
            'Accept':'application/json'
        }
                    
        data = {
            'revision_id': 'REVISION-ID-HERE'  
        }

        url = 'https://edx.netl.doe.gov/api/3/action/resource_download_stats_show'
        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: Output

        {'help': '/api/3/action/help_show?name=resource_download_stats_show', 'success': True, 
        'result': {'count': 13, 'stats': [{'datetime': '2024-07-10T13:27:25.393476'}, {'datetime': '2024-07-10T13:27:46.722838'}, 
        {'datetime': '2024-07-10T13:27:48.764149'}, {'datetime': '2024-07-11T15:53:41.581132'}, {'datetime': '2024-07-11T15:53:43.772783'}, 
        {'datetime': '2024-07-11T15:53:45.481481'}, {'datetime': '2024-07-11T15:53:47.087822'}, {'datetime': '2024-07-17T15:48:48.964589'}, 
        {'datetime': '2024-07-17T15:48:51.294180'}, {'datetime': '2024-07-17T15:48:52.807274'}, {'datetime': '2024-07-23T16:13:23.378989'}, 
        {'datetime': '2024-07-25T16:55:10.881878'}, {'datetime': '2024-08-01T10:52:56.585289'}]}}

|

Example 3: Get Download Stats Using ``format_dates`` to Group Counts
-------------------------------------------------------------------------

.. tabs:: lang3

    .. code-tab:: 
      :caption: Input

        import requests

        headers = {
            "EDX-API-Key": 'YOUR-API-KEY-HERE',
            "User-Agent": 'EDX-USER',
            'Content-Type': 'application/json',
            'Accept':'application/json'
        }
                    
        data = {
            'id': 'RESOURCE-ID-HERE',
            'format_dates': True
        }

        url = 'https://edx.netl.doe.gov/api/3/action/resource_download_stats_show'
        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: Output

        {'help': '/api/3/action/help_show?name=resource_download_stats_show', 'success': True,
        'result': {'count': 19, 'stats': [{'datetime': '07/2024', 'count': 12},
        {'datetime': '08/2024', 'count': 7}]}}