---
title: "Documentation for User Agent Parsing API | IPGeolocation.io"
slug: "/documentation/user-agent-api.html"
parent: "IP Geolocation API"
description: "Explore detailed documentation for IPGeolocation.io's User Agent API. Parse your user's device, OS, and browser information with examples and authentication."
---

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

> [!NOTE]
> For client-side calls to the endpoints mentioned below using the Request Origin (available on paid plans only), the apiKey parameter can be omitted.

> [!IMPORTANT]
> Plan Availability
>
> - `/v3/user-agent (GET)` Available on all plans
> - `/v3/user-agent (POST)` Paid plans only
> - `/v3/user-agent-bulk` Paid plans only
>
>
> Each successful User-Agent lookup costs 1 credit per user-agent. The `X-Credits-Charged` response header shows the total credits charged for the request. For details, please refer to our [Credits Usage Guide.](https://ipgeolocation.io/documentation/credits-usage.html)

* * *

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

**Response Preview**

```json
{
  "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)",
  "name": "Googlebot",
  "type": "Robot Mobile",
  "version": "2.1",
  "version_major": "2",
  "device": {
    "name": "Google",
    "type": "Robot Mobile",
    "brand": "Google",
    "cpu": "Unknown"
  },
  "engine": {
    "name": "Googlebot",
    "type": "Robot",
    "version": "??",
    "version_major": "??"
  },
  "operating_system": {
    "name": "Google Cloud",
    "type": "Cloud",
    "version": "??",
    "version_major": "??",
    "build": "??"
  }
}
```

* * *

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

* * *

## 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 -X POST 'https://api.ipgeolocation.io/v3/user-agent?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"uaString":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"}'
```

* * *

## 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 -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 -X POST 'https://api.ipgeolocation.io/v3/user-agent?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"uaString":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"}'
```

**Response Preview**

```json
{
  "user_agent_string": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
  "name": "Chrome",
  "type": "Browser",
  "version": "58.0.3029.110",
  "version_major": "58",
  "device": {
    "name": "Desktop",
    "type": "Desktop",
    "brand": "Unknown",
    "cpu": "Intel x86_64"
  },
  "engine": {
    "name": "Blink",
    "type": "Browser",
    "version": "58.0",
    "version_major": "58"
  },
  "operating_system": {
    "name": "Windows NT",
    "type": "Desktop",
    "version": "10.0",
    "version_major": "10",
    "build": "??"
  }
}
```

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

**Response Preview**

```json
{
  "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",
  "name": "Hacker",
  "type": "Hacker",
  "version": "Hacker",
  "version_major": "Hacker",
  "device": {
    "name": "Hacker",
    "type": "Hacker",
    "brand": "Hacker",
    "cpu": "Unknown"
  },
  "engine": {
    "name": "Hacker",
    "type": "Hacker",
    "version": "Hacker",
    "version_major": "Hacker"
  },
  "operating_system": {
    "name": "Hacker",
    "type": "Hacker",
    "version": "Hacker",
    "version_major": "Hacker",
    "build": "??"
  }
}
```

* * *

## User-Agent Details in Main IPGeolocation Endpoint

User-agent data is available only on the **Paid plan** of the **IP Geolocation API**. See the [Pricing page](https://ipgeolocation.io/pricing.html) for plan details.  
  
You can retrieve user-agent parsing details using the `/v3/ipgeo` endpoint by explicitly including `include=user_agent` in the query parameters. When requested, the response includes parsed user-agent information along with location, abuse contact, timezone, ASN data, security, network, company and other fields described in the [IP Geolocation API documentation](https://ipgeolocation.io/documentation/ip-location-api.html).  
  
User-agent details are returned in the `/v3/ipgeo` response once the `user_agent` object is enabled, as shown below.

```
curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&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'
```

**Response Preview**

```json
{
  "ip": "39.63.38.164",
  "user_agent": {
    "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",
    "name": "Safari",
    "type": "Browser",
    "version": "9.0.2",
    "version_major": "9",
    "device": {
      "name": "Apple Macintosh",
      "type": "Desktop",
      "brand": "Apple",
      "cpu": "Intel"
    },
    "engine": {
      "name": "AppleWebKit",
      "type": "Browser",
      "version": "601.3.9",
      "version_major": "601"
    },
    "operating_system": {
      "name": "Mac OS",
      "type": "Desktop",
      "version": "10.11.2",
      "version_major": "10.11",
      "build": "??"
    }
  },
  "location": {
    "continent_code": "AS",
    "continent_name": "Asia",
    "country_code2": "PK",
    "country_code3": "PAK",
    "country_name": "Pakistan",
    "country_name_official": "Islamic Republic of Pakistan",
    "country_capital": "Islamabad",
    "state_prov": "Punjab",
    "state_code": "PK-PB",
    "district": "Lahore",
    "city": "Lahore",
    "zipcode": "54000",
    "latitude": "31.52037",
    "longitude": "74.35875",
    "is_eu": false,
    "country_flag": "https://ipgeolocation.io/static/flags/pk_64.png",
    "geoname_id": "7043715",
    "country_emoji": "🇵🇰"
  },
  "country_metadata": {
    "calling_code": "+92",
    "tld": ".pk",
    "languages": [
      "ur-PK",
      "en-PK",
      "pa",
      "sd",
      "ps",
      "brh"
    ]
  },
  "network": {
    "connection_type": "",
    "route": "39.63.32.0/19",
    "is_anycast": false
  },
  "currency": {
    "code": "PKR",
    "name": "Pakistan Rupee",
    "symbol": "₨"
  },
  "asn": {
    "as_number": "AS17557",
    "organization": "Pakistan Telecommunication Company Limited",
    "country": "PK",
    "type": "ISP",
    "domain": "ptcl.net",
    "date_allocated": "",
    "rir": "APNIC"
  },
  "company": {
    "name": "Pakistan Telecommuication company limited",
    "type": "ISP",
    "domain": "ptcl.com.pk"
  },
  "time_zone": {
    "name": "Asia/Karachi",
    "offset": 5,
    "offset_with_dst": 5,
    "current_time": "2026-05-20 13:18:02.160+0500",
    "current_time_unix": 1779265082.16,
    "current_tz_abbreviation": "PKT",
    "current_tz_full_name": "Pakistan Standard Time",
    "standard_tz_abbreviation": "PKT",
    "standard_tz_full_name": "Pakistan Standard Time",
    "is_dst": false,
    "dst_savings": 0,
    "dst_exists": false,
    "dst_tz_abbreviation": "",
    "dst_tz_full_name": "",
    "dst_start": {},
    "dst_end": {}
  }
}
```

> [!IMPORTANT]
> The `user_agent` object returned by `/v3/ipgeo` (when requested using `include=user_agent` ) contains the same user-agent parsing details available through the dedicated `/v3/user-agent` endpoint.  
>
> Requests to the `/v3/user-agent` endpoint cost **1 credit** per successful lookup.  
>
> When using `/v3/ipgeo` with `include=user_agent` , no additional credits are charged beyond the base lookup cost. The total request cost remains **1 credit**, unless additional billable objects are requested.  
>
> Use `/v3/ipgeo` when user-agent data is required together with location, ASN, security, abuse contact, timezone, company, or network information in a single response.  
>
> When only user-agent parsing details are required, the dedicated `/v3/user-agent` endpoint may be used to reduce response payload size.

* * *

## Reference to User-Agent API Response

| Field | Type | Description | Can be empty? |
| --- | --- | --- | --- |
| user_agent_string | 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  |
| version_major | 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.version_major | string | Layout engine version major | No  |
| operating_system.name | string | Operating system name | No  |
| operating_system.type | string | Operating system type | No  |
| operating_system.version | string | Operating system version | No  |
| operating_system.version_major | string | Operating system version major | No  |
| operating_system.build | string | Operating system build number | No  |

> [!NOTE]
> - 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 |
| 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 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:

| HTTP Status | Description |
| --- | --- |
| 400 Bad Request | It is returned for one of the following reasons: * If special character(s) ( ) [ ] { } \\| ^ ` is passed in the API URL either as parameter or its value. Specially in case of API key. * If the user-agent string is empty/null. * If the User Agent Strings JSON list is empty, or the provided JSON does not have 'uaStrings' field while querying `user-agent-bulk` endpoint. * If more than 50,000 user agent strings are provided while querying from `user-agent-bulk` endpoint. |
| 401 Unauthorized | It is returned for one of the following reasons: * If API key (as `apiKey` URL parameter) is missing from the request to User Agent API. * If the provided API key is not valid. * When the request is made using API key of a database subscription. * 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 your subscription is paused or is not active. * If your account's active-until date has passed and you need to renew or upgrade your subscription. * If you're accessing a paid feature on free subscription. * If bulk user agent parsing endpoint is called using free subscription API key. |
| 404 Not Found | It is returned for one of the following reasons: * If the wrong endpoint is called, that does not exist in our API. |
| 405 Method Not Allowed | * If wrong HTTP request method is used for calling the endpoints. Only GET and POST methods are allowed: `user-agent` supports GET and POST `user-agent-bulk` supports POST only |
| 413 Content Too Large | * If the passed data in the POST requests is more than the limit of the API. |
| 415 Unsupported Media Type | * If the `Content-Type` header is not set to `application/json` , while sending a request to the `user-agent` (POST) or `user-agent-bulk` endpoint. |
| 429 Too Many Requests | It is returned for one of the following reasons: * If the API usage limit has reached for the free subscriptions, or paid subscriptions with the status 'past due', 'deleted' or 'trial expired'. * If the surcharge API usage limit has reached against the subscribed plan. |
| 499 Client Closed Request | * If the client has set the very short request or connection timeout, leading to the server closing the request prematurely. |
| 5XX Server Side Error | * If a `500` (Internal Server Error), `502` (Bad Gateway), `503` (Service Unavailable), `504` (Gateway Timeout), or `505` (HTTP Version Not Supported) status code is returned, it indicates an issue on our end. Please contact us with your request at [support@ipgeolocation.io](mailto:support@ipgeolocation.io) for further assistance. |

* * *

## 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. Following are the available SDKs:

*   [IP Geolocation API Java SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-java-sdk.html)
*   [IP Geolocation API Python SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-python-sdk.html)
*   [IP Geolocation API Go SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-go-sdk.html)
*   [IP Geolocation API Ruby SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-ruby-sdk.html)
*   [IP Geolocation API C-Sharp dotNet SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-c-sharp-dotnet-sdk.html)
*   [IP Geolocation API Rust SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-rust-sdk.html)
*   [IP Geolocation API Kotlin SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-kotlin-sdk.html)
*   [IP Geolocation API Swift SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-swift-sdk.html)
*   [IP Geolocation API C++ SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-cpp-sdk.html)
*   [IP Geolocation API PHP SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-php-sdk.html)
*   [IP Geolocation API Typescript SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-typescript-sdk.html)
*   [IP Geolocation API Javascript SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-javascript-sdk.html)
*   [IP Geolocation API JQuery SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-jquery-sdk.html)
*   [Astronomy API Javascript SDK](https://ipgeolocation.io/documentation/astronomy-api-sdk.html)

Looking for features, pricing, and use cases? Visit the User Agent API page.

[Explore User Agent API](https://ipgeolocation.io/user-agent-api.html)