# DeviceAtlas Device Detection API # The DeviceAtlas Device Detection API provides a way to detect devices based on the HTTP headers. Using the headers, the API returns device information such as screen width, screen height, is mobile, vendor, model etc. To see a full list of properties in DeviceAtlas please visit: https://deviceatlas.com/resources/available-properties . ### Data File ### The DeviceAtlas API relies on a device data file to function. DeviceAtlas provides daily data file updates so it is recommended to download the data file on a regular basis. This can be done manually from your account page or automated via the https://deviceatlas.com/getJSON page. For more information please see: https://deviceatlas.com/resources/getting-the-data ### Dependencies ### This library does not depend on any third party libraries. ### Library ### The DeviceAtlas Device Detection API consists of one module that contains all common API classes plus the ones for the Device API. #### DeviceAtlas common (mobi.mtld.da) #### Contains the shared classes which are common between the DeviceAtlas APIs. When using DeviceApi this module has to be accessible from your code. #### DeviceApi (mobi.mtld.da.device) #### This module contains the classes that the DeviceApi needs from mobi.mtld.da.device.device_api to load the Device data and detects and returns the properties for a set of request headers or the user-agent. Client-side properties can be optionally passed to this library to get more accurate results. ### The 2.0 API interface ### * This is the new standard interface, common across the DeviceAtlas APIs. * This interface is intended to be simple to use, as the interface includes custom objects for getting the detected property set and getting a single property value. * Unlike the former interface, this interface is not a set of static methods. This allows the interface to have more encapsulation, requiring fewer and simpler methods. This new API is highly maintainable and flexible for future improvements and new features. #### Basic Usage #### The API can be used as follows: To lookup the properties by manually passing the Hash of headers to the API: ```python # (1) create an instance with default API settings device_api = DeviceApi() # (2) load the data file try: device_api.load_data_from_file("/path/to/datafile.json") except: # handle the exceptions related to loading the data file # (3) look up device properties based on your custom header set headers = {"HEADER NAME": "HEADER VALUE"} properties = device_api.get_properties(headers) # (4) use the properties - e.g. detect mobile device # if there is a property named "mobileDevice" and the value is true if properties.contains("mobileDevice", True): # example 1: Get the screen width for image optimization if "displayWidth" in properties: display_width = int(properties["displayWidth"]) else: display_width = 100 # example 2: Get the device vendor name if "vendor" in properties: vendor = properties.get("vendor") else: vendor = "" # example 3: Touch screen optimization use_bigger_icons = properties.contains("touchScreen", True) # example 4: Send Geo Location JS to client? supports_geo_location = properties.contains("js.geoLocation", True) ``` ### Client Side Component ### In addition to the properties from the data file, properties can be gathered from the client's browser and used both on the client side and on the server side. Please see the [ClientSide readme file](README.ClientSide.html) for more information. #### Usage with Client Side Component #### In addition to normal usage, DeviceAtlas has the capability to capture client side properties and merge them into the server side properties. The "deviceatlas.min.js" file must be included on your webpage in order for it to detect the client side properties. The contents of this cookie are automatically detected with the request headers or can be passed separately, with Headers or a User-Agent, to get the combined properties back.. Both sets of properties are used in additional logic to determine other properties such iPhone and iPad models which are normally not detectable. * For instance, from a class that inherits from BaseHTTPRequestHandler. To lookup the properties by manually passing the headers and the client-side properties to the API: ```python # (1) create an instance with default API settings device_api = DeviceApi() # (2) load the data file try: device_api.load_data_from_file("/path/to/datafile.json") except: # handle the exceptions related to loading the data file # (3) look up device properties client_side_properties = "PROPERTY1:VALUE1|PROPERTY2:VALUE2|PROPERTY3:VALUE3" properties = device_api.get_properties(self.headers, client_side_properties) # (4) use the properties - e.g. detect mobile device # if there is a property named "mobileDevice" and the value is true if properties.contains("mobileDevice", True): # example 1: Get the screen width for image optimization if "displayWidth" in properties: display_width = int(properties["displayWidth"]) else: display_width = 100 # example 2: Get the device vendor name if "vendor" in properties: vendor = properties.get("vendor") else: vendor = "" # example 3: Touch screen optimization use_bigger_icons = properties.contains("touchScreen", True) # example 4: Send Geo Location JS to client? supports_geo_locatin = properties.contains("js.geoLocation", True) ``` ### Examples ### Various examples are included in this package to clearly demonstrate the API features, usage and some use cases. These examples are very simple and are heavily commented. #### Basic Usage #### Includes six examples. Three simple examples which use DeviceApi to detect and get properties from header sets and client-side component. These examples show how the headers and client-side components help getting precise property values from Opera mini browsers and iPhone devices. Three simple web examples with custom API settings. Usage of the client-side-component is shown in these web examples. #### Redirection #### This web example uses DeviceApi to get properties for the current request and then uses some basic property values to decide which website provides the most suitable content for the device making the request. #### Content Adaptation #### This web example uses DeviceApi to get properties for the device making the current request and then uses some basic property values to choose a suitable template to wrap around the content. #### Analytics #### This web example uses DeviceApi to get properties for user-agents from a given list. Some properties such as vendor, browser name and device type are aggregated and the results are displayed as graphs and numbers. #### Content Targeting #### This example uses DeviceApi to detect the device and use some of its properties to show certain advertisements and download links which may be related or of interest to the user, considering his/her device. This is a web example. To run the web application examples, follow these steps: * From the example directory, run "python example.py" * In a browser http://localhost:3000/example to see the results. ### Upgrading ### If you are currently using a DeviceAtlas Enterprise API version prior to 2.0. Please see the [Upgrade readme file](README.Upgrade.html) for more information. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ (c) 2014 Afilias Technologies Ltd (dotMobi). All rights reserved. https://deviceatlas.com _ <!-- HTML+JS for document formatting when opened in browser --> <div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li class="disabled"><a href="README.DeviceApi.html">Device Detection API</a></li><li><a href="README.Upgrade.html">Device Detection API Upgrade</a></li><li><a href="DeviceApiDocs/mobi.mtld.da.device.device_api.DeviceApi-class.html">Device API docs</a></li><li class="divider"></li><li><a href="README.ClientSide.html">Client Side Component</a></li><li><a href="README.ConnectivityAnalyser.html">Connectivity Analyser</a></li><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="CarrierApiDocs/mobi.mtld.da.carrier.carrier_api.CarrierApi-class.html">Carrier API docs</a></li></ul></div>