Class Client

object --+
         |
        Client

DeviceAtlas Cloud API. This client library can be used to easily get device data from the DeviceAtlas Cloud service. To reduce cloud calls and improve performance the API locally caches the data returned from the cloud service. This API caches data on the disk. If the cache path is not writable the API will not proceed (even if the device cache is turned off).

It is recommended to set DEBUG = True during implementation so if the cache path is not writable the errors will not be ignored. The client is queried by passing either a set (dictionary) of HTTP headers to it (if being used in a Django application request.META can be passed to the API) or a user-agent string. The device properties will then be returned.

Example 1:

Passing a custom set of HTTP headers.

>>> # Import the DeviceAtlas Cloud API module.
>>> from deviceatlas.cloud.device import Client
>>>
>>> # Get data by passing headers (headers named are not case sensitive and may include "_" or start with "HTTP_").
>>> headers = {
>>>     'User-Agent': 'Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaN95_8GB/15.0.015; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413',
>>>     'X-Profile': 'http://nds.nokia.com/uaprof/NN95_8GB-1r100.xml',
>>>     'Accept': 'text/html,text/css',
>>>     'Accept-Language': 'en-us,en;q=0.5'
>>> }
>>>
>>> # Instantiate a client for the DeviceAtlas Cloud API.
>>> client = Client()
>>>
>>> # Set the licence key used by the DeviceAtlas Cloud API.
>>> client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
>>>
>>> try:
>>>     results = client.getDeviceData(headers)
>>>
>>>     # If DEBUG = True and errors happened while fetching data.
>>>     error = results.get(client.KEY_ERROR, None)
>>>
>>>     # The User-Agent used in the lookup.
>>>     user_agent = results.get(client.KEY_USERAGENT, '')
>>>
>>>     # The source of the data - cache, cloud or None.
>>>     data_source = results.get(client.KEY_SOURCE, '')
>>>
>>>     # The actual device properties.
>>>     properties = results.get(client.KEY_PROPERTIES, {})
>>>
>>> except Exception as err:
>>>     # Handle all errors.

Example 2:

Passing a User-Agent.

>>> # Import the DeviceAtlas Cloud API module.
>>> from deviceatlas.cloud.device import Client
>>>
>>> ua = 'Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaN95_8GB/15.0.015; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413'
>>>
>>> # Instantiate a client for the DeviceAtlas Cloud API.
>>> client = Client()
>>>
>>> # Set the licence key used by the DeviceAtlas Cloud API.
>>> client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
>>>
>>> try:
>>>     results = client.getDeviceData(user_agent=ua)
>>>
>>>     # If DEBUG = True and errors happened while fetching data.
>>>     error = results.get(client.KEY_ERROR, None)
>>>
>>>     # The User-Agent used in the lookup.
>>>     user_agent = results.get(client.KEY_USERAGENT, '')
>>>
>>>     # The source of the data - cache, cloud or None.
>>>     data_source = results.get(client.KEY_SOURCE, '')
>>>
>>>     # The actual device properties.
>>>     properties = results.get(client.KEY_PROPERTIES, {})
>>>
>>> except Exception as err:
>>>     # Handle all errors

Example 3:

Passing set of HTTP headers from a framework such a Django.

>>> # Import the DeviceAtlas Cloud API module.
>>> from deviceatlas.cloud.device import Client
>>>
>>> # Instantiate a client for the DeviceAtlas Cloud API.
>>> client = Client()
>>>
>>> # Set the licence key used by the DeviceAtlas Cloud API.
>>> client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
>>>
>>> try:
>>>     results = client.getDeviceData(request.META)
>>>
>>>     # If DEBUG = True and errors happened while fetching data.
>>>     error = results.get(client.KEY_ERROR, None)
>>>
>>>     # The User-Agent used in the lookup.
>>>     user_agent = results.get(client.KEY_USERAGENT, '')
>>>
>>>     # The source of the data - cache, cloud or None.
>>>     data_source = results.get(client.KEY_SOURCE, '')
>>>
>>>     # The actual device properties.
>>>     properties = results.get(client.KEY_PROPERTIES, {})
>>>
>>> except Exception as err:
>>>     # Handle all errors.

Example 4:

Using the built-in User-Agent.

>>> # Import the DeviceAtlas Cloud API module.
>>> from deviceatlas.cloud.device import Client
>>>
>>> # Instantiate a client for the DeviceAtlas Cloud API.
>>> client = Client()
>>>
>>> # Set the licence key used by the DeviceAtlas Cloud API.
>>> client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
>>>
>>> try:
>>>     results = client.getDeviceData(test_mode=True)
>>>
>>>     # if DEBUG = True and errors happened while fetching data.
>>>     error = results.get(client.KEY_ERROR, None)
>>>
>>>     # The User-Agent used in the lookup.
>>>     user_agent = results.get(client.KEY_USERAGENT, '')
>>>
>>>     # The source of the data - cache, cloud or None.
>>>     data_source = results.get(client.KEY_SOURCE, '')
>>>
>>>     # The actual device properties.
>>>     properties = results.get(client.KEY_PROPERTIES, {})
>>>
>>> except Exception as err:
>>>     # Handle all errors.

>>> client = Client()
>>> client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
>>> client.getDeviceData(user_agent='user-agent')
{'source': 'data-source','properties': {'property_name': property_value, ...},'useragent': 'user-agent', _error: 'if-any-happens'}}

>>> client = Client()
>>> client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
>>> client.getServersLatencies()
{'host':'region0.deviceatlascloud.com','avg':0.123456789,'port':80,'latencies':[0.123456789, 0.123456789, 0.123456789]},...}

>>> client = Client()
>>> client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
>>> client.getServers()
{'host':'region0.deviceatlascloud.com','avg':0.123456789,'port':80,'latencies':[0.123456789, 0.123456789, 0.123456789]},...}

>>> client = Client()
>>> client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
>>> client.rankServers()
{'host':'region0.deviceatlascloud.com','avg':0.123456789,'port':80,'latencies':[0.123456789, 0.123456789, 0.123456789]},...}