User Agent Parser API provides the accurate browser, device, and operating system details from a User Agent String. It also provides information about crawlers and attack sources. You can use this detail to customize user experience, prevent crawlers and attackers from accessing your website.
We provide three endpoints in our User-Agent API to parse user-agent string into browser, device and operating system details.
Single User Agent String API can be used in two ways to lookup the browser, device and operating system details with JSON or XML response. The URL for this endpoint is https://api.ipgeolocation.io/user-agent and its full JSON response is below:
{
"userAgentString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9",
"name": "Safari",
"type": "Browser",
"version": "9.0.2",
"versionMajor": "9",
"device": {
"name": "Apple Macintosh",
"type": "Desktop",
"brand": "Apple",
"CPU": "Intel"
},
"engine": {
"name": "AppleWebKit",
"type": "Browser",
"version": "601.3.9",
"versionMajor": "601",
"build": "Unknown"
},
"operatingSystem": {
"name": "Mac OS X",
"type": "Desktop",
"version": "10.11.2",
"versionMajor": "10"
}
}
In order to get the User-Agent details about a user-agent string, pass it in the User-Agent header like below. Note that apiKey is also passed as a query parameter for authorization. This endpoint is meant to be called from the client-side. When executed in browser javascript, header is automatically appended and you just need to make a get call to the endpoint. To simulate this behavior of browser with curl, use this request.
# Get User-Agent Details for User-Agent header
$ curl --location --request GET 'https://api.ipgeolocation.io/user-agent?apiKey=API_KEY' \
--header 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9'
Note: When this endpoint is being called from client-side using Request Origin, apiKey parameter can be ommitted.
You can also provide custom User-Agent string to parse in JSON payload. This endpoint is meant to be called from server-side and is available for paid subscriptions only.
$ curl --location --request POST 'https://api.ipgeolocation.io/user-agent?apiKey=API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{ "uaString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9" }'
This endpoint allows you to perform the parsing of multiple User-Angent strings (max. 50) at the same time. The requests count per round is equal to total User-Agent strings passed. This feature is only available for paid plans.
To perform bulk User-Agent strings parse, send a POST request and pass the "uaStrings" array as JSON data along with it. Here is an example:
$ curl --location --request POST 'https://api.ipgeolocation.io/user-agent-bulk?apiKey=API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{ "uaStrings": ["Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36", "Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+", "Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)"] }'
Crawlers and bots pass their User Agent Strings with header and our API can parse that as well and detects the type of crawler.
Here is User Agent String of Google Bot with Nexus mobile device.
Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)
A curl request with this header will yield:
curl --location --request GET 'https://api.ipgeolocation.io/user-agent?apiKey=API_KEY' \
--header 'User-Agent: Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)' \
{
"userAgentString": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
"name": "Googlebot",
"type": "Robot Mobile",
"version": "2.1",
"versionMajor": "2",
"device": {
"name": "Google",
"type": "Robot Mobile",
"brand": "Google",
"CPU": null
},
"engine": {
"name": "Googlebot",
"type": "Robot",
"version": "Googlebot",
"versionMajor": "Googlebot"
},
"operatingSystem": {
"name": "Google",
"type": "Cloud",
"version": "Google",
"versionMajor": "Google"
}
}
The hackers usually malform the user agent strings and append their custom scripts with it. Whenever our API detects such anamolies, it reports back with appropriate message. Here is an example of malformed Google bot user agent.
Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html) select name
Notice that a SQL query select name is appended to the string. Here is how our API reacts to it:
curl --location --request GET 'https://api.ipgeolocation.io/user-agent?apiKey=API_KEY' \
--header 'User-Agent: Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html) select name'
{
"userAgentString": "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html) select name",
"name": "Hacker",
"type": "Hacker",
"version": "Hacker",
"versionMajor": "Hacker",
"device": {
"name": "Hacker",
"type": "Hacker",
"brand": "Hacker",
"CPU": null
},
"engine": {
"name": "Hacker",
"type": "Hacker",
"version": "Hacker",
"versionMajor": "Hacker"
},
"operatingSystem": {
"name": "Hacker",
"type": "Hacker",
"version": "Hacker",
"versionMajor": "Hacker"
}
}
User agent API can be combined with IP Geolocation API when executed on client side. The flage include=useragent will fetch the required User Agent String from the header and the response will be a user_agent object concatenated with the normal response. Here is an example:
curl --location --request GET 'https://api.ipgeolocation.io/ipgeo?apiKey=&include=useragent' \
--header 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9'
{
"ip": "111.119.185.60",
"continent_code": "AS",
"continent_name": "Asia",
"country_code2": "PK",
"country_code3": "PAK",
"country_name": "Pakistan",
"country_capital": "Islamabad",
"state_prov": "Sindh",
"district": "Nazimabad",
"city": "Karachi",
"zipcode": "74700",
"latitude": "24.91510",
"longitude": "67.02710",
"is_eu": false,
"calling_code": "+92",
"country_tld": ".pk",
"languages": "ur-PK,en-PK,pa,sd,ps,brh",
"country_flag": "https://ipgeolocation.io/static/flags/pk_64.png",
"geoname_id": "1346827",
"isp": "Connect Communication",
"connection_type": "",
"organization": "",
"asn": "",
"currency": {
"code": "PKR",
"name": "Pakistan Rupee",
"symbol": "₨"
},
"time_zone": {
"name": "Asia/Karachi",
"offset": 5,
"current_time": "2020-04-18 00:15:49.783+0500",
"current_time_unix": 1587150949.783,
"is_dst": false,
"dst_savings": 0
},
"user_agent": {
"userAgentString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9",
"name": "Safari",
"type": "Browser",
"version": "9.0.2",
"versionMajor": "9",
"device": {
"name": "Apple Macintosh",
"type": "Desktop",
"brand": "Apple",
"CPU": "Intel"
},
"engine": {
"name": "AppleWebKit",
"type": "Browser",
"version": "601.3.9",
"versionMajor": "601"
},
"operatingSystem": {
"name": "Mac OS X",
"type": "Desktop",
"version": "10.11.2",
"versionMajor": "10"
}
}
}
User Agent API and Threat Intelligence API can be combined as well. Together they form a solid framework to fight against malicious actors.
curl --location --request GET 'https://api.ipgeolocation.io/ipgeo?apiKey=&include=useragent,security' \
--header 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9'
Note: This feature is available on paid plans only.
| Field | Type | Description | Can be empty? |
|---|---|---|---|
| userAgentString | string | User-agent string that is parsed for browser, device and operating system details. | No |
| name | string | Agent name | No |
| type | string | Agent type | No |
| version | string | Agent version | No |
| versionMajor | string | Agent version major | No |
| device.name | string | Device name | No |
| device.type | string | Device type | No |
| device.brand | string | Device brand | No |
| device.CPU | string | Device's CPU model | No |
| engine.name | string | Layout engine name | No |
| engine.type | string | Layout engine type | No |
| engine.version | string | Layout engine version | No |
| engine.versionMajor | string | Layout engine version major | No |
| engine.build | string | Layout engine build | No |
| operatingSystem.name | string | Operating system name | No |
| operatingSystem.type | string | Operating system type | No |
| operatingSystem.version | string | Operating system version | No |
| operatingSystem.versionMajor | string | Operating system version major | No |
| Device Type | Description |
|---|---|
| Desktop | This device is a Desktop/Laptop |
| Mobile | This device is a mobile device however we are not sure if its a tablet, watch, e-reader or phone |
| Tablet | This device is a Tablet |
| Phone | This device is a mobile Phone |
| Watch | This device is a watch or device with tiny screen <2" |
| Virtual Reality | This is VR capable mobile device |
| eReader | Device with e-ink screen |
| Set-top box | A connected device that can interact with TV screen |
| TV | Smart TV |
| Game Console | Fixed game consoles like PS and XBox |
| Handheld Game Console | 'Mobile' game systems like the 3DS |
| Voice | A voice driven device that reads the page loud |
| Robot | Robot crawler |
| Robot Mobile | Mobile device Robot crawler |
| Robot Imitator | Robots that pretend to be Google or Bing crawlers but they usually are not official crawlers. |
| Hacker | Either the User Agent String is malformed or some kind of scripting is detected in it. |
| Anonymized | The User Agent has been altered by anonymization software. |
| Unknown | We can't extract the device information from the User Agent. |
| Operating System Type | Description |
|---|---|
| Desktop | A Desktop OS (Desktop/Laptop) |
| Mobile | A Mobile OS (Tablet/Mobile/Watch) |
| Game Console | Game Console like PlayStation |
| Embedded | An Embedded device (TV, RTOS etc) |
| Cloud | Something running in the cloud environment |
| Hacker | A hacker |
| Anonymized | Explicitly hidden with some software |
| Unknown | We really don't know about this OS |
| Layout Engine Type | Description |
|---|---|
| Browser | Regurlar Web Browser |
| Mobile App | A mobile app with webview or an app that includes regular browser |
| Hacker | Someone with malicious stuff in useragent string or malformed UA string |
| Robot | A web crawler |
| Unknown | We don't know anything about the identity of this device |
| User Agent Type | Description |
|---|---|
| Browser | Regurlar Web Browser |
| Browser Webview | Regular browser being used in a mobile app |
| Mobile App | A mobile app accessing the website |
| Robot Mobile | A web crawler who want to be detected as mobile |
| Cloud Application | Something running in the cloud (can be web scrapper etc.) |
| Email Client | An email client |
| Voice | Voice enabled browser that reads out loud |
| Special | Somethig special we can't classify |
| Testclient | Website testing tool |
| Hacker | Someone with malicious stuff in useragent string or malformed UA string |
| Unknown | We don't know |
User-Agent API returns 200 HTTP status in case of a successful request.
While, in case of an illegal request, User-Agent API returns 4xx HTTP code alongs with a descriptive message as why the error occured.
Here is the description of why a specific HTTP code is returned:
| HTTP Status | Description |
|---|---|
| 400 | (1) If the user-agent string is empty/null. (2) If your subscription is paused from use. |
| 401 | It is returned for one of the following reasons: (1) If the provided API key is not valid. (2) If your account has been disabled or locked by admin because of any illegal activity. (3) If you’re making requests after your subscription trial has been expired. (4) If you’ve exceeded your requests limit. (5) If your subscription is not active. (6) If you’re accessing a paid feature on free subscription. (7) If you’re making a request without authorization with our IP Geolocation API. |