DeviceAtlas Cloud Client Implementation Guide

Instructions for usage via direct HTTP call.

When to use this approach

Client APIs are provided in PHP, Python, Java, .NET. They handle all common use cases and include a configurable cache to ensure optimal performance. If a different language is required, making a direct call to the service may be appropriate.

Considerations when making a direct call to DeviceAtlas Cloud

The following points should be considered when making requests to DeviceAtlas Cloud.

Query results are not automatically cached, which means that the usage quota is reached more quickly, and latency is incurred on each call;
There is no auto-selection of the fastest endpoint;
The region can be changed to suit geographic location, to minimise latency. The full list of available regions is found on this page: https://deviceatlas.com/resources/cloud-service-end-points
There is no failover in the unlikely event of a region becoming slow or unresponsive;

Note that all of these considerations are incorporated into the official DeviceAtlas Cloud APIs, the recommended approach for utilising DeviceAtlas Cloud.

User-Agent Client Hints

A significant percentage of web traffic now sends a reduced User-Agent header in conjunction with User-Agent Client Hint headers; a User-Agent header alone is no longer sufficient to resolve devices and their properties. Thus a full set of HTTP headers is required to be sent to DeviceAtlas Cloud to accurately identify devices and their properties. You can read more about User-Agent Client hints in our Resources section.

REST API

The DeviceAtlas Cloud service can be queried using a URL in the following form:

https://region0.deviceatlascloud.com/v1/detect/properties?licencekey=<licence_key>

