API Documentation

userstack offers a real-time, easy-to-use REST API interface capable of parsing User-Agent strings to accurately detect device, browser and operating system information. Implementing the JSON/XML API in your frontend or backend system will give you all the tools you need to take control of your website's or application's user experience and the customer journey that goes with it.

This API documentation will outline in detail the API's specification, access and features. At the very bottom you will find code examples in different programming languages. In case any technical questions are left unanswered, please feel free to contact userstack Customer Service for assistance.

Specs & Overview

API Access Key & Authentication

After signing up for an account, you will be able redirected to the account dashboard to find your API access key, a uniquely generated hash consisting of 32 characters that can be used to access the userstack API.

To authenticate with the API, simply append your API access key to the API's base URL using the access_key parameter.

Sign Up to Run API Requesthttps://api.userstack.com/api/detect
    ? access_key = YOUR_ACCESS_KEY

Protect your API access key: To prevent unauthorized use of your account or API access, please make sure to keep your API access key private and safe from third parties. Your access key can be reset with immediate effect in your account dashboard.

API Response

If your API request is successful, the userstack API will return a series of response objects associated with the requested User-Agent string. The API's response can be delivered in JSON or XML format and is separated into the modules "os" (Operating System), "device", "browser" and "crawler". Above these modules the API will also return the requested User-Agent string and four of the most basic data points.

Find below an example API response for a User-Agent string associated with an Apple iMac running the operating system macOS "Mojave" Version 10.14.

Example API Response:

{
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
    "type": "browser",
    "brand": "Apple",
    "name": "Mac",
    "url": "https://www.google.com/about/company/",
    "os": {
        "name": "macOS 10.14 Mojave",
        "code": "macos_10_14",
        "url": "https://en.wikipedia.org/wiki/MacOS_Mojave",
        "family": "macOS",
        "family_code": "macos",
        "family_vendor": "Apple Inc.",
        "icon": "https://assets.userstack.com/icons/os/macosx.png",
        "icon_large": "https://assets.userstack.com/icons/os/macosx_big.png"
    },
    "device": {
        "is_mobile_device": false,
        "type": "desktop",
        "brand": "Apple",
        "brand_code": "apple",
        "brand_url": "http://www.apple.com/",
        "name": "Mac"
    },
    "browser": {
        "name": "Chrome",
        "version": "71.0.3578.98",
        "version_major": "71",
        "engine": "WebKit/Blink"
    },
    "crawler": {
        "is_crawler": false,
        "category": null,
        "last_seen": null
    }
}
<result>
    <ua>
    Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
    </ua>
    <type>browser</type>
    <brand>Apple</brand>
    <name>Mac</name>
    <url>https://www.google.com/about/company/</url>
    <os>
        <name>macOS 10.14 Mojave</name>
        <code>macos_10_14</code>
        <url>https://en.wikipedia.org/wiki/MacOS_Mojave</url>
        <family>macOS</family>
        <family_code>macos</family_code>
        <family_vendor>Apple Inc.</family_vendor>
        <icon>https://assets.userstack.com/icons/os/macosx.png</icon>
        <icon_large>
        https://assets.userstack.com/icons/os/macosx_big.png
        </icon_large>
    </os>
    <device>
        <is_mobile_device/>
        <type>desktop</type>
        <brand>Apple</brand>
        <brand_code>apple</brand_code>
        <brand_url>http://www.apple.com/</brand_url>
        <name>Mac</name>
    </device>
    <browser>
        <name>Chrome</name>
        <version>71.0.3578.98</version>
        <version_major>71</version_major>
        <engine>WebKit/Blink</engine>
    </browser>
    <crawler>
        <is_crawler/>
        <category/>
        <last_seen/>
    </crawler>
</result>
JSONXML

Please note: To be able to completely illustrate a successful API request, Crawler data has been included in the API response above. To enable the Crawler module, you must be subscribed to the Basic Plan or higher.

API Endpoints

