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:

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  },
19  "operatingSystem": {
20    "name": "Mac OS",
21    "type": "Desktop",
22    "version": "10.11.2",
23    "versionMajor": "10.11"
24  }
25}

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 -X GET 'https://api.ipgeolocation.io/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'

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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X POST 'https://api.ipgeolocation.io/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 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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X POST 'https://api.ipgeolocation.io/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 -X GET 'https://api.ipgeolocation.io/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  "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": "Unknown"
12  },
13  "engine": {
14    "name": "Googlebot",
15    "type": "Robot",
16    "version": "537.36",
17    "versionMajor": "537"
18  },
19  "operatingSystem": {
20    "name": "Google Cloud",
21    "type": "Cloud",
22    "version": "6.0.1",
23    "versionMajor": "6"
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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X GET 'https://api.ipgeolocation.io/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  "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": "Unknown"
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

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X GET 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&fields=geo&include=useragent' \
-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  "continent_code": "NA",
4  "continent_name": "North America",
5  "country_code2": "US",
6  "country_code3": "USA",
7  "country_name": "United States",
8  "country_name_official": "United States of America",
9  "is_eu": false,
10  "state_prov": "Washington",
11  "state_code": "US-WA",
12  "district": "King County",
13  "city": "Seattle",
14  "zipcode": "98164",
15  "latitude": "47.60621",
16  "longitude": "-122.33207",
17  "user_agent": {
18    "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",
19    "name": "Safari",
20    "type": "Browser",
21    "version": "9.0.2",
22    "versionMajor": "9",
23    "device": {
24      "name": "Apple Macintosh",
25      "type": "Desktop",
26      "brand": "Apple",
27      "cpu": "Intel"
28    },
29    "engine": {
30      "name": "AppleWebKit",
31      "type": "Browser",
32      "version": "601.3.9",
33      "versionMajor": "601"
34    },
35    "operatingSystem": {
36      "name": "Mac OS",
37      "type": "Desktop",
38      "version": "10.11.2",
39      "versionMajor": "10.11"
40    }
41  }
42}

Combine User Agent API with Security API

User Agent API and Threat Intelligence API can be combined as well. Together they form a solid framework to fight against malicious actors. Here we are fetching parsed user agent details along with the geolocation and security information of the client.

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X GET 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&fields=geo&include=useragent,security' \
-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'

Note: This feature is available on paid plans only.

Reference to User-Agent API Response

• 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

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

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

API SDKs

To facilitate the developers, we have added some SDKs for various programming languages. The detailed documentation on how to use these SDKs is available in the respective SDK's documentation page linked below.

Our SDKs are also available on Github. Feel free to help us improve them. SDKs. Following are the available SDKs:

• IP Geolocation API Java SDK
• IP Geolocation API C-Sharp dotNet SDK
• IP Geolocation API Typescript SDK
• IP Geolocation API PHP SDK
• IP Geolocation API JQuery SDK