UseragentAPI Documentation


Version 4 of the UseragentAPI introduces a number of improvements including: device detection, increased accuracy, and new useragent types.

We've added over 175+ Bots, and every device we could find including, smartphones, tablets, TVs, Cameras, even Cars.

We now detect the following useragent types:

Desktop
Typically Windows, Mac, or Linux Machines

Tablet
Such as the iPad, Kindle, or Galaxy

Mobile
Smartphones and older model phones

TV
Smart TVs, AppleTV, Roku, etc.

Game Console
Playstation, Wii, Xbox, etc.

Bot
Bots, including webcrawlers, uptime checkers, and webHook agents.

Library
Utilities used by servers such as Wget & Curl

App
Applications that run on a device. Facebook, Pinterest, etc.

Mail
Email clients such as Thunderbird and Outlook

Feed Reader
RSS readers like NetNewsWire & Reeder

Auto
Yep, cars have a useragent now too, such as the Tesla Model S

Camera
Camera models including Nikon & Samsung.

Media Player
iPod, Zune, Galaxy Media Player, etc.

Wearable
Wearable device detection such as the Google Glass


API Request


HTTP
http or https
APIKEY
Unique account identifier received after signup
USERAGENT
urlencoded() Useragent string
HTTP://useragentapi.com/api/v4/json/APIKEY/USERAGENT

Example Request GET
https://useragentapi.com/api/v4/json/APIKEY/CCBot%2F2.0+%28http%3A%2F%2Fcommoncrawl.org%2Ffaq%2F%29

API Response


We return the useragent, operating system and browser data in the following fields:

Useragent

ua_type Useragent type, exact values returned: Auto, App, Bot, Camera, Desktop, Feed Reader, Game Console, Tablet, Mail, Media Player, Mobile, Library, TV, Wearable.

ua_brand Useragent brand many values returned: Apple, Microsoft, Samsung, Google, etc.

ua_name Useragent name many values returned: iPhone, Googlebot, Outlook, Kindle Fire, etc.

ua_version Useragent version many values returned: 7 for iPhone, HD for Kindle Fire, Note 10.1" for Galaxy.

ua_url Useragent url if available, for example a link to the Googlebot's webpage.

Operating System

os_name Operating system name many values returned: MacOS, Windows, Android, etc.

os_version Operating system version examples: 10.7.5 for MacOS, Vista for Windows, 6.0 for Android.

Browser

browser_name Browser name, many values returned: Safari, Chrome, Firefox, Opera, etc.

browser_version Browser version.

engine_name Browser engine name, many values returned: WebKit, Gecko, Edge, etc.

engine_version Browser engine version

Example Response JSON

{
    "data": {
        "ua_type": "Bot",
        "ua_name": "ccBot crawler"
    }
}

Errors


The API makes use of standard HTTP errors to indicate the success or failure of a request. The 2xx series of response codes indicate a success, 4xx indicates an error from the client side, and a 5xx error indicates a server side error. Here are the HTTP response codes the API utilizes:

  • 200 - OK Everything worked as expected.
  • 400 - Bad Request The request was unacceptable, often due to missing a required parameter.
  • 404 - Not Found The requested resource doesn't exist.
  • 500 - Internal Server Error Something went wrong on our end.
Error Response

{
    "error": {
        "code": "useragent_not_found",
        "message": "Useragent Not Found"
    }
}

Error Messages

  • type_invalid - API response type invalid, must be json
  • key_invalid - API Key Invalid
  • useragent_invalid - Useragent Invalid
  • useragent_not_found - Useragent Not Found



Sample Code


<?php
	$ua = urlencode($_SERVER['HTTP_USER_AGENT']);
	
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, "http://useragentapi.com/api/v4/json/APIKEY/$ua");
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
	
	$result = curl_exec($ch);
	$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
	curl_close($ch);
	
	print_r($result);
?>
<script>
	var ua = encodeURIComponent(navigator.userAgent).replace(/%20/g,'+');
	var xhr = new XMLHttpRequest();
	xhr.open('GET', 'http://useragentapi.com/api/v4/json/APIKEY/'+ua, false);
	xhr.send();

	if (xhr.status == 200) {
		var result = JSON.parse(xhr.responseText);
		console.log(result);
	}
</script>
	import requests
	
	url = 'http://useragentapi.com/api/v4/json/APIKEY'
	ua = request.META['HTTP_USER_AGENT']
	
	r = requests.get(url, params={'ua': ua})
	
	data = r.json()
	require 'net/http'
	require 'json'
	
	ua = request.env['HTTP_USER_AGENT']
	 
	url = 'http://useragentapi.com/api/v4/json/APIKEY/ua'
	uri = URI(url)
	response = Net::HTTP.get(uri)
	JSON.parse(response)
	var request = require('request');
	
	var ua = req.headers['user-agent'];
	var url = 'http://useragentapi.com/api/v4/json/APIKEY/ua';
	
	request(url, function (error, response, body) {
		if (!error && response.statusCode == 200) {
			var data = JSON.parse(body);
		}
	});