The API comes with a total of 2 core functionalities: Looking up single User-Agent strings, and looking up User-Agent strings in bulk.

Single Lookup
Look up any given User-Agent string.
Bulk Lookup (HTTP POST only)
Look up multiple User-Agent strings in bulk.

256-bit HTTPS Encryption Available on: Basic Plan and higher

Customers subscribed to the Basic Plan and higher can connect to the API using industry standard HTTPS (SSL) by appending an s to the HTTP Protocol. Please find an example API request using HTTPS below.

Example API Request:

https://api.userstack.com/api/detect

JSONP Callbacks

The API supports JSONP Callbacks. To make use of this feature, simply append the API's callback parameter to your API request URL and set it to your preferred function name. The API will then return your API results set wrapped inside the tags of the function you specified.

Example API Request:

Sign Up to Run API Requesthttps://api.userstack.com/api/detect
    ? access_key = YOUR_ACCESS_KEY
    & ua = Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
    & callback = FUNCTION_NAME

Example API Response:

CALLBACK_FUNCTION ({
    {
        "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
        "type": "browser",
        "brand": "Apple",
        "name": "Mac",
        "url": "https://www.google.com/about/company/",
        [...]
    }
})JSON ONLY

Please note: The API also supports Access-Control (CORS) headers.

API Error Codes

If an API request fails, a JSON object containing details about the error will be returned by the API. Find below an example error that is returned if the maximum allowed API request limit has been reached or exceeded.

Example Error:

{
    "success": false,
    "error": {
        "code": 104,
        "type": "usage_limit_reached",
        "info": "Your monthly API request volume has been reached. Please upgrade your plan."    
    }
}JSON ONLY

Common API Errors:

Code	Type	Info
`404`	`404_not_found`	User requested a resource which does not exist.
`101`	`missing_access_key`	User did not supply an access key.
`101`	`invalid_access_key`	User supplied an invalid access key.
`102`	`inactive_user`	User account is inactive or blocked.
`103`	`invalid_api_function`	User requested a non-existent API function.
`104`	`usage_limit_reached`	User has reached his subscription's monthly request allowance.
`105`	`function_access_restricted`	The user's current subscription does not support this API function.
`105`	`https_access_restricted`	The user's current subscription plan does not support HTTPS.
`301`	`missing_user_agent`	No User-Agent string has been specified.
`302`	`invalid_fields`	One or more invalid output fields have been specified.
`303`	`too_many_user_agents`	Too many User-Agent strings have been specified in a single Bulk request.
`304`	`batch_not_supported_on_plan`	Requests to the Bulk endpoint are not supported at this subscription level.

API Features

Single User-Agent Lookup (HTTP GET) Available on: All plans

To look up a single User-Agent string, simply make an HTTP GET request to the API's base URL and append the ua parameter containing your User-Agent string as well as your API access key. Find below an example API request.

Example API Request:

Sign Up to Run API Requesthttps://api.userstack.com/detect
    ? access_key = YOUR_ACCESS_KEY
    & ua = Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36

HTTP GET Request Parameters:

Object	Description
`access_key`	[Required] Your API access key, available in your account dashboard.
`ua`	[Required] Specify the User-Agent string to be looked up.
`fields`	[optional] Specify API response field(s) according to the Specify Response Fields section.
`callback`	[optional] Specify a JSONP callback function name according to the JSONP Callbacks section.
`output`	[optional] Set to `json` or `xml` to choose between output formats.

Example API Response:

Successful API requests will cause the userstack API to return an extensive API response in JSON or XML format, structured into three or four different models, depending on your subscription. An API response always contains the basic data points of "ua", "type", "brand", "name" and "url", as well as the extensive modules "os", "device" and "browser".

The fourth module "crawler" will be included in your API result if you are subscribed to the Basic Plan or higher.

