User Agents
===========

Parse User-Agent strings into structured browser, OS, device, and bot data.

.. contents:: Tools on this page
   :local:
   :depth: 1


apicrate-parse-user-agent
-------------------------

Parse a single User-Agent string into structured device, browser, and OS data.
Returns detailed classification flags and nested objects for client, OS, device,
and bot information.

**Credit cost:** 2 credits per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``user_agent_string``
     - string
     - yes
     - Full User-Agent header value to parse.

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-parse-user-agent",
     "arguments": {
       "user_agent_string": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
     }
   }

Response:

.. code-block:: json

   {
     "client": {
       "type": "browser",
       "name": "Chrome",
       "version": "125.0",
       "engine": "Blink",
       "engine_version": "125.0"
     },
     "os": {
       "name": "Windows",
       "version": "10",
       "platform": "x64"
     },
     "device": {
       "type": "desktop",
       "brand": "",
       "model": ""
     },
     "bot": null,
     "is_bot": false,
     "is_browser": true,
     "is_mobile": false,
     "is_desktop": true,
     "is_tablet": false,
     "is_tv": false,
     "is_touch_enabled": false
   }

Errors
^^^^^^

- **Empty string** -- an empty ``user_agent_string`` returns a response with all
  fields set to their empty/default values (no error is raised).


apicrate-parse-user-agents-bulk
-------------------------------

Parse multiple User-Agent strings in a single call. Efficiently processes up to
100 UA strings at once.

**Credit cost:** 1 credit per UA string.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``user_agent_strings``
     - list[string]
     - yes
     - List of User-Agent header values to parse. Maximum 100 items.

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-parse-user-agents-bulk",
     "arguments": {
       "user_agent_strings": [
         "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
         "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
       ]
     }
   }

Response:

.. code-block:: json

   {
     "count": 2,
     "results": [
       {
         "user_agent_string": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
         "client": {
           "type": "browser",
           "name": "Chrome",
           "version": "125.0",
           "engine": "Blink",
           "engine_version": "125.0"
         },
         "os": {
           "name": "Windows",
           "version": "10",
           "platform": "x64"
         },
         "device": {
           "type": "desktop",
           "brand": "",
           "model": ""
         },
         "bot": null,
         "is_bot": false,
         "is_browser": true,
         "is_mobile": false,
         "is_desktop": true
       },
       {
         "user_agent_string": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
         "client": {
           "type": "browser",
           "name": "Googlebot",
           "version": "2.1",
           "engine": "",
           "engine_version": ""
         },
         "os": {
           "name": "",
           "version": "",
           "platform": ""
         },
         "device": {
           "type": "",
           "brand": "",
           "model": ""
         },
         "bot": {
           "name": "Googlebot",
           "category": "Search bot",
           "url": "http://www.google.com/bot.html",
           "producer": {
             "name": "Google Inc.",
             "url": "https://www.google.com"
           }
         },
         "is_bot": true,
         "is_browser": false,
         "is_mobile": false,
         "is_desktop": false
       }
     ]
   }

Errors
^^^^^^

- **Empty list** -- passing an empty ``user_agent_strings`` list returns an
  error. At least one UA string is required.
- **Over 100 items** -- lists exceeding 100 entries are rejected. Split large
  batches into multiple calls.