Name: User-Agent Parser API: Browser, OS, Device Detection
Brand: viv-data
SKU: api-viv-data-ua-parser
Availability: InStock
Author: API Market

gia ly bui

# User Agent Parser — Browser, OS, Device Detection

## Overview
The User Agent Parser API provides a robust solution for instantly dissecting any User-Agent string into its constituent components. This powerful tool extracts comprehensive information about the browser, its version, the operating system, its version, and the device type (e.g., mobile, tablet, desktop, bot) from a single user agent string. Designed for developers and engineers, this API simplifies the complex task of user agent analysis, enabling applications to deliver tailored content, identify bots, and gather valuable analytics without relying on extensive regex or external libraries.

## Features
*   **Comprehensive Parsing:** Accurately extracts browser name and version, operating system name and version, and device type.
*   **Device Type Detection:** Categorizes devices as Desktop, Mobile, Tablet, or Bot.
*   **Modern Browser Support:** Supports all major and modern browsers, including Chrome, Firefox, Safari, Edge, and more.
*   **Bot and Crawler Identification:** Distinguishes between human users and automated bots/crawlers for enhanced analytics and security.
*   **Lightweight & Fast:** Delivers instant results through an efficient regex-based parsing engine.
*   **No External Libraries:** Self-contained logic ensures minimal dependencies and high reliability.

## Use Cases
*   **Web Analytics & Personalization:** Understand user demographics and device preferences to personalize content delivery, optimize user experience, and generate more accurate analytics reports for marketing and product teams.
*   **Fraud Detection & Security:** Identify automated bots, crawlers, and suspicious user agents to prevent malicious activities, protect against scraping, and enhance application security in e-commerce and financial platforms.
*   **Content Optimization & SEO:** Tailor content, stylesheets, and scripts based on the detected device type (mobile, tablet, desktop) and browser capabilities, improving page load times and search engine rankings.
*   **Customer Support & Debugging:** Quickly diagnose user-reported issues by identifying their browser, OS, and device, streamlining troubleshooting processes for technical support teams.
*   **API & Application Development:** Integrate user agent parsing into backend services to log user access, enforce platform-specific policies, or customize API responses for various client types.

## Pricing
The User Agent Parser API is priced per API unit, where **1 API unit equals 1 user agent string processed**.

Different pricing tiers are available based on usage volume:
*   **Free Tier:** 2,000 requests per month
*   **Pro Tier ($19.99/month):** 20,000 requests per month

## API Documentation

### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/viv-data/ua-parser`

### Authentication
Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```


### Endpoints

#### Parse User Agent String
**`GET /parse`**

Parses a given User-Agent string and returns structured data including browser, browser version, operating system, OS version, and device type.

**Parameters:**
*   `ua` (query parameter, **required**): The User-Agent string to parse.
    *   Type: `string`
    *   Description: The full User-Agent string from an HTTP request or a custom string.

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/ua-parser/parse?ua=Mozilla/5.0%20(Windows%20NT%2010.0)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/120.0.0.0%20Safari/537.36" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{
  "browser": "Chrome",
  "browser_version": "120.0.0.0",
  "os": "Windows",
  "os_version": "10.0",
  "device": "Desktop",
  "is_mobile": false,
  "is_tablet": false,
  "is_bot": false
}
```

#### Health Check
**`GET /health`**

Checks the health status of the API service.

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/ua-parser/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{}
```

**`HEAD /health`**

Performs a lightweight health check, returning only headers.

**Example Request:**
```bash
curl -X HEAD "https://prod.api.market/api/v1/viv-data/ua-parser/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
(No body, only HTTP headers)

#### Root Endpoint
**`GET /`**