{
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
    "type": "browser",
    "brand": "Apple",
    "name": "Mac",
    "url": "https://www.google.com/about/company/",
    "os": {
        "name": "macOS 10.14 Mojave",
        "code": "macos_10_14",
        "url": "https://en.wikipedia.org/wiki/MacOS_Mojave",
        "family": "macOS",
        "family_code": "macos",
        "family_vendor": "Apple Inc.",
        "icon": "https://assets.userstack.com/icons/os/macosx.png",
        "icon_large": "https://assets.userstack.com/icons/os/macosx_big.png"
    },
    "device": {
        "is_mobile_device": false,
        "type": "desktop",
        "brand": "Apple",
        "brand_code": "apple",
        "brand_url": "http://www.apple.com/",
        "name": "Mac"
    },
    "browser": {
        "name": "Chrome",
        "version": "71.0.3578.98",
        "version_major": "71",
        "engine": "WebKit/Blink"
    },
    "crawler": {
        "is_crawler": false,
        "category": null,
        "last_seen": null
    }
}
<result>
    <ua>
    Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
    </ua>
    <type>browser</type>
    <brand>Apple</brand>
    <name>Mac</name>
    <url>https://www.google.com/about/company/</url>
    <os>
        <name>macOS 10.14 Mojave</name>
        <code>macos_10_14</code>
        <url>https://en.wikipedia.org/wiki/MacOS_Mojave</url>
        <family>macOS</family>
        <family_code>macos</family_code>
        <family_vendor>Apple Inc.</family_vendor>
        <icon>https://assets.userstack.com/icons/os/macosx.png</icon>
        <icon_large>
        https://assets.userstack.com/icons/os/macosx_big.png
        </icon_large>
    </os>
    <device>
        <is_mobile_device/>
        <type>desktop</type>
        <brand>Apple</brand>
        <brand_code>apple</brand_code>
        <brand_url>http://www.apple.com/</brand_url>
        <name>Mac</name>
    </device>
    <browser>
        <name>Chrome</name>
        <version>71.0.3578.98</version>
        <version_major>71</version_major>
        <engine>WebKit/Blink</engine>
    </browser>
    <crawler>
        <is_crawler/>
        <category/>
        <last_seen/>
    </crawler>
</result>
JSONXML

API Response Objects: Looking for details about the API's response objects? All objects returned by userstack are explained in detail in the API Response Objects section of this documentation.

Bulk User-Agent Lookup (HTTP POST) Available on: Business Plan and higher

Multiple User-Agent strings can be processed at once by sending an HTTP POST request to the API's base URL containing one ua_batch[] object for each User-Agent string to process. A single Bulk Lookup request can accept up to 100 User-Agent strings.

Here's an example illustrating how to use HTTP POST to process 3 different User-Agent strings at once. The Bulk Lookup feature still makes use of the same base URL that is used in the Single Lookup feature. It is also still possible to append optional HTTP GET parameters (e.g. the API's fields parameter) to that URL to customize your API response.

POST request illustration:

// HTTP POST request to the API's base URL
Sign Up to Run API Requesthttps://api.userstack.com/detect
    ? access_key = YOUR_ACCESS_KEY

// 3 User-Agent strings to process
ua_batch[] = Mozilla/5.0 (Windows NT 5.1; rv:7.0.1) Gecko/20100101 Firefox/7.0.1
ua_batch[] = Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; FunWebProducts)
ua_batch[] = Mozilla/5.0 (iPad; CPU OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko)

HTTP POST Request Objects:

Object	Description
`ua_batch[]`	[Required] Specify one object for each User-Agent string to process.

HTTP GET Request Parameters:

Object	Description
`access_key`	[Required] Your API access key, available in your account dashboard.
`fields`	[optional] Specify API response field(s) according to the Specify Response Fields section.
`callback`	[optional] Specify a JSONP callback function name according to the JSONP Callbacks section.
`output`	[optional] Set to `json` or `xml` to choose between output formats.

Example API Response:

The API will now return a large array containing one sub-array for each requested User-Agent string. These sub-arrays are identical in structure to the Single Lookup API response. In our example, the API returns the three sub-arrays below.

