Getting started

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 API itself

The 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.

What is a User Agent?

A user agent is a relatively short string of text, that attempts to describe a web browser, bot, or application.

Where are User Agents used?

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.

In other words?

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.

Why do I need an API to work with User Agents?

That all seems simple enough so far, right? Why is there a need for an API to deal with user agents?

User agents are messy and convoluted

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 an enormous variety of user agents

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.

User agents can be dangerous

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 agents don't always include enough information

User agent strings for mobile devices don't usually contain the "device name"; often it's just an arcane Model Number.

Handling all of these problems is a lot of work - so let our API do it for you

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 13 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.

What do User Agents actually look like?

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:

A standard Chrome on macOS user agent:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36

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.

A standard Firefox on Windows user agent:

Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101 Firefox/91.0

Google's "GoogleBot" user agent

Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +

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


The Facebook App's user agent comes in lots of different varieties, this is one of them.

Curious to see more sample user agents? Explore our big collection.

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.

How do I use the API?

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.

Sending your first API request

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:

Register an account with us

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.

Get your API Key

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.

Write/modify code to send 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.

Read the Documentation

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.

Still stuck?

If you're still having trouble or have some questions, just send us a message and we'll get back to you ASAP.