Feeling a bit confused by the API? That's ok; user agents, client hints, and browser detection in general are a pretty confusing topic to begin with, and while we've tried to keep the API as simple and as easy to use as possible, we know it can still be a bit much to figure out. So lets go right from the beginning.
The WhatIsMyBrowser.com API is a subscription based service, it's primary goal is to provide a service that makes it easy for web developers to detect the web browsers, operating systems, devices, hardware types, and so on, that visitors to their sites are using.
A user agent is a relatively short string of text, that attempts to describe a web browser, bot, or application.
Every time a web browser, bot, or application wishes to access a page on the internet, it sends a request to the relevant web server for that page. Each request includes a series of pieces of information called "HTTP Headers". These HTTP Headers typically add a bit more information to that request; for example browsers usually include an "Accept Language" header in their requests, which indicates which written language/s that you the user can understand. Sometimes there is also a "referrer" heading which indicates the web page which referred the user to that page.
One of the more interesting HTTP Headers is known as the "User Agent String" - it is essentially a series of short fragments of text and numbers which provide hints about the type of software requesting the page.
When your web browser loads any page on the internet, it sends a request, part of which includes a bit of information (the User Agent) that says "I'm using Chrome on Windows" or something like that.
That all seems simple enough so far, right? Why is there a need for an API to deal with user agents?
In the early days of the internet, the theory was that user agent strings were meant to be straight-forward explanations of the "agent" (the browser, bot, or program) making a web request. However, over time, and due to various bad practices that web developers and browser manufacturers that began in the 1990s, the user agent string has become very convoluted, messy, and difficult to understand. Some user agents even contain descriptive fragments in them which are intentionally incorrect.
There is also no official format or structure to a user agent string, so just about every web browser, bot, and program sends its user agent string in a different style. So you can't just assume that "the first part of the user agent string means this and the second part means that...". You have to analyse each user agent in complicated ways to determine what it really means.
As well as all of this, user agents can be changed or "faked"; introducing further complexity and in some cases contradictions (and even spam or security risks!)
User agent strings for mobile devices don't usually contain the "device name"; often it's just an arcane Model Number.
We have been developing our User Agent Parsing library since 2010, and we've "seen it all". Our User Agent Parsing library knows how to decipher the user agents of thousands of different browsers, bots, and applications, and knows how to recognize tens of thousands of different device models and platforms. It can also identify problems and risks with some types of user agents. We can even let you know if a web browser is out of date!
Maintaining the software to do this, and doing it "The Right Way" is difficult and time consuming and requires a lot of background knowledge. We've taken the software we've been writing for more than 14 years and made it available via the API. So instead of doing it yourself, you are invited to use what we've made, freeing you up to do more interesting things.
So far we've discussed user agents without actually giving some examples. Here are a few sample ones, to illustrate some of the reasons you need a good user agent parser:
That's about as simple and readable as browser user agents come - it has the Chrome fragment with the full version number, it shows that it's macOS and the version number. It doesn't specifically state the kind of device it's on (A computer). It doesn't tell you if it's out of date or not. It also has fragments which are actually incorrect - the Mozilla/5.0, AppleWebKit, KHTML, like Gecko, and Safari are all "wrong" technically speaking. Chrome includes them in it's user agent for historical reasons.
You can see it looks almost like an Android user agent, but it has the Googlebot and Google fragments in it. When Google's bots roam the internet, this is one of the ways they identify themselves.
The Facebook App's user agent comes in lots of different varieties, this is one of them.
We've collected over 410 million different user agents and categorised them in different ways. If you're curious about all the different formats you can have a look around at them all.
To use the API, you will typically write software that sends a HTTP "request" containing a user agent string to the API. Our API will "parse" that user agent and send you a response which contains an interpretation of that user agent; seperated into dozens of different fields.
How you use that parse response is up to you and depends on your own objectives. Here is a list of API Use Cases to explore.
There are other uses of the API as well, but the parse end point is definitely the main feature that our customers use.
To start sending API requests there's a few short steps you need to take. They are covered in our detailed Integration Guide, but we'll outline them here as well:
The first thing you need to do is create an API account. There are no costs for registering an account and even on the paid plans you are welcome to test it out before having to pay for it. If you decide the API isn't for you, just let us know and we'll cancel your invoice for you.
Once you've created an account with us, head over to the Accounts System and log in. There you will see a link titled Get your API Key. Click it and you will see a page showing you your API key. Keep it secret and safe - you'll need it to authenticate your API requests.
The easiest way to do this is to test out some Sample Code. We've got some basic code in a number of programming languages which will help you get started. It's not a full solution and you will need to write code that is tailored to your specific needs, but the sample code is a good place to start to get a feel for the API.
For more detail about sending API requests, including extra options you can set, and detailed explanations of the API End points and their request/response formats, as well as troubleshooting steps, dive in to our Integration Guide.
If you're still having trouble or have some questions, just send us a message and we'll get back to you ASAP.