[
    {
        "ua": "Mozilla/5.0 (Windows NT 5.1; rv:7.0.1) Gecko/20100101 Firefox/7.0.1",
        "type": "browser",
        "brand": null,
        "name": null,
        "url": "https://www.mozilla.org/",
        "os": {
            "name": "Windows XP",
            "code": "windows_xp",
            "url": "https://en.wikipedia.org/wiki/Windows_XP",
            "family": "Windows",
            "family_code": "windows",
            "family_vendor": "Microsoft Corporation.",
            "icon": "https://assets.userstack.com/icons/os/windowsxp.png",
            "icon_large": "https://assets.userstack.com/icons/os/windowsxp_big.png"
        },
        "device": {
            "is_mobile_device": false,
            "type": "desktop",
            "brand": null,
            "brand_code": null,
            "brand_url": null,
            "name": null
        },
        "browser": {
            "name": "Firefox",
            "version": "7.0.1",
            "version_major": "7",
            "engine": "Gecko"
        },
        "crawler": {
            "is_crawler": false,
            "category": null,
            "last_seen": null
        }
    },
    {
        "ua": "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; FunWebProducts)",
        "type": "browser",
        "brand": null,
        "name": null,
        "url": "https://www.microsoft.com/about/",
        "os": {
            "name": "Windows 2000",
            "code": "windows_2000",
            "url": "https://en.wikipedia.org/wiki/Windows_2000",
            "family": "Windows",
            "family_code": "windows",
            "family_vendor": "Microsoft Corporation.",
            "icon": "https://assets.userstack.com/icons/os/windows.png",
            "icon_large": "https://assets.userstack.com/icons/os/windows_big.png"
        },
        "device": {
            "is_mobile_device": false,
            "type": "desktop",
            "brand": null,
            "brand_code": null,
            "brand_url": null,
            "name": null
        },
        "browser": {
            "name": "IE",
            "version": "6.0",
            "version_major": "6",
            "engine": "Trident"
        },
        "crawler": {
            "is_crawler": false,
            "category": null,
            "last_seen": null
        }
    },
    {
        "ua": "Mozilla/5.0 (iPad; CPU OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko)",
        "type": "email-client",
        "brand": "Apple",
        "name": "iPad",
        "url": "http://www.apple.com/",
        "os": {
            "name": "iOS 8",
            "code": "ios_8",
            "url": "https://en.wikipedia.org/wiki/IOS_8",
            "family": "iOS",
            "family_code": "ios",
            "family_vendor": "Apple Inc.",
            "icon": "https://assets.userstack.com/icons/os/iphone.png",
            "icon_large": "https://assets.userstack.com/icons/os/iphone_big.png"
        },
        "device": {
            "is_mobile_device": true,
            "type": "tablet",
            "brand": "Apple",
            "brand_code": "apple",
            "brand_url": "http://www.apple.com/",
            "name": "iPad"
        },
        "browser": {
            "name": "Apple Mail",
            "version": null,
            "version_major": null,
            "engine": "WebKit"
        },
        "crawler": {
            "is_crawler": false,
            "category": null,
            "last_seen": null
        }
    }
]
<batch>
    <result index="0">
        <ua>Mozilla/5.0 (Windows NT 5.1; rv:7.0.1) Gecko/20100101 Firefox/7.0.1</ua>
        <type>browser</type>
        <brand></brand>
        <name></name>
        <url>https://www.mozilla.org/</url>
        <os>
            <name>Windows XP</name>
            <code>windows_xp</code>
            <url>https://en.wikipedia.org/wiki/Windows_XP</url>
            <family>Windows</family>
            <family_code>windows</family_code>
            <family_vendor>Microsoft Corporation.</family_vendor>
            <icon>https://assets.userstack.com/icons/os/windowsxp.png</icon>
            <icon_large>https://assets.userstack.com/icons/os/windowsxp_big.png</icon_large>
        </os>
        <device>
            <is_mobile_device></is_mobile_device>
            <type>desktop</type>
            <brand></brand>
            <brand_code></brand_code>
            <brand_url></brand_url>
            <name></name>
        </device>
        <browser>
            <name>Firefox</name>
            <version>7.0.1</version>
            <version_major>7</version_major>
            <engine>Gecko</engine>
        </browser>
        <crawler>
            <is_crawler></is_crawler>
            <category></category>
            <last_seen></last_seen>
        </crawler>
    </result>
    <result index="1">
        <ua>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; FunWebProducts)</ua>
        <type>browser</type>
        <brand></brand>
        <name></name>
        <url>https://www.microsoft.com/about/</url>
        <os>
            <name>Windows 2000</name>
            <code>windows_2000</code>
            <url>https://en.wikipedia.org/wiki/Windows_2000</url>
            <family>Windows</family>
            <family_code>windows</family_code>
            <family_vendor>Microsoft Corporation.</family_vendor>
            <icon>https://assets.userstack.com/icons/os/windows.png</icon>
            <icon_large>https://assets.userstack.com/icons/os/windows_big.png</icon_large>
        </os>
        <device>
            <is_mobile_device></is_mobile_device>
            <type>desktop</type>
            <brand></brand>
            <brand_code></brand_code>
            <brand_url></brand_url>
            <name></name>
        </device>
        <browser>
            <name>IE</name>
            <version>6.0</version>
            <version_major>6</version_major>
            <engine>Trident</engine>
        </browser>
        <crawler>
            <is_crawler></is_crawler>
            <category></category>
            <last_seen></last_seen>
        </crawler>
    </result>
    <result index="2">
        <ua>Mozilla/5.0 (iPad; CPU OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko)</ua>
        <type>email-client</type>
        <brand>Apple</brand>
        <name>iPad</name>
        <url>http://www.apple.com/</url>
        <os>
            <name>iOS 8</name>
            <code>ios_8</code>
            <url>https://en.wikipedia.org/wiki/IOS_8</url>
            <family>iOS</family>
            <family_code>ios</family_code>
            <family_vendor>Apple Inc.</family_vendor>
            <icon>https://assets.userstack.com/icons/os/iphone.png</icon>
            <icon_large>https://assets.userstack.com/icons/os/iphone_big.png</icon_large>
        </os>
        <device>
            <is_mobile_device>1</is_mobile_device>
            <type>tablet</type>
            <brand>Apple</brand>
            <brand_code>apple</brand_code>
            <brand_url>http://www.apple.com/</brand_url>
            <name>iPad</name>
        </device>
        <browser>
            <name>Apple Mail</name>
            <version></version>
            <version_major></version_major>
            <engine>WebKit</engine>
        </browser>
        <crawler>
            <is_crawler></is_crawler>
            <category></category>
            <last_seen></last_seen>
        </crawler>
    </result>
