Package com.deviceatlas.device

Class DeviceApi

java.lang.Object
com.deviceatlas.BaseDeviceAtlasApi
com.deviceatlas.device.DeviceApi
All Implemented Interfaces:
DeviceAtlasApi
Direct Known Subclasses:
DeviceApiWeb, DeviceApiWebJakarta
public class DeviceApi extends BaseDeviceAtlasApi

The DeviceAtlas device detection API provides a way to detect devices based on the HTTP headers. Using these headers, the API returns device properties such as screen width, screen height, is mobile, vendor, model etc. If you want to use the DeviceAtlas API in a servlet container then it is strongly recommended to use DeviceApiWeb instead of this library.

The DeviceApiWeb is preferred when you want to perform real-time detection of a user's device in a servlet container.

The DeviceApi is preferred when you want to perform device outside of a servlet container or from an off-line User-Agent list or header set.


getProperties(Map<String, String> headers, String clientSide).

To get the most accurate results: 1- Pass all of the HTTP headers. 2- Use the DeviceAtlas Client-side component and pass the result.

When you have limited data you can also use these alternatives:

getProperties(Map<String, String> headers).

getProperties(String userAgent, String clientSide).

getProperties(String userAgent).

Example usage:

 Map<String, String> headers = new HashMap&lt&gt();
 headers.put("user-agent", "...");
 headers.put("accept-language", "...");
 // add any other available header...

 DeviceApi deviceApi = new DeviceApi();

 try {
     DeviceApi.loadDataFromFile("/path/to/datafile.json");

     // get all properties from the headers
     Properties props = DeviceApi.getProperties(headers);

     // .... use the properties ....
     if (props.contains("isMobilePhone", true)) {
         // it is a mobile phone
     }
     if (props.containsKey("model")) {
         String deviceModel = props.get("model").asString();
     }
     if (props.containsKey("yearReleased")) {
         int deviceModel = props.get("yearReleased").asInteger();
     }
 } catch (...) {
     ...
 }
Copyright (c) DeviceAtlas Limited 2026. All Rights Reserved.

  • Field Details

  • Constructor Details

    • DeviceApi

      public DeviceApi()
      Constructs a DeviceApi instance with default config. You can see the default config here: Config.
      See Also:

    • DeviceApi

      public DeviceApi(Config config)
      Constructs a DeviceApi instance with custom config.
      Parameters:
      config - An instance of Config, you can change the DeviceAtlas API config by creating an instance or Config and setting your custom config values and then passing the instance to the DeviceApi constructor.
      See Also:

  • Method Details

    • loadDataFromClassPath

      public void loadDataFromClassPath(String fileName) throws DataLoadingException
      Load the DeviceAtlas device detection data into the API from a JSON file form the class path. The JSON data file is provided by the DeviceAtlas website.
      Parameters:
      fileName - The JSON file-name
      Throws:
      DataLoadingException

    • loadDataFromFile

      public void loadDataFromFile(String jsonDataFilePath) throws DataLoadingException
      Load the DeviceAtlas device detection data into the API from a JSON file. The JSON data file is provided by the DeviceAtlas website.
      Parameters:
      jsonDataFilePath - Path to the JSON file
      Throws:
      DataLoadingException

    • loadDataFromStream

      public void loadDataFromStream(InputStream inputStream) throws DataLoadingException
      Load the DeviceAtlas device detection data into the API from an input stream. The stream is read to its end and closed. If loading fails, any previously loaded data remains in use.
      Parameters:
      inputStream - Input stream
      Throws:
      DataLoadingException - if the data cannot be read or is not valid

    • getPropertyNames

      public Set<PropertyName> getPropertyNames()
      Get a set of all possible property names. Note that the client side properties are not included in this set.
      Returns:
      A set of all possible device property names as PropertyName objects.

    • getApiVersion

      public static String getApiVersion()
      The version of this API.
      Returns:
      DeviceApi version

    • getDataVersion

      public String getDataVersion()
      The version of the data file.
      Returns:
      The device data file version.

    • getDataCreationTimestamp

      public Integer getDataCreationTimestamp()
      The creation date/time of the loaded data file as a Unix timestamp.
      Returns:
      The creation date/time of this data file as a Unix timestamp.

    • getDataCreationIso8601

      public String getDataCreationIso8601()
      The creation date/time of the loaded data file in ISO 8601 format.
      Returns:
      The creation date/time of the loaded data file in ISO 8601 format.

    • getProperties

      public Properties getProperties(String identifier)
      Get the properties for the provided identifier. The identifier may be a User-Agent string, Client Hints model or if enabled in the data file an app "Make Model" string.
      Parameters:
      identifier - The identifier string to identify
      Returns:
      A collection of properties (Property objects) wrapped in a Properties object

    • getProperties

      public Properties getProperties(String identifier, String clientSideString) throws ClientPropertiesException
      Get the properties for an identifier merged with the client side properties (provided by the DeviceAtlas Client-side component). The DeviceAtlas Client-side component (JavaScript library) collects the client-side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will override any properties discovered from the main JSON data file.
      Parameters:
      identifier - An identifier such as a User-Agent or Client Hints model.
      clientSideString - The contents of the cookie containing the client side properties
      Returns:
      A set of properties (Property objects) wrapped in a Properties object
      Throws:
      ClientPropertiesException

    • getProperties

      public Properties getProperties(Map<String,String> headers)
      Get the properties for a map of HTTP headers. The DeviceApi gets all the request HTTP headers and will precisely detect the device and find property values for all usable headers.
      Parameters:
      headers - Client's request HTTP headers
      Returns:
      A set of properties (Property objects) wrapped in a Properties object

    • getProperties

      public Properties getProperties(Map<String,String> headers, String clientSideString) throws ClientPropertiesException
      Get the properties for a set of HTTP headers merged with properties from the Client-side component. The DeviceApi gets all the request HTTP headers and will precisely detect the device and find property values for all usable headers. Get the properties for a User-Agent merged with the client side properties (provided by the DeviceAtlas Client-side component). The DeviceAtlas Client-side component (JavaScript library) collects the client side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will override any properties discovered from the main JSON data file.
      Parameters:
      headers - Client's request HTTP headers
      clientSideString - The contents of the cookie containing the client side properties
      Returns:
      A set of properties (Property objects) wrapped in a Properties object
      Throws:
      ClientPropertiesException

    • getDeviceAtlasApiVersion

      public String getDeviceAtlasApiVersion()