The root endpoint of the API.

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/ua-parser/" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{}
```

## Status Codes

| Status Code | Description | Recommended Handling |
|-------------|-------------|----------------------|
| **200 OK** | The request completed successfully and returned the expected response. | Process the JSON response body. |
| **400 Bad Request** | The request was malformed or contained invalid parameters, typically due to an invalid `ua` query parameter. | Verify that your request parameters are valid and review the error response for details. |
| **401 Unauthorized** | The API key is missing or invalid. | Ensure the `x-api-market-key` header is included and contains a valid API key. |
| **403 Forbidden** | The API key is valid, but it does not have permission to access the requested resource. | Verify your API key permissions or contact support if you believe this is an error. |
| **404 Not Found** | The requested endpoint or resource does not exist. | Check the endpoint URL for typos and ensure it matches the API documentation. |
| **422 Unprocessable Entity** | The request was syntactically valid but contained invalid or missing parameter values. | Inspect the `detail` field in the response for validation errors and correct your request. |
| **429 Too Many Requests** | The rate limit for your API plan has been exceeded. | Retry the request using exponential backoff or upgrade your plan if needed. |
| **500 Internal Server Error** | An unexpected server-side error occurred. | Log the error and retry after a short delay. If the problem persists, contact support. |
| **503 Service Unavailable** | The service is temporarily unavailable due to maintenance or high load. | Retry the request using exponential backoff after waiting briefly. |

## Rate Limits
API usage is subject to rate limits based on your subscription tier (e.g., 2,000 req/month for the Free tier, 20,000 req/month for Pro). If you exceed your allocated rate limit, the API will return a `429 Too Many Requests` status code.

To handle rate limits effectively:
*   Monitor your usage and plan for peak times.
*   Implement client-side caching where appropriate to reduce redundant requests.
*   Employ an exponential backoff strategy for retrying requests after a `429` response, gradually increasing the wait time between retries.

## Error Handling
Effective error handling is crucial for building robust applications. This API uses standard HTTP status codes to indicate the outcome of a request, with detailed error messages provided in the response body for `4xx` and `5xx` errors.

**How to Interpret Error Responses:**
Error responses typically follow a structured JSON format to provide clear information about the issue.

**Common Errors and How to Resolve Them:**
*   **`400 Bad Request` or `422 Unprocessable Entity`**: Often due to missing or invalid `ua` query parameter.
    *   *Resolution:* Ensure the `ua` parameter is always present and properly URL-encoded.
    *   *Example Error:*
    ```json
    {
      "detail": [
        {
          "loc": [
            "query",
            "ua"
          ],
          "msg": "Field required",
          "type": "missing"
        }
      ]
    }
    ```
*   **`401 Unauthorized`**: Indicates an issue with your API key.
    *   *Resolution:* Double-check that `x-api-market-key` header is correctly set with your valid API key.
*   **`429 Too Many Requests`**: You've hit your rate limit.
    *   *Resolution:* Wait for the rate limit to reset, or implement a retry strategy with exponential backoff.

**Recommended Retry Strategies for Transient Errors:**
For transient errors like `429 Too Many Requests` or `503 Service Unavailable`, implement an exponential backoff strategy:
1.  Wait a short initial period (e.g., 1 second).
2.  If the error persists, double the wait time for the next retry.
3.  Add a small random jitter to the wait time to prevent thundering herd problems.
4.  Limit the number of retries and introduce a maximum wait time to avoid indefinite delays.

## Implementation Guide
This section provides code examples for integrating the User Agent Parser API into your applications. Since this is a synchronous API, you will make a single request and receive the result directly.

### Example Code

#### JavaScript
```javascript
// JavaScript example for synchronous API call
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/viv-data/ua-parser";

async function parseUserAgent(userAgentString) {
  try {
    const encodedUserAgent = encodeURIComponent(userAgentString);
    const response = await fetch(`${baseUrl}/parse?ua=${encodedUserAgent}`, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
    }

    const result = await response.json();
    return result;

  } catch (error) {
    console.error("Error parsing user agent:", error);
    throw error;
  }
}

// Example usage:
const userAgentToParse = "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1";

parseUserAgent(userAgentToParse)
  .then(data => {
    console.log("Parsed User Agent Data:", data);
  })
  .catch(err => {
    console.error("Failed to parse user agent:", err);
  });
```

#### Python
```python
# Python example for synchronous API call
import requests
import json

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/viv-data/ua-parser"

def parse_user_agent(user_agent_string):
    headers = {
        "x-api-market-key": API_KEY
    }
    params = {
        "ua": user_agent_string
    }

    try:
        response = requests.get(
            f"{BASE_URL}/parse",
            headers=headers,
            params=params,
            timeout=30 # Recommend a reasonable timeout for network requests
        )
        response.raise_for_status()  # Raises HTTPError for bad responses (4xx or 5xx)

        return response.json()

    except requests.exceptions.HTTPError as err:
        print(f"HTTP error occurred: {err}")
        print(f"Response body: {err.response.text}")
        raise
    except requests.exceptions.ConnectionError as err:
        print(f"Connection error occurred: {err}")
        raise
    except requests.exceptions.Timeout as err:
        print(f"Request timed out: {err}")
        raise
    except requests.exceptions.RequestException as err:
        print(f"An unknown error occurred: {err}")
        raise

