Single User Agent String Lookup API

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 Lookup API

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:

Response

1{
2    "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",
3    "name": "Safari",
4    "type": "Browser",
5    "version": "9.0.2",
6    "versionMajor": "9",
7    "device": {
8        "name": "Apple Macintosh",
9        "type": "Desktop",
10        "brand": "Apple",
11        "CPU": "Intel"
12    },
13    "engine": {
14        "name": "AppleWebKit",
15        "type": "Browser",
16        "version": "601.3.9",
17        "versionMajor": "601",
18        "build": "Unknown"
19    },
20    "operatingSystem": {
21        "name": "Mac OS X",
22        "type": "Desktop",
23        "version": "10.11.2",
24        "versionMajor": "10"
25    }
26}

Parse User-Agent String in User-Agent Header

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.

Parse Custom User-Agent String

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" }'

Parse Bulk User-Agent Strings

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)"] }'

Detecting Bots, Crawlers and Attackers

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)'

Response

1{
2    "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)",
3    "name": "Googlebot",
4    "type": "Robot Mobile",
5    "version": "2.1",
6    "versionMajor": "2",
7    "device": {
8        "name": "Google",
9        "type": "Robot Mobile",
10        "brand": "Google",
11        "CPU": null
12    },
13    "engine": {
14        "name": "Googlebot",
15        "type": "Robot",
16        "version": "Googlebot",
17        "versionMajor": "Googlebot"
18    },
19    "operatingSystem": {
20        "name": "Google",
21        "type": "Cloud",
22        "version": "Google",
23        "versionMajor": "Google"
24    }
25}

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'

Response

1{
2    "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",
3    "name": "Hacker",
4    "type": "Hacker",
5    "version": "Hacker",
6    "versionMajor": "Hacker",
7    "device": {
8        "name": "Hacker",
9        "type": "Hacker",
10        "brand": "Hacker",
11        "CPU": null
12    },
13    "engine": {
14        "name": "Hacker",
15        "type": "Hacker",
16        "version": "Hacker",
17        "versionMajor": "Hacker"
18    },
19    "operatingSystem": {
20        "name": "Hacker",
21        "type": "Hacker",
22        "version": "Hacker",
23        "versionMajor": "Hacker"
24    }
25}

Combine User Agent API with IP Geolocation API

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,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'

Response

1{
2    "ip": "111.119.185.60",
3    "continent_code": "AS",
4    "continent_name": "Asia",
5    "country_code2": "PK",
6    "country_code3": "PAK",
7    "country_name": "Pakistan",
8    "country_capital": "Islamabad",
9    "state_prov": "Sindh",
10    "district": "Nazimabad",
11    "city": "Karachi",
12    "zipcode": "74700",
13    "latitude": "24.91510",
14    "longitude": "67.02710",
15    "is_eu": false,
16    "calling_code": "+92",
17    "country_tld": ".pk",
18    "languages": "ur-PK,en-PK,pa,sd,ps,brh",
19    "country_flag": "images/flags/pk.svg",
20    "geoname_id": "1346827",
21    "isp": "Connect Communication",
22    "connection_type": "",
23    "organization": "",
24    "asn": "",
25    "currency": {
26        "code": "PKR",
27        "name": "Pakistan Rupee",
28        "symbol": "₨"
29    },
30    "time_zone": {
31        "name": "Asia/Karachi",
32        "offset": 5,
33        "current_time": "2020-04-18 00:15:49.783+0500",
34        "current_time_unix": 1587150949.783,
35        "is_dst": false,
36        "dst_savings": 0
37    },
38    "user_agent": {
39        "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",
40        "name": "Safari",
41        "type": "Browser",
42        "version": "9.0.2",
43        "versionMajor": "9",
44        "device": {
45            "name": "Apple Macintosh",
46            "type": "Desktop",
47            "brand": "Apple",
48            "CPU": "Intel"
49        },
50        "engine": {
51            "name": "AppleWebKit",
52            "type": "Browser",
53            "version": "601.3.9",
54            "versionMajor": "601"
55        },
56        "operatingSystem": {
57            "name": "Mac OS X",
58            "type": "Desktop",
59            "version": "10.11.2",
60            "versionMajor": "10"
61        }
62    }
63}

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

Reference to User-Agent API Response

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

Agent: The actual "Browser" that was used.
Device: The hardware that was used.
Layout Engine: The underlying core that converts the 'HTML' into a visual/interactive.
Operating System: The base software that runs on the hardware.

Possible Values of The Device Type

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

Possible Values of The Operating System Type

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
Set-top box	A connected device that can interact with TV screen
Unknown	We really don't know about this OS

Possible Values of The Engine Type

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

Possible Values of The User Agent Type

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.)
Cloud Application	Something running in the cloud (can be web scrapper etc.)
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

Error Codes

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	If the user-agent string is empty/null. If your subscription is paused from use.
401	It is returned for one of the following reasons: If the provided API key is not valid. If your account has been disabled or locked by admin because of any illegal activity. If you’re making requests after your subscription trial has been expired. If you’ve exceeded your requests limit. If your subscription is not active. If you’re accessing a paid feature on free subscription. If you’re making a request without authorization with our IP Geolocation API.

HTTP Status

Description

400

If the user-agent string is empty/null.
If your subscription is paused from use.

401

It is returned for one of the following reasons:

If the provided API key is not valid.
If your account has been disabled or locked by admin because of any illegal activity.
If you’re making requests after your subscription trial has been expired.
If you’ve exceeded your requests limit.
If your subscription is not active.
If you’re accessing a paid feature on free subscription.
If you’re making a request without authorization with our IP Geolocation API.

Overview
Single User Agent String Lookup API
Parse User-Agent String in User-Agent Header
Parse Custom User-Agent String
Detecting Bots, Crawlers and Attackers
Combine User Agent API with IP Geolocation API
Reference to User-Agent API Response
Possible Values of The Device Type
Possible Values of The Operating System Type
Possible Values of The Engine Type
Possible Values of The User Agent Type
Error Codes