<
for more information.
### Loading the data file ###
The DeviceAtlas API provides multiple methods to load the data file.
#### Loading an existing data file ####
The following example shows how to load a data file that is already on the filesystem.
```go
import (
"deviceatlas/device"
)
da := device.New()
// Load data from a file on the filesystem
_, err := da.LoadDataFromFile(<data file name>)
```
#### Downloading and loading the data file ####
The following example downloads the data file, saves it to the file system,
loads it into the DeviceAtlas API, and starts a background task to automatically
refresh the data file at a configured interval.
Please see the [Data File Configuration documentation](README.DataFile.html)
to obtain the data file download URL and for data file configuration options.
```go
import (
"context"
"log"
"deviceatlas/device"
"deviceatlas/datafile"
)
func main() {
da := device.New()
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// Your DeviceAtlas licence key
licenceKey := "<your-licence-key>"
// This URL downloads the WEB data file. For APP or combined data files,
// see all options at: https://deviceatlas.com/resources/getting-the-data/device-data
dataFileURL := "https://deviceatlas.com/getJSON?index=web&version=3&licencekey=" + licenceKey
// Download, load, and start background auto-refresh.
// MD5 file hash is automatically validated.
mgr, err := da.DownloadAndLoadDataFile(ctx, dataFileURL,
// datafile.WithDirectory("/var/cache/deviceatlas"), // persistent directory recommended, defaults to system temp
// datafile.WithRefreshInterval(24 * time.Hour), // optional, 24 hours is the default
// datafile.WithScheduleTime("14:00:00"), // optional, defaults to current time
)
if err != nil {
log.Fatal(err)
}
defer mgr.Close()
// API is ready to use
}
```
## 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.deviceatlas-cdn.com/dacs.js" async></script>
```
By default, the client-side library returns the data via a cookie. If this is
present in the `http.Request` object it will be automatically used. The
cookie name is configurable via the `DaConfig` struct.
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.
### Usage Examples ###
The following sections shows how to call the DeviceApi. Please note that
exception handling has been omitted for brevity.
#### Detection via HTTP Headers ####
Lookup the properties by passing HTTP headers to the API:
```go
da := device.New()
_, err := da.LoadDataFromFile(<data file name>)
// pass HTTP headers to the API
headers := map[string]string{
"user-agent": "Mozilla/5.0 (Linux; Android 11; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.141 Mobile Safari/537.36",
"sec-ch-ua": "\"Chromium\";v=\"87\", \"Google Chrome\";v=\"87\"",
"sec-ch-ua-mobile": "?1",
}
properties, err := da.Detect(headers)
// print all properties
for k, v := range properties {
fmt.Printf("%v: %v\n", k, v)
}
// use a property
if mobileDevice, ok := properties["mobileDevice"].(bool); ok && mobileDevice {
// do something for mobile devices
}
// get a string property with a default value
browserName := ""
if bn, ok := properties["browserName"].(string); ok {
browserName = bn
}
```
#### Detection via Make/Model ####
Lookup the properties by 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).
```go
da := device.New()
_, err := da.LoadDataFromFile(<data file name>)
// The Make/Model identifier may be looked up by directly passing the string
makeModel := "samsung sm-n9005"
properties, err := da.DetectV(makeModel)
// It is also possible to add the Make/Model identifier to a map for the lookup
identifiers := make(map[string]string)
identifiers["make-model"] = makeModel
properties, err = da.Detect(identifiers)
```
#### Passing Client Side Data ####
The data collected by the DeviceAtlas Client-side Library is automatically
passed when an `http.Request` is used with `DetectHttpRequest()`. If an `http.Request` object
is not available the client-side data can be passed manually using the
`DetectWithClientSide()` method.
```go
da := device.New()
_, err := da.LoadDataFromFile(<data file name>)
headers := map[string]string{
"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": "\"Chromium\";v=\"102\", \"Google Chrome\";v=\"102\"",
"sec-ch-ua-mobile": "?1",
}
clientSideData := "scsVersion:2.2|bcookieSupport:1|bcss.animations:1|bcss.columns:1|bcss.transforms:1|bcss.transitions:1|sdeviceAspectRatio:1795/1010"
properties, err := da.DetectWithClientSide(headers, clientSideData)
// use the properties
```
#### Detection via HTTP Request ####
When using the Device API in a web application, you can pass the
`*http.Request` object directly. This automatically extracts all HTTP headers
and any client-side data from cookies.
```go
import (
"net/http"
"deviceatlas/device"
)
var da *device.DaGo
func init() {
da = device.New()
_, err := da.LoadDataFromFile(<data file name>)
if err != nil {
panic(err)
}
}
func handler(w http.ResponseWriter, r *http.Request) {
properties, err := da.DetectHttpRequest(r)
if err != nil {
// handle error
return
}
// use a property
if mobileDevice, ok := properties["mobileDevice"].(bool); ok && mobileDevice {
// serve mobile content
}
}
```
### Error Handling ###
All API methods return `DaError` which supports `errors.Is()`, `errors.As()`,
and `errors.Unwrap()` for idiomatic Go error handling. Use `errors.Is(err, device.ErrDataNotLoaded)`
to check for specific conditions. See the package exports for available sentinel errors.
#### Additional Examples ####
Please find more complete examples in the /Examples directory.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas 2026. 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><a href="README.Installation.html">Enterprise API Installation</a></li><li><a href="README.DataFile.html">Data File Configuration</a></li><li class="disabled"><a href="README.DeviceApi.html">Device API Usage</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li class="divider"></li><li><a href="./ApiDocs/device.html">Device API Docs</a></li><li><a href="./ApiDocs/carrier.html">Carrier API Docs</a></li><li><a href="./ApiDocs/datafile.html">Datafile Docs</a></li></ul></div>]]>