</batch>
JSONXML

The next section will explain in detail all API response objects.

Response Objects

Based on which plan you are subscribed to and the options you specify for your API request, there are over 40 unique response objects the API is capable of responding with. Find below a complete list of API response objects:

Response Object	Description
`ua`	Returns requested User-Agent string.
`type`	Returns entity type the requested User-Agent string is associated with. View all entity types
`brand`	Returns the brand the resulting device, browser or OS is associated with.
`name`	Returns the name the resulting device, browser or OS is associated with.
`url`	Returns the URL the resulting device, browser or OS is associated with.
`os` > `name`	Returns the name of the resulting OS.
`os` > `code`	Returns the code name of the resulting OS.
`os` > `url`	Returns the URL the resulting OS is associated with.
`os` > `family`	Returns the product family the resulting OS is associated with.
`os` > `family_code`	Returns the product family code the resulting OS is associated with.
`os` > `family_vendor`	Returns the vendor the resulting OS is associated with.
`os` > `icon`	Returns a URL leading to a 16x16px icon associated with the resulting OS.
`os` > `icon`	Returns a URL leading to a 128x128px icon associated with the resulting OS.
`device` > `is_mobile_device`	Returns `true` or `false` depending on whether or not a mobile device has been detected.
`device` > `type`	Returns the type of device that has been detected. View all device types
`browser` > `name`	Returns the name of the resulting browser.
`browser` > `version`	Returns the version of the resulting browser.
`browser` > `version_major`	Returns the major version of the resulting browser.
`browser` > `engine`	Returns the name of the engine the resulting browser is running.
`crawler` > `is_crawler`	Returns `true` or `false` depending on whether or not a crawler has been detected.
`crawler` > `category`	Returns the detected crawler category. View all crawler categories
`crawler` > `last_seen`	Returns information about when this particular crawler was last seen.

