User Agent API

Overview

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 these details 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/v3/user-agent and its full JSON response is below:

1{
2  "user_agent_string": "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  "version_major": "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    "version_major": "601"
18  },
19  "operating_system": {
20    "name": "Mac OS",
21    "type": "Desktop",
22    "version": "10.11.2",
23    "version_major": "10.11",
24    "build": "??"
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 the 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, follow this request example:

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

Copy

curl -X GET 'https://api.ipgeolocation.io/v3/user-agent?apiKey=API_KEY' \
-H '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'

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 .

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

Copy

curl -X POST 'https://api.ipgeolocation.io/v3/user-agent?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"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,000) at the same time. The requests count per round is equal to total number of User-Agent strings passed. This feature is only available for paid subscriptions

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

Copy

curl -X POST 'https://api.ipgeolocation.io/v3/user-agent-bulk?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"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 http request with this header will yield:

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

Copy

curl -X GET 'https://api.ipgeolocation.io/v3/user-agent?apiKey=API_KEY' \
-H '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)'

1{
2  "user_agent_string": "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  "version_major": "2",
7  "device": {
8    "name": "Google",
9    "type": "Robot Mobile",
10    "brand": "Google",
11    "cpu": "Unknown"
12  },
13  "engine": {
14    "name": "Googlebot",
15    "type": "Robot",
16    "version": "537.36",
17    "version_major": "537"
18  },
19  "operating_system": {
20    "name": "Google Cloud",
21    "type": "Cloud",
22    "version": "6.0.1",
23    "version_major": "6",
24    "build": "??"
25  }
26}

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

Copy

curl -X GET 'https://api.ipgeolocation.io/v3/user-agent?apiKey=API_KEY' \
-H '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'

1{
2  "user_agent_string": "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  "version_major": "Hacker",
7  "device": {
8    "name": "Hacker",
9    "type": "Hacker",
10    "brand": "Hacker",
11    "cpu": "Unknown"
12  },
13  "engine": {
14    "name": "Hacker",
15    "type": "Hacker",
16    "version": "Hacker",
17    "version_major": "Hacker"
18  },
19  "operating_system": {
20    "name": "Hacker",
21    "type": "Hacker",
22    "version": "Hacker",
23    "version_major": "Hacker",
24    "build": "??"
25  }
26}

Combine User Agent API with IP Geolocation API

User agent API can be combined with IP Geolocation API when executed on client side. The flag include=user_agent will fetch the required User Agent String from the header and the response will be a user_agent object concatenated with the normal response. This is also available only for paid subscriptions . Here is an example:

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

Copy

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&fields=location&include=user_agent' \
-H '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'

1{
2  "ip": "149.40.62.5",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "country_capital": "Washington, D.C.",
11    "state_prov": "Washington",
12    "state_code": "US-WA",
13    "district": "King",
14    "city": "Seattle",
15    "locality": "Seattle",
16    "accuracy_radius": "",
17    "zipcode": "98104",
18    "latitude": "47.60357",
19    "longitude": "-122.32945",
20    "is_eu": false,
21    "country_flag": 
22      "https://ipgeolocation.io/static/flags/us_64.png",
23    "geoname_id": "11386261",
24    "country_emoji": "🇺🇸"
25  },
26  "user_agent": {
27    "user_agent_string": "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",
28    "name": "Safari",
29    "type": "Browser",
30    "version": "9.0.2",
31    "version_major": "9",
32    "device": {
33      "name": "Apple Macintosh",
34      "type": "Desktop",
35      "brand": "Apple",
36      "cpu": "Intel"
37    },
38    "engine": {
39      "name": "AppleWebKit",
40      "type": "Browser",
41      "version": "601.3.9",
42      "version_major": "601"
43    },
44    "operating_system": {
45      "name": "Mac OS",
46      "type": "Desktop",
47      "version": "10.11.2",
48      "version_major": "10.11",
49      "build": "??"
50    }
51  }
52}

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

User-Agent API returns HTTP status code 200 for a successful API request along with the response.

While, in case of an illegal request, User-Agent API returns 4xx HTTP code alongs with a descriptive message as why the error occurred.

Below is a detailed explanation of the specific HTTP status codes and their corresponding error conditions: