< page.
> **Note:** The 3.x API is only compatible with the version 3 data file which is downloadable from the DeviceAtlas website.
The version 2 data file is only compatible with the production 2x APIs.
### Loading The Data File ###
The DeviceAtlas API provides a function to load the data file:
* `device_api.load_data_from_file("/path/to/datafile.json")`
The exception DataLoadingException is thrown by the above methods in case the data file cannot be loaded.
Please see the sample code later in this document for how to call these methods.
## Client Side Library - Apple Device Identification ##
In addition to the server-side API, an optional client-side Javascript library
is available. This library is important for two reasons:
1. It facilitates identification of Apple devices. Apple devices are _not_
identifiable using only HTTP User-Agent data.
2. It allows for the collection of dynamic or changing properties.
When the client-side library is embedded in a web page it collects additional
properties from the client's web browser. This data is then sent back to the
server and must be passed to the DeviceAtlas API along with the HTTP headers.
The combination of the client data and the server side data allow for accurate
identification of Apple devices.
The client-side library may be included on a webpage by adding the following
snippet:
```Javascript
<!-- Adding the DeviceAtlas client side component to get client side properties -->
<script type="text/javascript" src="https://cs-cdn.deviceatlas.com/dacs.js" async></script>
```
By default, the client-side library returns the data via a cookie. If this is
present in the `HttpServletRequest` object it will be automatically used. The
cookie name is configurable via the `Config` class.
Alternatively, the client data may be returned via AJAX and passed to the server
side API manually.
For additional information, please see the [Client Side Library](https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html) documentation.
## Setup & Usage ##
The usage of the DeviceAtlas server side library is straightforward. In all
cases, the data file must be loaded before any device identification calls are
made.
> **Note:** It is highly recommended to ensure the data file is only loaded once.
This is particularly important for batch processing and web applications.
### Python Version ###
The DeviceAtlas API requires at least the Python 3.6.x (or above)
### Usage Examples ###
The following sections shows how to call the DeviceApi. Please note that
exception handling has been omitted for brevity.
#### EXAMPLE 1: Detection via HTTP headers ###
To look up the properties by manually passing a dictionary of HTTP headers to the API.
It is recommended to pass all of the HTTP headers
provided by the client. The below example shows passing a User-Agent along with
a Client Hint header. In the example, the device properties are detected from
the User-Agent and the browser properties are detected from the Client Hint
header.
```python
from com.deviceatlas.device.device_api import DeviceApi
from com.deviceatlas.exception.data_loading_exception import DataLoadingException
headers = {
"User-Agent": "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/102.0.0.0 Mobile Safari/537.36",
"Sec-CH-UA-Full-Version-List": "\" Not A;Brand\";v=\"99.0.0.0\", \"Chromium\";v=\"102.0.5005.125\", \"Google Chrome\";v=\"102.0.5005.25\""
}
device_api = DeviceApi()
try:
device_api.load_data_from_file("/path/to/datafile.json")
properties = device_api.get_properties(headers)
except DataLoadingException:
# Handle the exceptions related to loading the data file
```
#### EXAMPLE 2: Detection via User-Agent ###
To lookup the properties by manually passing a user-agent string to the API:
```python
from com.deviceatlas.device.device_api import DeviceApi
from com.deviceatlas.exception.data_loading_exception import DataLoadingException
user_agent = "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/102.0.0.0 Mobile Safari/537.36"
device_api = DeviceApi()
try:
device_api.load_data_from_file("/path/to/datafile.json")
properties = device_api.get_properties(user_agent)
except DataLoadingException:
# Handle the exceptions related to loading the data file
```
#### EXAMPLE 3: Detection via Make/Model ###
To lookup the properties by manually passing a Make/Model string to the API.
DeviceAtlas expects the make/model string in a specific format, this format
and how to obtain the Make/Model string can be found under the
"Expected string format for DeviceAtlas lookup" section [here](https://deviceatlas.com/resources/getting-started-enterprise-for-apps).
```python
from com.deviceatlas.device.device_api import DeviceApi
from com.deviceatlas.exception.data_loading_exception import DataLoadingException
make_model = "samsung sm-n9005"
device_api = DeviceApi()
try:
device_api.load_data_from_file("/path/to/datafile.json")
properties = device_api.get_properties(make_model)
except DataLoadingException:
# Handle the exceptions related to loading the data file
```
#### EXAMPLE 4: Using the properties ####
```python
# 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
display_width = 0
if "displayWidth" in properties:
display_width = int(properties.get("displayWidth"))
# Example 2: Get the screen width for image optimization
vendor = ""
if "vendor" in properties:
vendor = str(properties.get("vendor"))
# Example 3: Get the screen width for image optimization
use_bigger_icons = properties.contains("touchScreen", True)
# Example 4: Send Geo Location JS to client?
support_geo_location = properties.contains("js.geoLocation", True)
# Example 5: or get the property value as a string with an internal check to verify
# if the property exists in the set, otherwise the defaultValue is returned instead.
browser_name = properties.get_or_default_str("browserName", "")
```
#### EXAMPLE 5: Configuration ####
During instantiation of the `DeviceApi` object an optional config parameter may
be passed. The example below shows the setting of a custom cookie name that the
DeviceAtlas client-side data should be found in.
```python
from com.deviceatlas.device.device_api import DeviceApi
from com.deviceatlas.device.config import Config
config = Config()
config.set_cookie_name("DeviceAtlasClientSide")
# override default cache size
config.set_max_cache_entries(4096)
device_api = DeviceApi(config)
```
#### Additional Examples ####
Please find more complete examples in the /Examples directory.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2024. 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 Identification API</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">DeviceAtlas API Docs</a></li></ul></div>]]>