.. meta::
    :description: This documentation will guide you through the use of the Memset API.

.. index::
   double: Methods; bandwidth

.. _bandwidth:

Bandwidth Methods
-----------------

API Methods for dealing with bandwidth information

.. function:: bandwidth.info

    Return bandwidth information.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :returns: a dictionary with the following keys:
    
        **service_type**
            Dictionary: a dictionary with the following keys:
                **bytes_in**:
                    Float: bytes in for the current month.
                **bytes_out**:
                    Float: bytes out for the current month.
                **daily_rate**:
                    Float: average total bandwidth usage per day.
                **predicted**:
                    Float: predicted total bandwidth usage by the end of the month.
                **connection_type**
                    String: Optional: 'metered', 'unmetered' or 'inarrears'.
                **max_burst**
                    Float: Optional: maximum burst in Mbps.
                **remaining**
                    Float: Optional: for metered connections, remaining bandwidth for current month.
                **inclusive_transfer**
                    Float: Optional: monthly data transfer in GB.
                **bandwidth_bank**
                    Float: Optional: extra transfer bank in GB per month.
                **contention**
                    Float: Optional: contention ratio.
                **ips**
                    List: Optional: a list of dictionaries. See below for a description of the dictionary keys.
    
    The **ips** attribute is a list of dictionaries with the following keys:
    
        **ip_address**
            Dictionary: a dictionary with the following keys:
                **bytes_in**:
                    Float: bytes in for the current day.
                **bytes_out**:
                    Float: bytes out for the current day.
    
    Some services may return several service types (i.e. Memstore will return cloud storage and CDN
    bandwidth information).
    
    Notes:
      * The fields *connection_type*, *max_burst* and *ips* are only available in servers.
      * The fields *remaining*, *inclusive_transfer* and *bandwidth_bank* are only available in servers using 'metered' connection type.
      * The field *contention* is only available in servers using 'unmetered' connection type.

.. function:: bandwidth.monthly_usage

    Return monthly bandwidth usage information in a given year.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param year: Period of data starting on 1st January of provided year. Ensure this value is less than or equal to 2100. Ensure this value is greater than or equal to 2000.
    :type year: Integer, Optional
    
    :returns: a dictionary with following keys:
    
        **service_type**
            List: a list of dictionaries with following keys:
                **date**
                    Date: period of the record (yyyy-mm).
                **bytes_in**
                    Float: bytes in for that date.
                **bytes_out**
                    Float: bytes out for that date.
    
    Some services, such as Memstore, will return bandwidth information for several service types
    (for example: the cloud storage itself and the CDN service).
    
    If the year is not provided, current year will be used.

.. function:: bandwidth.usage

    Return bandwidth usage information in last *period*.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param period: Period Acceptable values: 'day', 'week', 'month', 'quarter', 'halfyear', 'year'.
    :type period: String, Optional
    
    :returns: a dictionary with following keys:
    
        **service_type**
            List: a list of dictionaries with following keys:
                **date**
                    Date: period of the record.
                **bps_in**
                    Float: bits in per second for that date.
                **bps_out**
                    Float: bits out per second for that date.
    
    Some services, such as Memstore, will return bandwidth information for several service types
    (for example: the cloud storage itself and the CDN service).
    
    If the period is not provided, 'day' will be used.