Single User-Agent Lookup (HTTP GET)
To look up a single User-Agent string, make an HTTP GET request to the /detect endpoint and append the ua parameter containing your User-Agent string (URL-encoded) as well as your API access key.
Example API request:
https://api.apilayer.net/userstack/detect?access_key=YOUR_ACCESS_KEY&ua=Mozilla/5.0%20(Macintosh;%20Intel%20Mac%20OS%20X%2010_14_0)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/71.0.3578.98%20Safari/537.36HTTP GET request parameters:
| Parameter | Description |
|---|---|
| access_key | [Required] Your API access key, available in your account dashboard. |
| ua | [Required] The User-Agent string to look up. |
| fields | [Optional] Return only selected response fields. See Options. |
| output | [Optional] Set to json (default) or xml to choose the output format. |
| legacy | [Optional] Set to 1 for the legacy UserAgent API response format. See Options. |
| callback | [Optional] JSONP callback function name. See Getting Started. |
Example API response:
Successful requests return a response in JSON or XML format. A response always contains the general fields ua, type, brand, name and url, as well as the os, device and browser modules. The crawler module is included on all plans, including Free.
{
"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
}
}API response objects: All objects returned by Userstack are explained in the Response Objects section below.
Bulk User-Agent Lookup (HTTP POST)
Multiple User-Agent strings can be processed at once by sending an HTTP POST request to the same /detect endpoint with one ua_batch[] body field for each User-Agent string. A single Bulk Lookup request accepts up to 100 User-Agent strings. You can also send the list as JSON ({"ua_batch": [...]}) with Content-Type: application/json.
The optional query parameters (fields, output, legacy, callback) can still be appended to the URL; they apply to every User-Agent in the batch.
Note: Bulk lookups are available on the Professional plan and higher. Each User-Agent in a successful bulk request counts as one request against your monthly quota (a batch of 3 counts as 3).
Example API request (form fields):
curl -X POST "https://api.apilayer.net/userstack/detect?access_key=YOUR_ACCESS_KEY" \
--data-urlencode "ua_batch[]=Mozilla/5.0 (Windows NT 5.1; rv:7.0.1) Gecko/20100101 Firefox/7.0.1" \
--data-urlencode "ua_batch[]=Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; FunWebProducts)" \
--data-urlencode "ua_batch[]=Mozilla/5.0 (iPad; CPU OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko)"Example API request (JSON body):
curl -X POST "https://api.apilayer.net/userstack/detect?access_key=YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"ua_batch": ["Mozilla/5.0 (Windows NT 5.1; rv:7.0.1) Gecko/20100101 Firefox/7.0.1", "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; FunWebProducts)", "Mozilla/5.0 (iPad; CPU OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko)"]}'HTTP POST request body:
| Object | Description |
|---|---|
| ua_batch[] | [Required] One entry for each User-Agent string to process (up to 100). |
HTTP GET request parameters:
| Parameter | Description |
|---|---|
| access_key | [Required] Your API access key, available in your account dashboard. |
| fields | [Optional] Return only selected response fields. |
| output | [Optional] Set to json (default) or xml to choose the output format. |
| legacy | [Optional] Set to 1 for the legacy response format. |
| callback | [Optional] JSONP callback function name. |
Example API response:
For 2 to 100 User-Agent strings, the API returns an array with one result per User-Agent string, in the same order as the request. Each result has the same structure as the Single Lookup response. A batch with one User-Agent string returns a single result object.
[
{
"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
}
}
]Bulk errors: More than 100 User-Agent strings returns 400 with code 302 (too_many_user_agents). Two or more User-Agent strings on a plan without bulk lookups returns 400 with code 303 (batch_not_supported_on_plan).
Response Objects
Based on your plan and the options you specify, the API can return the response objects below.
| Response object | Description |
|---|---|
| ua | Returns the requested User-Agent string. |
| type | Returns the entity type the User-Agent string is associated with (for example browser, mobile-browser, email-client, crawler). |
| brand | Returns the brand the detected device, browser or OS is associated with. |
| name | Returns the name the detected device, browser or OS is associated with. |
| url | Returns the URL the detected device, browser or OS is associated with. |
| os > name | Returns the name of the detected OS. |
| os > code | Returns the code name of the detected OS. |
| os > url | Returns the URL the detected OS is associated with. |
| os > family | Returns the product family the detected OS is associated with. |
| os > family_code | Returns the product family code the detected OS is associated with. |
| os > family_vendor | Returns the vendor the detected OS is associated with. |
| os > icon | Returns a URL leading to a 16x16 px icon of the detected OS. |
| os > icon_large | Returns a URL leading to a 128x128 px icon of the detected OS. |
| device > is_mobile_device | Returns true or false depending on whether a mobile device has been detected. |
| device > type | Returns the type of device detected (for example desktop, tablet, smartphone). |
| device > brand | Returns the brand of the detected device. |
| device > brand_code | Returns the brand code of the detected device. |
| device > brand_url | Returns the URL of the detected device brand. |
| device > name | Returns the name of the detected device. |
| browser > name | Returns the name of the detected browser. |
| browser > version | Returns the version of the detected browser. |
| browser > version_major | Returns the major version of the detected browser. |
| browser > engine | Returns the name of the engine the detected browser is running. |
| crawler > is_crawler | Returns true or false depending on whether a crawler has been detected. |
| crawler > category | Returns the detected crawler category. |
| crawler > last_seen | Returns when this crawler was last seen. |