User-Agent Parsing

POST /v1/user-agent turns a raw User-Agent header into structured browser, OS, and device data plus boolean flags you can branch on.

Method Endpoint Purpose
POST /v1/user-agent Parse one User-Agent string

Parameters

Name In Type Required Notes
ua body string yes The raw User-Agent string. Max 2000 characters.
curl -X POST "https://dev.toolkitapi.io/v1/user-agent" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"}'
import requests

def parse_ua(ua_string: str) -> dict:
    r = requests.post(
        "https://dev.toolkitapi.io/v1/user-agent",
        headers={"X-API-Key": "YOUR_KEY"},
        json={"ua": ua_string[:2000]},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()

info = parse_ua(
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
    "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
)
print(f"{info['browser']['family']} {info['browser']['version']}")
print(f"{info['os']['family']} {info['os']['version']}")
print(f"device_type={info['device_type']}  bot={info['is_bot']}")
const UA =
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
  "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";

const resp = await fetch("https://dev.toolkitapi.io/v1/user-agent", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ ua: UA }),
});
if (!resp.ok) throw new Error(`UA parse failed: ${resp.status}`);
const data = await resp.json();

const label = `${data.browser.family} ${data.browser.version} on ${data.os.family}`;
console.log(label, `(${data.device_type})`);
if (data.is_bot) console.log("crawler traffic — skip analytics");
Response
{
  "browser": { "family": "Chrome", "version": "125.0.0.0" },
  "os": { "family": "Mac OS X", "version": "10.15.7" },
  "device": { "family": "Mac", "brand": null, "model": null },
  "is_mobile": false,
  "is_tablet": false,
  "is_pc": true,
  "is_bot": false,
  "device_type": "desktop"
}
Response — iOS phone
{
  "browser": { "family": "Mobile Safari", "version": "17.4" },
  "os": { "family": "iOS", "version": "17.4" },
  "device": { "family": "iPhone", "brand": "Apple", "model": "iPhone" },
  "is_mobile": true,
  "is_tablet": false,
  "is_pc": false,
  "is_bot": false,
  "device_type": "mobile"
}
Response — crawler
{
  "browser": { "family": "Googlebot", "version": "" },
  "os": { "family": "Other", "version": "" },
  "device": { "family": "Spider", "brand": null, "model": null },
  "is_mobile": false,
  "is_tablet": false,
  "is_pc": false,
  "is_bot": true,
  "device_type": "bot"
}

Field reference

Field Type Description
browser.family string Browser name, e.g. Chrome, Mobile Safari, Firefox, Googlebot
browser.version string Version string; empty string when unknown
os.family string OS name, e.g. Mac OS X, iOS, Windows, Android, Other
os.version string OS version; empty string when unknown
device.family string Device family, e.g. iPhone, iPad, Mac, Spider, Other
device.brand string | null Manufacturer when the UA advertises it
device.model string | null Model when the UA advertises it
is_mobile boolean Phone-class device
is_tablet boolean Tablet-class device
is_pc boolean Desktop/laptop-class device
is_bot boolean Crawler, fetcher, or automation
device_type string Derived label: bot, mobile, tablet, desktop, or other

How device_type is derived

The implementation is a strict precedence chain — the first match wins:

is_bot    → "bot"
is_mobile → "mobile"
is_tablet → "tablet"
is_pc     → "desktop"
otherwise → "other"

Two consequences worth knowing:

  1. Bots win over everything. A mobile Googlebot reports device_type: "bot", even though is_mobile may be true. Don't use device_type as a substitute for the individual flags.
  2. iPadOS Safari reports as Mac. Desktop-mode Safari sends a Macintosh UA, so iPad traffic can land in desktop. Combine with is_tablet/is_mobile when it matters.

Error cases

Status Condition Response
422 ua missing, empty, not a string, or longer than 2000 chars FastAPI validation error
401/403 Missing or invalid API key auth error
{
  "detail": [
    {
      "type": "string_too_long",
      "loc": ["body", "ua"],
      "msg": "String should have at most 2000 characters",
      "input": "Mozilla/5.0 (…"
    }
  ]
}

Garbage input is not an error — {"ua": "hello"} returns 200 with browser.family: "Other" and device_type: "other". There is no "unparseable" response; check family == "Other" instead.

Tips

  • Always truncate before sending. Some clients send absurdly long UAs; anything over 2000 characters is rejected with 422 rather than truncated server-side.
  • Treat version as a string, never a number. "125.0.0.0" and "17.4" have different segment counts and some browsers report "", which float() will choke on.
  • UA is client-controlled and trivially spoofed. Use this endpoint for analytics bucketing and feature hints, never for security decisions or bot mitigation on its own.
  • Check is_bot before recording page views — you'll otherwise inflate traffic with crawlers. But don't block on is_bot; plenty of tools intentionally spoof a browser UA.
  • Cache by hash. If you parse the same UA repeatedly (e.g. per request in a busy service), key a local LRU cache on hash(ua) — the parser is deterministic.
  • Prefer is_mobile/is_tablet over parsing device.family strings. The flags come from the same parser but are stable across unknown devices.
  • Server-side detection beats UA sniffing. Use this for analytics, not for choosing responsive layouts.