# DeviceAtlas Device Identification API #
The DeviceAtlas Device Identification API provides a way to detect devices based on
the HTTP headers, user-agent or Make/Model string. 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. Please ensure you are using an up-to-date data file.
The data file can be downloaded from your account page or via
https://deviceatlas.com/getJSON page.
For more information please see:
https://deviceatlas.com/resources/getting-the-data
### 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. It is strongly recommended to use the Client-side component when using
the DeviceAtlas Device Detection API within a web application in order to
correctly identify iOS devices. The "deviceatlas.min.js" file must be included on
your web page in order for it to detect the client side properties. The contents of
this cookie are automatically detected by the API. Please see the
[ClientSide readme file](README.ClientSide.html) for more information.
### Basic Usage ###
The API can be used as follows:
#### Detection via HTTP headers ###
To lookup the properties by manually passing a dictionary of HTTP headers to the API:
```python
from mobi.mtld.da.device.device_api import DeviceApi
from mobi.mtld.da.exception.data_file_exception import DataFileException
headers = {
"User-Agent": "USER-AGENT",
...
...
}
device_api = DeviceApi()
try:
device_api.load_data_from_file("/path/to/datafile.json")
properties = device_api.get_properties(headers)
except DataFileException:
# Handle the exceptions related to loading the data file
```
#### Detection via User-Agent ###
To lookup the properties by manually passing a user-agent string to the API:
```python
from mobi.mtld.da.device.device_api import DeviceApi
from mobi.mtld.da.exception.data_file_exception import DataFileException
user_agent = "USER-AGENT"
device_api = DeviceApi()
try:
device_api.load_data_from_file("/path/to/datafile.json")
properties = device_api.get_properties(user_agent)
except DataFileException:
# Handle the exceptions related to loading the data file
```
#### 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 mobi.mtld.da.device.device_api import DeviceApi
from mobi.mtld.da.exception.data_file_exception import DataFileException
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 DataFileException:
# Handle the exceptions related to loading the data file
```
#### 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)
```
### Examples ###
Please see the Examples directory for examples that encompass the following scenarios:
1. **Analytics**: Located at Examples/device/analytics
2. **Usage within a command line application**: Located at Examples/device/basic_usage_cli_detect
3. **iPhone detection**: Located at Examples/device/basic_usage_cli_detect_iphone
4. **Detecting Opera Mini browser device properties**: Located at Examples/device/basic_usage_cli_detect_opera
4. **Analyse a list of user-agents**: Located at Examples/device/basic_usage_cli_detect_list_of_uas
6. **Usage within a web application**: Located at Examples/device/basic_usage_web
7. **Content adaptation**: Located at Examples/device/content_adaptation
8. **Content targeting**: Located at Examples/device/content_targeting
9. **Redirection**: Located at Examples/device/redirection
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved. _
_ https://deviceatlas.com _