# Example usage:
user_agent_to_parse = "Mozilla/5.0 (Linux; Android 10; SM-A205U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.99 Mobile Safari/537.36"

try:
    parsed_data = parse_user_agent(user_agent_to_parse)
    print("Parsed User Agent Data:", json.dumps(parsed_data, indent=2))
except Exception as e:
    print("Failed to parse user agent:", e)

```

#### cURL
```bash
# cURL example for synchronous API call
# Replace YOUR_API_MARKET_KEY with your actual API key

# Example 1: Parsing a desktop Chrome user agent
curl -X GET "https://prod.api.market/api/v1/viv-data/ua-parser/parse?ua=Mozilla/5.0%20(Windows%20NT%2010.0)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/120.0.0.0%20Safari/537.36" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Example 2: Parsing an iPhone Safari user agent
curl -X GET "https://prod.api.market/api/v1/viv-data/ua-parser/parse?ua=Mozilla/5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2015_0%20like%20Mac%20OS%20X)%20AppleWebKit/605.1.15%20(KHTML%2C%20like%20Gecko)%20Version/15.0%20Mobile/15E148%20Safari/604.1" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Example 3: Parsing a bot user agent (Googlebot)
curl -X GET "https://prod.api.market/api/v1/viv-data/ua-parser/parse?ua=Mozilla/5.0%20(compatible%3B%20Googlebot/2.1%3B%20%2Bhttp%3A//www.google.com/bot.html)" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
To ensure optimal performance and minimize costs when using the User Agent Parser API:

*   **Cache Results:** If you are frequently parsing the same User-Agent strings (e.g., from a static list of known bots or common browser versions), cache the results on your end to avoid redundant API calls.
*   **Batch Processing (if applicable):** While this specific API processes one `ua` string per request, for applications that might involve analyzing a large number of unique User-Agent strings, consider if any pre-filtering or data aggregation can reduce the total number of distinct requests.
*   **Efficient Error Handling:** Implement robust error handling (as described above) to quickly identify and address issues, preventing unnecessary retries or failed operations that consume resources.
*   **Monitor Usage:** Regularly monitor your API usage against your subscription limits to anticipate and avoid rate limit breaches, which can interrupt your service.

## FAQ

### What is a User-Agent string?

A **User-Agent string** is a text string sent by a web browser, mobile app, bot, or other client with every HTTP request. It identifies details such as the client application, browser, operating system, device, and version, allowing servers to tailor responses or collect analytics. :contentReference[oaicite:0]{index=0}

---

### Is this API synchronous or asynchronous?

This API is **synchronous**. You send a request containing a User-Agent string, and the API immediately returns the parsed information in the response. No polling or job IDs are required. :contentReference[oaicite:1]{index=1}

---

### What operating systems and browsers does it support?

The API supports all major modern browsers, including:

- Chrome
- Firefox
- Safari
- Edge
- Opera

It also recognizes User-Agent strings from operating systems such as:

- Windows
- macOS
- Linux
- Android
- iOS

Additionally, it can identify many bots and web crawlers. :contentReference[oaicite:2]{index=2}

---

### How accurate is the parsing?

The API uses a robust regex-based parsing engine to accurately identify:

- Browser name and version
- Operating system and version
- Device type (Desktop, Mobile, Tablet)
- Bots and crawlers

It is designed to provide reliable results across a wide variety of User-Agent strings. :contentReference[oaicite:3]{index=3}

---

### What happens if I send an invalid or unknown User-Agent string?

If the User-Agent string cannot be parsed, the API returns default values such as `"Unknown"` for the browser or operating system.

If the request itself is invalid—for example, if the required `ua` parameter is missing—the API returns a **`400 Bad Request`** or **`422 Unprocessable Entity`** error. :contentReference[oaicite:4]{index=4}

---

### Can I use this API for commercial projects?

Yes. The API is suitable for both **personal** and **commercial** use, with multiple pricing plans available to accommodate different usage levels. :contentReference[oaicite:5]{index=5}

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Parse User-Agent strings to accurately detect browser, OS, device type, and version. This regex-based API provides instant results, identifying modern browsers 