Options

Specify Response Format Available on: All plans

The userstack API can deliver API results either in JSON (default) or XML format. To change the response format, simply append the API's output parameter to your API request URL and set it to json or xml.

Example API Request - JSON:

Sign Up to Run API Requesthttps://api.userstack.com/detect
    ? access_key = YOUR_ACCESS_KEY
    & ua = Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
    & output = json

Example API Request - XML:

Sign Up to Run API Requesthttps://api.userstack.com/detect
    ? access_key = YOUR_ACCESS_KEY
    & ua = Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
    & output = xml

API Response: Interested in seeing the API response? Jump to the API Response section.

Specify Response Fields Available on: All plans

Since the file size of API responses can be extensive in size, especially when making Bulk Lookup requests, the userstack API features a fields parameter that can be used to request only certain parts of the API response to be included in the final result.

Using this parameter is simple. Please find some examples below.

Examples:

fields = main // returns general API fields only, from "ua" to "url"
  
fields = brand // returns only the "brand" object

fields = os // returns the complete "os" object with sub-objects
fields = device.icon // returns only the "icon" object inside "device"
  
fields = os.name,device.name // returns both the "type" and "device" > "name" objects

Example API Request:

Sign Up to Run API Requesthttps://api.userstack.com/detect
    ? access_key = YOUR_ACCESS_KEY
    & fields = type,device.name

Example API Response:

{
    "type": "browser",
    "device": {
        "name": "Mac"
    }
}
<result>
    <type>browser</type>
    <device>
        <name>Mac</name>
    </device>
</result>
JSONXML

As you can see above, the API now returns only the fields specified in the API request, dramatically reducing the file size of the API response and speed of your application using userstack.

Enable Legacy Format Available on: All plans

For customers transitioning from former UserAgent API, userstack is capable of delivering API results in a legacy format identical to the former response structure. To enable legacy format, simply append the API's legacy parameter to your API request URL and set it to 1.

Example API Request:

Sign Up to Run API Requesthttps://api.userstack.com/detect
    ? access_key = YOUR_ACCESS_KEY
    & ua = Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
    & legacy = 1

Example API Response:

{
    "data": {
        "ua_type": "Desktop",
        "os_name": "macOS 10.14 Mojave",
        "os_version": "",
        "browser_name": "Chrome",
        "browser_version": "71.0.3578.98",
        "engine_name": "WebKit/Blink",
        "engine_version": ""
    }
}
<result>
    <data>
        <ua_type>Desktop</ua_type>
        <os_name>macOS 10.14 Mojave</os_name>
        <os_version/>
        <browser_name>Chrome</browser_name>
        <browser_version>71.0.3578.98</browser_version>
        <engine_name>WebKit/Blink</engine_name>
        <engine_version/>
    </data>
</result>
JSONXML

Code Examples

Below you will find code examples in various programming languages that can be used to make an API request to look up an individual User-Agent string. Programming language examples currently include PHP, Python, Nodejs, jQuery, Go and Ruby.

Code Example - PHP

