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:
- Bots win over everything. A mobile Googlebot reports
device_type: "bot", even thoughis_mobilemay betrue. Don't usedevice_typeas a substitute for the individual flags. - iPadOS Safari reports as
Mac. Desktop-mode Safari sends aMacintoshUA, so iPad traffic can land indesktop. Combine withis_tablet/is_mobilewhen 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
422rather than truncated server-side. - Treat
versionas a string, never a number."125.0.0.0"and"17.4"have different segment counts and some browsers report"", whichfloat()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_botbefore recording page views — you'll otherwise inflate traffic with crawlers. But don't block onis_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_tabletover parsingdevice.familystrings. 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.
Related endpoints¶
- Parsing & Analysis — URL, IP, HTTP header, cron, and timestamp parsers
- Data & Format Tools — JSON/YAML/CSV conversion
- Generation & Mock Data — generate random User-Agent strings for tests