User Agent Parser 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:

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

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


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

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

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

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

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