$query = http_build_query([
  'access_key' => 'YOUR_ACCESS_KEY',
  'ua' => 'Mozilla/5.0 (iPad; CPU OS 9_3_2 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13F69 Safari/601.1',
]);

$ch = curl_init('https://api.userstack.com/detect?' . $query);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$json = curl_exec($ch);
curl_close($ch);

$api_result = json_decode($json, true);

if ($api_result['device']['type'] === 'tablet') {
  echo "It's a tablet";
}

Code Example - Python

import requests

params = {
  'access_key': 'YOUR_ACCESS_KEY',
  'ua': 'Mozilla/5.0 (iPad; CPU OS 9_3_2 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13F69 Safari/601.1'
}

api_result = requests.get('http://api.userstack.com/detect', params)

if api_result.json()['device']['type'] == 'tablet':
  print "It's a tablet";

Code Example - Nodejs

const http = require('http');
const querystring = require('querystring');

let query = {
  access_key: 'YOUR_ACCESS_KEY',
  ua: 'Mozilla/5.0 (iPad; CPU OS 9_3_2 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13F69 Safari/601.1'
};

http.get(`http://api.userstack.com/detect?${querystring.stringify(query)}`, response => {
  let data = '';

  response.on('data', chunk => data += chunk);

  response.on('end', () => {
    let api_response = JSON.parse(data);

    if(api_response.device && api_response.device.type === 'tablet') {
      console.log('It\'s a tablet.');
    }
  });
});

Code Example - jQuery

$.ajax({
  url: 'https://api.userstack.com/detect',
  data: {
    access_key: 'YOUR_ACCESS_KEY',
    ua: 'Mozilla/5.0 (iPad; CPU OS 9_3_2 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13F69 Safari/601.1'
  },
  dataType: 'jsonp',
  success: function(json) {
    if (json.device && json.device.type == 'tablet') {
      console.log("It's a tablet.");
    }
  }
});

Code Example - Go

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
)

type Device struct {
  Type string
}

type Response struct {
  Success bool
  Device Device
}

func main() {
  httpClient := http.Client{}

  req, err := http.NewRequest("GET", "http://api.userstack.com/detect", nil)
  if err != nil {
    panic(err)
  }

  q := req.URL.Query()
  q.Add("access_key", "YOUR_ACCESS_KEY")
  q.Add("ua", "Mozilla/5.0 (iPad; CPU OS 9_3_2 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13F69 Safari/601.1")
  req.URL.RawQuery = q.Encode()

  res, err := httpClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  response := Response{}
  json.NewDecoder(res.Body).Decode(&response)

  if(response.Device.Type == "tablet") {
    fmt.Printf("It's a tablet.")
  }
}

Code Example - Ruby

require 'net/http'
require 'json'

params = {
  :access_key => "YOUR_ACCESS_KEY",
  :ua => "Mozilla/5.0 (iPad; CPU OS 9_3_2 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13F69 Safari/601.1"
}
uri = URI('http://api.userstack.com/detect')
uri.query = URI.encode_www_form(params)
response = Net::HTTP.get(uri)
json = JSON.parse(response)
if json['device']['type'] == 'tablet'
  print("It's a tablet.")
end

Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Plan Name	Monthly Price	Number of Calls	Overage Price per call	Overage	Total price
Basic	$9.99	50,000	0.0002997	10,000	$12.99
Business	$49.99	500,000	0.00014997	100,000	$64.99
Business Pro	$99.99	2,000,000	0.0000749925	400,000	$129.99

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.

Introducing Platinum Support - Enterprise-grade support for APILayer

Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.

What does Platinum Support include?

	Standard Support	Platinum Support
General review on the issue
Access to knowledge base articles
Email support communication
Regular products updates and fixes
Dedicated account team
Priority Email Support with unlimited communication
Priority bug and review updates
Option for quarterly briefing call with product Management
Features requests as priority roadmap input into product

Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.

Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.

Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.

Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.

Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.

Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.

Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!

Upgrade now

3-Step Quickstart Guide

Code Examples