API Features

Single User-Agent Lookup (HTTP GET)

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 Request

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.

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)

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 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.

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.

Questions? Contact Sales .

Need help? Contact Support .