Replace <licence_key> with your actual licence key (https://deviceatlas.com/signup-cloud)

The full set of HTTP headers from the device must be sent with the request, prefixed with x-da- to differentiate them from other headers sent as part of the request. With the advent of User-Agent Client Hints, the User-Agent header alone is no longer sufficient to identify the majority of web traffic, so all headers from a device should be included with the request.

A list of REST endpoints and their geographical affinities can be seen here: https://deviceatlas.com/resources/cloud-service-end-points

Example cURL requests

Simple User-Agent example

curl --location 'https://region0.deviceatlascloud.com:443/v1/detect/properties?licencekey=your_licence_key' \
--header 'X-DA-User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36'

Full header set example

curl --location 'https://region0.deviceatlascloud.com:443/v1/detect/properties?licencekey=your_licence_key' \
--header 'X-DA-Accept-Language: en-US,en;q=0.9' \
--header 'X-DA-Accept-Encoding: gzip, deflate, br' \
--header 'X-DA-Sec-Fetch-Dest: document' \
--header 'X-DA-Sec-Fetch-User: ?1' \
--header 'X-DA-Sec-Fetch-Mode: navigate' \
--header 'X-DA-Sec-Fetch-Site: same-origin' \
--header 'X-DA-Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7' \
--header 'X-DA-User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36' \
--header 'X-DA-Dnt: 1' \
--header 'X-DA-Sec-Ch-Prefers-Reduced-Motion: no-preference' \
--header 'X-DA-Sec-Ch-Prefers-Color-Scheme: dark' \
--header 'X-DA-Sec-Ch-Ua-Full-Version-List: "Chromium";v="116.0.5845.140", "Not)A;Brand";v="24.0.0.0", "Google Chrome";v="116.0.5845.140"' \
--header 'X-DA-Sec-Ch-Ua-Bitness: "64"' \
--header 'X-DA-Sec-Ch-Ua-Model: ""' \
--header 'X-DA-Sec-Ch-Ua-Platform-Version: "13.5.1"' \
--header 'X-DA-Sec-Ch-Ua-Platform: "macOS"' \
--header 'X-DA-Sec-Ch-Ua-Arch: "arm"' \
--header 'X-DA-Sec-Ch-Ua-Full-Version: "116.0.5845.140"' \
--header 'X-DA-Sec-Ch-Ua-Mobile: ?0' \
--header 'X-DA-Sec-Ch-Ua: "Chromium";v="116", "Not)A;Brand";v="24", "Google Chrome";v="116"' \
--header 'X-DA-Ect: 4g' \
--header 'X-DA-Downlink: 8.9' \
--header 'X-DA-Rtt: 50' \
--header 'X-DA-Viewport-Width: 1508' \
--header 'X-DA-Dpr: 1' \
--header 'X-DA-Device-Memory: 8' \
--header 'X-DA-Client-Properties: bS:0|scsVersion:2.4.1|sconnectionType:unknown|bcookieSupport:1|bcss.animations:1|bcss.columns:1|bcss.transforms:1|bcss.transitions:1|sdeviceAspectRatio:16/9|sdevicePixelRatio:1|idisplayColorDepth:24|sdownlink:8.2|seffectiveConnectionType:4g|bflashCapable:0|bhtml.audio.ogg:1|bhtml.audio.mp3:1|bhtml.audio.wav:1|bhtml.audio.m4a:1|bhtml.canvas:1|bhtml.inlinesvg:1|bhtml.svg:1|bhtml.video.ap4x:0|bhtml.video.ogg:1|bhtml.video.h264:1|bhtml.video.webm:1|bjs.accessDom:1|bjs.applicationCache:0|bjs.deviceMotion:1|bjs.geoLocation:1|bjs.indexedDB:1|bjs.json:1|bjs.localStorage:1|bjs.modifyCss:1|bjs.modifyDom:1|bjs.querySelector:1|bjs.sessionStorage:1|bjs.supportBasicJavaScript:1|bjs.supportConsoleLog:1|bjs.supportEventListener:1|bjs.supportEvents:1|bjs.webGl:1|sjs.webGlRenderer:ANGLE (Apple, Apple M1, OpenGL 4.1)|bjs.webSockets:1|bjs.webSqlDatabase:1|bjs.webWorkers:1|bjs.xhr:1|srendererRef:0554757778|iroundTripTime:100|bsaveData:0|sscreenWidthHeight:1920/1080|stimeZone:Europe/Dublin|buserMedia:1|s64BitArchitecture:true|sch.bitness:64|sch.browserFullVersionList:%22Chromium%22%3Bv%3D%22116.0.5845.140%22%2C%20%22Not)A%3BBrand%22%3Bv%3D%2224.0.0.0%22%2C%20%22Google%20Chrome%22%3Bv%3D%22116.0.5845.140%22|sch.browserList:%22Chromium%22%3Bv%3D%22116%22%2C%20%22Not)A%3BBrand%22%3Bv%3D%2224%22%2C%20%22Google%20Chrome%22%3Bv%3D%22116%22|sch.model:|sch.platform:%22macOS%22|sch.platformVersion:%2213.5.1%22|splatformArchitecture:arm|srequestingMobileUx:false|saudioRef:707339779|bmouseActivity:1|bE:0'

Client-side Component

The DeviceAtlas Client-side Component is a JavaScript library that adds additional granularity in identifying devices and also awareness of device capabilities that can change according to the context and preferences of a user. For example, the Client-Side Component can be used to indentify different iPhone models, something that is not possible with HTTP headers alone. The Client-Side Component can also include properties sent as Client Hints by a device.

To support Client-side Component it is required to send the DAPROPS cookie value using x-da-client-properties HTTP header as below.

x-da-client-properties: <DAPROPS>

Example

x-da-client-properties: sdeviceAspectRatio:40/71|sdevicePixelRatio...

Caching

A caching strategy should be implemented to improve latency and keep usage of the DeviceAtlas Cloud API to a minimum and avoid using up quota. The particular implementation details for this will depend on the nature of the environment but a strategy should be employed that that caches results based on all of the headers sent by the originating device. The most important headers to consider for cache keys are the User-Agent header and all of the Sec-Ch-Ua-* headers.

DeviceAtlas Cloud Client Implementation Guide