WhatIsMyBrowser.com API - Version 2 - Integration Guide

Welcome

The WhatIsMyBrowser.com API provides an easy way to discover lots of useful things about web browser technology via an API.

We provide a detailed API Specification, Sample Code, and world class support.

The API integration guide you are now reading accompanies the specs, sample code and support, taking you from the beginning all the way to being set up and integrated with the API.

API Version: 2.4.8 - 29 September, 2022

Version 2 is deprecated

This documentation is for an older version of the API. Use the Version 3 Documentation for the most accurate browser detection. Read the Migration Guide for more information.

Sign Up

Before you can access the API, you need to register an account with us and get your API Key.

Once you have your API Key, you will send this as a HTTP header to show that your requests are authorised.

If you haven't already registered, you need to do so now. Go to the Sign up/Pricing page.

You are taken to a sign up form. Complete the form and submit it. We will send you an email containing a link to verify your email address. Once you click it, you will then be able to log in with your new account.

Accounts System

Once you are logged in, you will see the Accounts System landing page looking like this:

The Accounts System lets you do things like Change your Billing Details, Check your API Usage and Get your API Key.

Any time you need to change something relating to the API, this is where you need to go.

You can access it at: https://accounts.whatismybrowser.com/

Get your API Key

When you signed up with us, we automatically created an "Application" for you, which controls your API Key. To find that API key, simply click the Get your API Key link in the left column of the Accounts System. You will be taken to a page which shows you details about your application, including showing you your API Key.

Make a note of this API Key and keep it secret. It controls your access to the API. Anyone with a copy of it can access the API as you and use up your monthly quota.

Read the section on Authentication in this document for information about how to use this API Key.

Creating a new API Key

If your API Key is leaked, it will allow other people to perform API requests on your behalf.

If this happens, you need to generate a new API Key and stop using the old one.

To create a new API Key, click the big green button labeled Create new API Key below where your API Key is displayed in the Accounts System (follow the instructions above to get your API Key.

Monitor API usage

Keep an eye on your API account usage by looking at the Statistics Graph in the Accounts System.

To access it, click the Check API Usage link on the homepage of the Accounts system.

You can also visit the URL: https://accounts.whatismybrowser.com/buyer/stats

You will see a graph similar to the following one, showing your usage for the last month.

It will show you your usage for each API end-point seperately, including the number of hits per day. You can filter these end points by clicking the individual API Methods up the side, to toggle their display.

Change your API Plan

It is easy to change your API plan with us. Billing is calculated daily, on a pro rata basis, so if you change part-way through a month, you will be billed accordingly.

To change your API plan, log in to the Accounts System: https://accounts.whatismybrowser.com/.

The Accounts System Homepage

From the logged in Home Page, click the Change your plan link in the right-hand column to edit your Application.

Edit Your Application

This will take you to a page which will let you edit your Application. One of the things you can edit is the plan which you are on.

At the top of the page, you will see the API plan that your account is currently using. Click the red "Review/Change" link next to it to see its features and choose another plan.

Choose your new plan

You can explore the different plan levels by clicking on the different levels up the side of the window. You will see the different features available on each plan. When you've found the plan you want to switch to, click the green "Change Plan" button at the bottom of the pop-over. If you want to cancel changing plans, just close the pop-over by clicking the X in the top right hand corner.

Your new plan choice will be accepted and the pop-over window will close. Your account is now on the new plan and you have immediate access to its features.

API Versioning

We want to make it easy for you to track the continuing development of the API. Like most software, we maintain a version number of the API which makes it easy to tell when there have been additions or changes to the API.

The API Versioning scheme we use is as follows:

API Version number is for structure and functionality only

Note that these API version numbers only concern the structure and functionality of the API, they have no bearing on the User Agent Parsing or the Software Version Number reporting which are typically updated and expanded daily.

The user agent parsing and software versions are continually checked and updated, and when they are updated: they do not affect the version number of the API.

The version number of the API will only increase when there are changes or additions to the API itself.

API Version History

View the WhatIsMyBrowser.com API Version History.

Get help

We are dedicated to providing you with the best support we can for the API.

We provide a detailed API Specification, Sample Code, FAQ and the API Integration Guide you're reading now. If none of these can answer your problem, don't hesitate to get in touch with us; we're always happy to help.

You can send us a message via our Main Website's Contact Form.

Please include as much detail as possible with your message as possible, including the specific error messages/codes you receive. We will reply as quickly as we can. Most responses are within a few hours.

Common Elements of the API

Introduction

Each end-point of the API has a different objective, and so naturally they each accept different types of requests and provide different responses; however, there are a few elements which are common between them, so to save repeating ourselves, we describe them here.

Request and Response structure

The structure of URLs for the API is: https://api.whatismybrowser.com/api/v2/end-point

There are a number of different end points, depending on what you want the API to do for you. Refer to the individual sections of this guide for the end points you want to integrate with.

Request structure

The request structure varies by endpoint but the general idea is that if you're POST-ing something for us to process (eg. a user agent or batch of user agents), you'll send the POST body as valid JSON and we'll take it from there.

If it's a GET request, whatever you're "getting" from us will be somewhere in the URL.

Check the documentation for the end point in question.

Note that we also allow and fulfil OPTIONS requests - without affecting your API quota - so that Javascript based API requests work (many JS implementations send a pre-flight OPTIONS request which fails if we don't allow OPTIONS).

Response structure

Each end point will return data relevant to itself, but there will also always be a result dictionary containing the result of your request. This is where you look to see whether your request worked. If there was a problem you'll find a description of the problem here too.

For example:

In this example, you can see that the message and message_code are from the User Agent Parse end point, but there is the common code key which will be either success or error.

The message fields

The message and message_code fields in the API response's result key will give you more detail about how your request was handled.

Generally speaking, if your request was successful, they will be something relating to your end point (eg. "The user agent was parsed successfully."). If there was some kind of problem the message will tell you more about the problem (eg. "No user_agents key was provided in the request"; or it may also be a more general kind of error: "No X-API-KEY header provided in the request".)

Message and Message Code

Inside the result key, the message key will contain a human readable message which is constructed for developers to read and get a better understanding of your request result, as well as this the message_code is specifically built for your software to inspect.

For example, your code can look for and handle scenarios like a message_code being usage_limit_exceeded, and know to not send any more API requests until the next month.

Your code should never inspect the contents of message and make decisions based on it. Instead: your code should look at message_code.

While we're always very careful... a human readable message string can still theoretically change - perhaps a minor punctuation correction, or meaningful clarification...

However message_code is specifically built to never change, so if your code checks for certain values, you can be assured that it will always work the same way.

Common message_code values

The following table doesn't show all of the message codes which the API can return. Each endpoint has one or more message/message codes when your request was successful. Those endpoints will also have some "error" messages/messages codes specific to them as well. Make sure to read the documentation for those end points for more information.

Here is a list of the common error messages/message codes which the API may return. Similar to the "success" results, they will appear in the JSON result similar to this - for example:

Possible message_code when code is error

HTTP Status Codes

As well as returning result messages and codes, we also return meaningful HTTP Status Codes.

TLS Security

You can access the API via either the http or https protocol.

We recommend using https.

Authentication

Authenticating your API requests is done by sending a HTTP Header called: X-API-KEY with the value being your API Key which you got by following the Get your API Key instructions.

Here are some relevant snippits of sample code showing this to give you the idea.

Authentication example using Python & the Requests Module

Authentication example using PHP & the cURL Module

As per the HTTP RFC 2616, header field names are not case sensitive, so it doesn't matter if you send the header as X-API-KEY or x-api-key.

For examples in more programming languages, please look at our Sample Code.

Authentication Issues and Errors

Missing API Key

If you don't send the your API Key in the X-API-KEY HTTP header, you will receive a response like:

This can happen for a number of reasons, check out the section on Debugging Authentication Problems.

Invalid API Key

If you send an incorrect X-API-KEY, you will receive a response like:

Note that the API Key that you sent through is included in the result message; so that you can confirm that you are sending the key that you intend to.

This error can occur if you generate a new API key but don't update your code to send the new API key through.

If you're stuck, check out the section on Debugging Authentication Problems.

No access to end point

If you send a valid API Key but your account's plan does not have access to the specified end point, you will receive a response like:

You will get this kind of response if you do something like try to access the User Agent Batch Parser on the Basic plan.

If you want permission to access to the end point you're trying to use, you can upgrade your API Plan.

Usage Limit Exceeded

If you send a valid API key but your account has gone over it's monthly limit for this end point, you will receive a response like:

Note that end points are metered independently of each other; so you might have exceeded the limit of one end point but can still use other ones.

You can monitor your account usage in the Accounts System -> View API Usage.

We will send you warning emails when you are at 90% and 100% of your limits.

User Agent Parsing

Introduction

The User Agent Parse end point allows you to send a User Agent String and received a detailed response back, describing as much as we can tell you about it in individual fields.

The User Agent Parse end point is designed for parsing individual user agents, one at a time; if you need to parse a large batch of user agents then you should look at the User Agent Batch Parsing end point.

User Agent Parse - Request and Response

Making an API request to the User Agent Parse end point is quite straightforward.

Request

HTTP POST Body

To send a user agent string to be parsed, you simply need to put it in a JSON key named user_agent and POST it to the API.

Response

This is an example response (with line breaks to make it readable) containing all parse fields for the user agent given in the example request (above).

Parse Options

It's possible for you to specify options/settings for the way that user agents are parsed. To do this, include a dictionary of options values as a part of your request that will change how we parse it or return the response in certain circumstances.

To add parse options to your request, add another key containing a dictionary, along-side the user_agent key that you send in the JSON body. For example:

Parse Option: Allow servers to impersonate devices

Our parser was built from the beginning to be as accurate as possible; so for example, when a Crawler (Bot) comes along (GoogleBot for example), we report its hardware as being a server - this is because the bot is actually running on a server somewhere.

However, sometimes bots will add extra fragments to make it seem like the request is actually coming from a Mobile device, such as a Phone or Tablet. We realise that some customers would prefer that the hardware the server is impersonating be detected, instead of the fact that it's running on a server.

To cater for this scenario, we've added an option which lets you control how we detect the hardware for servers (including analysers, site monitors and so on)

By default, we would detect the hardware for a user agent like:

However, if you sent the same user agent with the setting enabled, eg:

the relevant parts of our response would be:

You can see that the hardware type/sub-type has been detected as "Mobile -> Phone", and the Operating System and Operating Platform show that it's an Apple iOS device.

The software will still be shown as GoogleBot, as this is what the agent is, but instead of appearing to be on a server, it gets detected as coming from a mobile device.

Notes:

• The idea behind this is that you send that setting with every request to the API... you don't want to try to send it only with the bots or anything (...because how would you know in the first place!) - the setting only has any effect if the hardware is a Server. It's perfectly fine to just send it with every request.
• If the user agent is for a bot that doesn't try to impersonate mobile hardware (eg. Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html), then it will be detected as running on a server as normal; this setting only has an effect when there's also the mobile-ish fragments as well (iPhone/Android/BlackBerry etc)
• This setting works for the User Agent Batch Parsing end point as well.

Parse Option: Don't sanitize user agents before parsing them

If for some reason you don't want us to sanitize the user agent you provide before we parse it, you can set the "dont_sanitize_before_parse": true in the parse_options to stop it. We don't recommend it, but the option is there for you if you want.

Field Definitions

This is a detailed description of the parts of a user agent parse response.

The JSON in a successful response will contain parse and result dictionaries. If you are on any of the paid plans (Standard, Pro or Enterprise) you will also get a version_check dictionary which contains information about whether their software is up to date or not.

parse key elements

These are the fields you will find in a user agent parse response under the parse key.

The availablility of some of the user agent parse fields depends on which API plan your account has access to. If you don't have access, they will not appear in the response. It is easy to change your API plan.

Notes on is_abusive, is_weird, is_restricted, is_spam

These fields are best attempts at warning you if there may be problems with the user agent that you sent to our API. We don't disclose the specifics around restricted words, fragments, and patterns to help prevent criminals from finding workarounds.

sanitization key elements

These are the fields you will find in a user agent parse response under the sanitization key.

We will always include a "sanitized" version of the user agent in the response. You are welcome to ignore it or do whatever you need with it (for example, compare what you submitted to what was returned to see if we have fixed a problem with it, or perhaps store it in your system instead of the raw, unprocessed user agent that was originally submitted).

Sanitizing before parsing

By default, for our paid customers we will sanitize the user agents you submit, before parsing them. We do this because encoding problems in user agents can impact and degrade the quality of the parse results (eg our parser may look for two words separated by a space, but if the space is instead %20 then the parsing won't work properly). If for some reason you don't want us to do this before we parse them, you can set the "dont_sanitize_before_parse": true in the parse_options to stop it. We don't recommend it, but the option is there for you if you want.

The sanitization key is available for paid plans (Standard, Pro or Enterprise). If you need access to it it is easy to change your API plan.

Notes on sanitization/preprocessing

Sometimes user agents are sent to the API which have some types of problems with them that we can fix; our sanitizer / preprocessor fixes as many issues as possible before we parse the user agent you sent us. It's available on any of the paid plans (and can optionally be turned off if you want).

You may not need to worry about this feature; however it's very handy if you need to sanitize/prepare user agents before storing them in your database. Things like GUIDs or encoding problems can cause massive issues with duplication in your database. We built this originally for ourselves; because we had issues with millions of "almost-duplicate" user agents in our database; separated only by unique GUID or "anonymizer" strings.

There are three major functions of the sanitizer:

1. Fixing encoding issues with user agents

   Sometimes user agents are encoded incorrectly when they are sent to the API.

   The main cause of this is that visitors are sending you user agents with encoding problems in the first place, but occasionally our customers have problems with their API code which isn't sending the requests to our API correctly.

   It will do things like convert:

   Mozilla/4.0+(compatible;+MSIE+6.0;+MS+Web+Services+Client+Protocol+2.0.50727.8940)

   In to:

   Mozilla/4.0 (compatible; MSIE 6.0; MS Web Services Client Protocol 2.0.50727.8940)

   Our preprocessor will these sorts of errors as best as possible.

2. Removing GUIDs and other unique fragments from User Agents

   Something else the user agent preprocessor does is remove as many unique/random fragments as possible. For example, many user agents have GUIDs in them.

   It will reduce user agents like:

   Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; CK={cR1Oj2P+w+Wd8PdQtvneboQ7bvsE7SbR+Wvzp1APzmHlfbUGLHQT02pcw3jtBivKIwIgjn4fcfNyTuoijSW7Y3JExTmP7Zr0})

   In to:

   Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; CK={})

3. Removing weird encoded fragments

   The sanitizer will also remove weird fragments that look like some kind of encoding, changing a user agent like:

   Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.224 Safari/537.36 ijkypxh+p7TNu736xudKvZSwjSo=

   to:

   Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.224 Safari/537.36

   We have dozens of different fixes for a wide variety of different unique strings we see in user agents.

4. Removing date stamps

   We've seen lots of user agents with a variety of datestamps in them, presumably added at the time the request was made. The sanitizer will attempt to remove those fragments.

5. Fixing general problems with user agents

   There's a third class of functionality that the preprocessor provides, and that's removing general, miscellaneous issues with user agents. For example, we've seen misbehaving user agent changing plugins accidentally wrapping user agents with quotation marks which again clog up your logs and database with "almost-duplicate" user agents. We'll automatically fix issues like this for you using the preprocessor.

These fixes work together, so that a user agent like this:

Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.224 Safari/537.36 ijkypxh+p7TNu736xudKvZSwjSo= 2014-05-16T17:21:22.531Z

which is a user agent that our systems saw in the wild, is neatly reduced to:

Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.224 Safari/537.36

which allows it to be neatly grouped together with other user agents of the same kind, if so desired.

version_check key elements

These are the fields you will find in a user agent parse response under the version_check key.

The version_check key is available for paid plans (Standard, Pro or Enterprise). If you need access to it it is easy to change your API plan.

Notes on Version Checking

Chrome version checks

When we perform "up to date" checks on Chrome user agents, by comparing the version number in the user agent to what we have on record as being the latest version number of Chrome, we compare just the first three version number fragments.

For example: we perform the version number comparison on 91.0.4472 instead of 91.0.4472.164.

The reason for this is that we have found that occasionally the version data from various online sources that we extract version numbers from for Chrome from is slightly different to what a completely up to date version of the Chrome browser itself reports as the latest version.

The difference is always in that fourth and final version fragment of the Chrome version number.

In other words, a fully up to date copy of Chrome might have a version number that the very last version fragment is behind what we have been told is the latest version number of Chrome. On the occasions that this happens, it results in an incorrect warning that the copy of Chrome is out of date.

Experimentation has shown that we actually get more accurate "version checks" by comparing just the first three version fragments instead of all four (as there are no longer false positives).

Notes on hours_released_ago

Some software packages (eg Chrome) don't release the latest version of their browser in all regions of the world all, at the one time. It can take many hours to complete a global distribution of the latest version.

As such, for some users in some regions, they may no longer technically have the very latest version of their browser, but their auto-update tool isn't able to download the latest version yet. This can be confusing if you tell them that they're out of date when their browser thinks that it isn't out of date...

The hours_released_ago field makes it easy to add a slight delay to the "please update your browser" message that you may show your users.

You might have a bit of code that does something like:

We include this as an integer value in the API response to make it very easy for you to determine how long ago the latest version was released and if you want to show the message to your users.

The value will reset each time a new version of that software is released.

result key elements

Remember: there are some message_code values which are common to all end points (eg api_authentication_invalid) - Read more.

The following tables describe message_code values which are unique to the User Agent Parse end point.

Possible message_code when code is success

Possible message_code when code is error

Caching the API Response

You are welcome (and even encouraged!) to implement a relatively short cache between your server and the API. This can help minimize parse times on your end for popular browsers and bots. If you get thousands of people using the exact same version of Chrome and Operating system - all with the exact same user agent, it makes sense to minimize youre quota use and increase the parse speed by caching our API result for a few hours.

Our version check info updates every three hours, so you might consider caching results for three hours.

User Agent Batch Parsing

Introduction

The original User Agent Parse end point was created for parsing individual user agents and returning a response very quickly. But if you've got a large batch of user agents stored in a database or set of log files and don't mind too much about how long it takes to process, it makes much more sense to send those user agents through in a large batch instead of making a different HTTP request for each user agent. This is where the user agent batch parsing end point comes in handy.

The maximum batch size is 500 user agents per request.

User Agent Parse Batch - Request and Response

Making an API request to the User Agent Parse Batch end point is quite straightforward.

Request

HTTP POST Body

It doesn't matter what the individual keys of user_agents are, as long as they are unique to your HTTP request (it also doesn't matter if you reuse keys in different requests - each request is independent of other requests). If your batch of user agents is coming from a database, you might use the primary key for each user agent. As per the JSON specification, dictionaries can't be relied on to have a certain ordering - so you can't assume that the tenth parse result will correspond with the tenth user agent you sent through, and thus the unique key is necessary for you to be able to match user agent parse results back to what you sent through.

If you have no need to match them back to an original record (eg. to update a database) and instead are just making a report about each of your user agents, you can just start with an arbitary number and increment it for each one you send through - and then disregard it in the response and just loop over each result in parses.

Response

This is an example response (with line breaks to make it readable) for the user agent batch given in the example request (above).

Parse Options

The User Agent Parse Batch end point has the same options as the standard User Agent Parse end point.

Please refer to Parse Options for the User Agent Parse end point and use them in the same way.

Field Definitions

This is a detailed description of the parts of a user agent parse batch response.

The JSON in a successful response will contain parses, parse_stats and result dictionaries.

parses key elements

The parses element is a dictionary - the keys are the unique keys you sent through in your user_agents dictionary. The contents of each parses element follow exactly the same rules as an individual user agent parse request. Each element will have it's own result key, just like an individual parse response, and if your account has access to version checking (ie. It's on a Standard, Pro or Enterprise plan), you will also get sanitization and version_check dictionaries.

Go through each user agent in parses and match it's key with whatever system you used to create the keys with in the first place - perhaps database "primary keys".

parse_stats key elements

To give you some summary information about your batch request, parse_stats contains a summary of the batch which was just processed.

result key elements

Remember: there are some message_code values which are common to all end points (eg api_authentication_invalid) - Read more.

The following tables describe message_code values which are unique to the User Agent Parse Batch end point.

Possible message_code when code is success

Possible message_code when code is error

Software Version Numbers

Introduction

The Software Version Numbers end point lets you get the latest version numbers of popular web browsers, operating systems and browser plugins via an API.

Version data also includes sample User Agents

The responses from this API end point also include some sample user agents for the browsing software in question. For example, when you look at Chrome's version data in the API response, you'll also see a series of user agents for Chrome on the various operating systems it runs on (Windows, macOS, Linux, iOS, Android). This can be very helpful if you need to impersonate those browsers when testing your systems. You don't have to use the user agents if you don't need them, but they're there if you do.

We also include sample user agents for the various Operating System version numbers we provide; there are some sample user agents for many of the popular web browsers for those operating systems: for example, if you look at the sample user Agents for Windows 10, we've got Chrome on Windows 10, Firefox on Windows 10, Edge on Windows 10 and Internet Explorer on Windows 10 user agents.

Software Version Numbers - Request and Response

Making an API request to the Software Version Numbers end point is quite straightforward.

Request

URL element - software_name_code

You can use different values for the software_name_code URL element depending on what you need to do.

The "standard" or "default" thing to do would be to set it to all, so that you get all the version numbers we provide - you can then process the response extracting some or all of the software version numbers you need.

End point URL - requesting all version numbers:

Even if you were only interested in the latest version numbers for Chrome and Firefox, it would still make sense to request all version numbers, and then just look for those two elements in the response. Doing it this way requires one HTTP request and one quota hit, instead of two HTTP requests and two quota hits.

If you really require version numbers for just one software package, you can request it like this:

End point URL - requesting version numbers for just one software package:

Instead of putting all in the url, use a the software name code that you want version data for. For example, requesting version data for chrome:

The software name codes you can specifically request version data for are:

• chrome
• firefox
• firefox-esr
• edge
• internet-explorer
• safari
• opera
• vivaldi
• yandex-browser
• flash
• java

Response

As discussed, you can either request version data for "all" software packages, or version data for just one specific software package by changing your request URL.

What you request will determine what is returned in the response.

Requesting version numbers for all software

You would send your request to the URL:

And the response would have this structure:

Requesting version numbers for a specific software name code

This is an example response (with line breaks to make it readable) for requesting version numbers for just iOS.

You would send your request to the URL:

And the response would have this structure:

You can see that it shows you the latest version of iOS in the latest_version list, and then also has a sample_user_agents dictionary, where it groups one or more sample user agents for each software name code. Note that the version number given for each is also the latest version: so in the Chrome section, you get a user agent for the latest version of Chrome on the latest version of Macos.

These are done as lists, so if there was more than one variant, then the different variants would appear in the list for that software name code.

Field Definitions

This is a detailed description of the parts of a software version numbers response.

The JSON in a successful response will contain version_data and result dictionaries.

version_data key elements

Each key in the version_data dictionary corresponds to a different software package, and contains the software version number/s for it.

If you send a request for "all, the keys which will exist under version_data are:

• chrome
• firefox
• firefox-esr
• edge
• internet-explorer
• safari
• opera
• vivaldi
• yandex-browser
• flash
• java

Each one of these "software name codes" then contains one or more "streams". For example, we provide version data for the latest version of chrome for five streams: windows, macos, linux, android and ios.

Elements for each stream in a software_name_code key

latest_version is the only element guaranteed to be present; all other fields will appear depending on the individual software package.

result key elements

Remember: there are some message_code values which are common to all end points (eg api_authentication_invalid) - Read more.

Possible message_code when code is success

Possible message_code when code is error

User Agent Database Dump URL

Introduction

Our systems get sent a huge variety of user agents over the normal course of their operation; we collect millions of user agents from the homepage of whatismybrowser.com and the user agent parsing API itself. We collect and organise those millions of user agents to help us develop the user agent parser, as well as to provide our big user agent listing.

We also make weekly database dumps of this these user agents - each with with the results of our user agent parser for each user agent - and we make it available for you to download: customers on Pro or Enterprise plans can make a simple API request and receive the URL for the latest database dump of user agents. You can then load them into your systems to help you do research or develop your own product or system.

Search the database instead of downloading it

As we continue to add more and more user agents into our database, it admittedly becomes more and more unweildy to use. Our database now has hundreds of millions of user agents in it and the filesize is many gigabytes. This can be a bit much for some users who want to just do some basic user agent queries.

So, we've launched a user agent database search API end point. Instead of having to download and import hundreds of millions of records each week, you can just send some simple API requests and get all the user agent information you need. Check it out to see if it will make your life easier.

Don't need to automate your database downloads? Use our web-based GUI instead.

If you don't need to automate your downloads of this database and prefer to manually download a database dump yourself, please have a look at our handy frontend for getting the same downloads. It will make the API request for you and show you the download links immediately.

If you have an API key for a Pro or Enterprise plan, you can download a copy right now.

User Agent Database Dump URL - Request and Response

Making an API request to get the latest User Agent Database Dump URL is quite straightforward. Simply make a GET request with the Auth Key header and a file_format url parameter and you'll get a JSON response that gives you the URL of the dump to download as well as some helpful meta data.

As of version 2.4.8, we now default to offering a "delta" of the database each week. Each one of these contains only the new user agents since the last extract, in order to keep the size smaller and the data quicker to handle.

Request

Sample CURL command

Here's a sample curl command that demonstrates a request:

A request to this API Endpoint will return the latest database dump (whether the latest extract is a "full" dump or a "delta").

Easy to use Web Interface

We've got a simple web user interface for making these requests if you'd prefer that:

Web UI for downloading the database via the API

Please have a look at it and make sure to to inspect the page source; it's got some basic Javascript which makes the request for you; feel free to copy it and use it in your own system if you need.

Delta and Full database extracts

When we first started sharing database extracts in 2018, there was only about 500,000 records, and this was a very manageable amount of data to handle. In the years since then, the size of the database has grown incredibly, now several hundreds of millions of records, and it's at the point where the size of it is now causing issues for a lot of our customers, as well as introducing a lot of wasted bandwidth, space, and energy to work with.

There is also just so much data in there that isn't used by a majority of customers, that we've made the decision to start releasing "deltas" of the database each week, instead of dumping hundreds of millions of records each time.

This will allow those customers who just need "the latest user agents" to get them each week without the overhead of a lot of very old user agents that they don't need. It also increases the load time significantly for everyone who is downloading and importing them.

Customers who just need "the latest user agents" and who don't need very old ones can download and import the database deltas each week, and choose to purge their systems after whatever time period suits them.

Customers who want an ever expanding collection of user agents - new and old - can simply keep loading the deltas on top of their existing database.

You can control the types of dump URLs that the database returns by specifying the dump_type URL parameter. If you don't specify anything, you will receive the latest dump each week, whether it is a full one or a delta.

The database is now size limited

To combat the fact that the database continues to grow in size, and was getting close to half a billion records, we now limit the size of the database.

We will continue to dump the weekly "deltas" as normal. There is no real difference to users of the database download feature, except: that depending on how you use the database dumps, there may end up being duplicate user agents in your database.

Our database will never have duplicates in it; but the issue could arise if you combined the individual dumps that we provide, over time.

This can happen if a user agent is added to our database, you download a dump containing it and load it in to your system. Some time later, we remove that user agent from our database because it's old. But then later; the same user agent is re-added to the database. Because it no longer existed in our dataset, it will be added as a new record (with a new database ID). Then, it will be soon exported in our next database dump. When your system downloads that latest database delta, it will try to load the same user agent which is now in a new record on top of your data. This may cause problems for you.

Our MySQL database dumps use the INSERT IGNORE statement to help minimize issues with this; the new, duplicate data won't be loaded.

This also means that the times_seen and first_seen_at values are no longer "for all time"; they are just for as long as a user agent has been in the database.

HTTP GET Parameters

file_format - the format of the large database dump:

or:

or:

or:

We provide the database dumps in MySQL, CSV, Parquet, and Plain Text formats. The MySQL, CSV, and Parquet files also contain the various parse fields, the Plain Text version contains just the user agents.

dump_type - the type of the database dump:

You can optionally specify the dump_type parameter; it can be either full or delta. If you do this, the API will return the URL of the latest dump of that type. If you don't specify it, it will return the latest URL, whether it is a full or a delta extract.

The most common scenario is that you would not specify the dump_type parameter and instead just keep loading the data regardless if it was a full or a delta.

If for some reason you only want to handle "full" extracts and not use the "deltas", you would specify to only receive "full" dumps. We will only be generating full dumps every few months; the rest of the time, only delta extracts will be provided.

Same format/structure

The files are structured the same way, the only difference is that they contain less data data.

Deltas don't include updated meta data or parse data for older user agents

The deltas only contain new records; they don't update the various meta data fields, such as times_seen, first_seen_at, last_seen_at, and so on.

The API response includes the type

The API response JSON includes an indication of the "type" of dump that is being provided (in the dump_type field. This lets you easily determine the type of the dump in case you need to handle the different types differently in your system.

Example url for accessing only full extracts:

Response

The response format is the same regardless of which file format you have requested.

For example, the request to the URL:

would have a response similar to:

Field Definitions

This is a detailed description of the parts of a User Agent Database Dump URL response.

The JSON in a successful response will contain the user_agent_database_dump dictionary.

user_agent_database_dump key elements

result key elements

Remember: there are some message_code values which are common to all end points (eg api_authentication_invalid) - Read more.

Possible message_code when code is success

Possible message_code when code is error

The database dumps

We provide copies of our user agent database dumps in MySQL, CSV, Parquet and Plain Text formats. We are considering other formats, so please let us know if this would help you.

Fields

A quick glance at the actual contents of a database dump will make it instantly clear the format of the data we provide.

However to be explicit about it: we provide a id column which is the same as our database's primary key. This means that if/when you load in new user agents from a new database dump from us, you can know that the id's of the new dump match the existing ones and you can choose to update them or so on.

As we further develop our user agent parsing library, the values in some or all of the parse fields may change over time. We have a bot which faithfully works it's way through our database reparsing each of the user agents using the latest copy of our parser.

We also then provide the user_agent column, which contains a user agent string.

The other columns include the number of times that user agent has been seen, the first and last times the user agent has been seen by our systems, as well as the fields from the output of our user agent parser. This saves you having to reparse the user agents yourself and instead very easily run queries against them or group them how you would like to.

Note that other than the PRIMARY KEY index there are no other indexes in the "create" sql we provide. We highly recommend adding your own database indexes based on the sorts of queries you will be running.

Sanitization

We often see obviously "fake" user agents; either random strings of garbage, obscenities or "silly" messages. We've given a lot of attention to removing these bogus user agents from our dumps. We don't guarantee that the database is perfect but we've done our best. If you notice any user agents in the database which you don't think should be included, please let us know the id of it and we'll have a look.

Automating your integration

This API end point and data dumps have been specifically built to make it easy to automate loading these user agents into your own system.

In regards to the MySQL database dumps: The .tar.gz file contains two seperate SQL scripts: one to create a table which will accomodate the user agent data, and another (much larger) script which contains the actual user agent data. It is assumed that the most common work flow of our customers is to create the table once and then regularly import new user agents from the latest data base dump file.

For this reason, we took care to make sure that the CREATE table query was in a separate file to the INSERT queries. This lets you very easily and quickly add the new data to the existing table which you may have. This also helps if you have added your own extra fields to that table; you don't need to recreate them as well, the new INSERT queries should just go nicely on top. Further to this we have also made sure the "insert" script actually uses INSERT IGNORE INTO statements which will add new rows but not fail if there is already an existing row which matches.

While the actual file you download from our CDN will have an unpredictable datetime stamp and a random fragment to obsfucate the URL, once you have downloaded and extracted the file, the filenames inside will always be the same: create-table-whatismybrowser_useragent.sql and whatismybrowser-user-agent-database.sql. Your automation scripts can rely on those two files existing.

If you have any problems with automating the handling of these database dumps; please let us know via the Contact form; we are keen to maintain a system that makes it easy for you to use.

User Agent Database Troubleshooting

We have a User Agent Database FAQ for further help on working with and resolving problems with using the User Agent Database extracts.

User Agent Database Search

Introduction

In the beginning was the database download...

Since the start of 2018, we've made our database of hundreds of millions of user agents available to our Pro and Enterprise customers to download. You can download the entire database and import it in to your system and do all sorts of searches and queries on it...

However, as we continue to add more and more user agents to it, it keeps getting bigger and bigger, and thus more and more time consuming for you to use: you need more storage space, more processing time and lets be frank, unless you're doing advanced data analysis on it, it's probably over-kill for your needs.

So, instead of downloading and importing the entire database each week, our Pro and Enterprise customers can perform searches via our API on the database. This means you no longer have to download and import the database each week; you can simply search it right now and always have the most up to date data.

Things you can use search for

One of the most common uses of it is when our customers need frequently updated lists of new user agents: they want to always have a list of 50 of the newest and most common Firefox or Chrome user agents. Or they want to easily be able to find user agents for a particular platform in order to test a system they're developing.

You can search our User Agent Database with any combination of fields (Software Name, Operating System, Device type etc), specify results ordering, limits and so on to get the types of results you want.

The search API is perfect for when you need to find things like:

• Safari user agents on iPhone that have been seen more than 10,000 times
• The most popular Firefox user agents on computers
• Chrome user agents between version 59 and 64
• All Firefox 70 user agents across all operating systems and device types
• Samsung mobile (phone & tablet etc) device user agents
• The most popular ebook user agents
• The oldest car-based web browser
• The most recent Chrome on Android user agents
• 200 of the most recent user agents that have been seen more than 100 times
• All user agents for Galaxy Note devices

And all sorts of other combinations...

Try it out right now

We have a easy to use Database Search UI which gives you an easy to use form to query the database. It's great for experimenting and prototyping with and seeing what the database search provides. Once you've figured out the queries you might want to regularly run, you can then use those parameters in your code.

Note: The database is now size limited

Please note, due to the ever increasing size of the database, we have made the decision to start limiting the size of the database. This shouldn't affect searches for relatively new user agents, but older user agents will no longer appear in the data. To see historical user agent data, you will need to download the various database dumps and search through them on your own system.

User Agent Database Search - Request and Response

Request

Notes on the HTTP Get Parameters

• Combining parameters: As with normal GET parameters, you can combine multiple URL parameters to get the precise search you want - for example software_name=Firefox&software_version=65 would give you Firefox user agents for version 65
• Weird parameter searches - It's possible to do things like search for just version 10 without specifying the software_name. This would return user agents for various software all with the version number of 10 - eg Firefox 10, Internet Explorer 10, Chrome 10 and so on... It's a bit weird and there's probably not many scenarios you would want to do this in, but we won't stop it from working for you!
• Impossible combinations: Some combinations will never return results; for example if you search for operating_system_name=macOS&operating_system_version=Vista you won't find any versions of macOS Vista! You also won't find Safari browsers on Android and so on... Another scenario would be if you did something like search for the specific software version (eg version 50) but then also specify a software_version_min and software_version_max range of 60 -> 70: you won't get any results! There's no problem if you do search like this, but there won't be any results.
• Encode URL Parameters: As with normal GET parameters, you need to encode the search parameters to prevent issues with your searches. In particular, any spaces in the various parameters (eg Software Name, Order By etc) should be converted into + symbols. Another main one to watch for is encoding actual + symbols which you want to use in your search. For example, if you wanted to search for user agents with an operating_platform for Galaxy Grand Neo+ values, you need to encode and send that parameter as operating_platform=Galaxy+Grand+Neo%2B. Notice that the spaces have been converted to + symbols, and the actual + symbol in the parameter value has been encoded as %2B. If you use any sort of HTTP request library in your software it will probably take care of this for you.
• The ordering of the parameters in the URL doesn't matter.

Remember, these are just standard HTTP GET parameters, so when you use and combine them, the URL will look something like this:

Notice that after the API End Point fragment: user_agent_database_search, there is a ? (a question mark) to indicate that one or more GET parameters follow, and then each following parameter is separated by an ampersand: & character to denote the end of the value and the start of the next key.

Example searches

Here are some example combinations of search requests:

Response

What follows is a sample search response for a search for up to 100 Safari user agents on macOS which have been seen at least 50 times, ordered by the first time we saw the user agents.

The full search URL for such a search request would be:

This example search request will respond with a result similar to the following one (which contains line breaks to make it readable). The full response would normally contain 100 user agents but we have only shown the contents of two of them, and in both instances also snipped the full parse dicts to make the response more readable - the emphasis here is on the whole structure of the response. Each parse dict will have the same keys as those found in a normal parse API response.

Weird/Restricted/Spam/Abusive flags are not included in search results

When you access the search end point, you are accessing the database of user agents. This database only consists of user agents that we have already decided aren't "flagged" in some way - for being weird, dangerous, spammy, or containing a "restricted" word.

The because search results will never contain user agents like that, we don't include the various is_weird, is_spam, etc fields. Of course, when you send a user agent to be parsed, the response there will include those fields, but when you're searching the database, it doesn't need to return them, so it won't.

Version check information is not included in results

Note that version check information is not included in search results; if you want to check if a specific user agent is considered up to date then send a user agent parse API request.

Field Definitions

This is a detailed description of the parts of a user agent database search response.

The JSON in a successful response will contain search_results and result dictionaries.

search_results key elements

The search_results dictionary contains two keys: user_agents and search_meta_data.

user_agents

The user_agents element is a list of 0 or more user agents which matched your search criteria. Each item in the list is a standard "parse" dictionary in the same format as you get from the User Agent Parse API End Point: there are the standard fields like: simple_software_string, software_type, software_version_full, and so on.

search_meta_data

This is a small but handy dictionary which provides some meta data about the search you just performed. It holds:

• num_of_results_returned: The number of results in the user_agents list
• search_took_milliseconds: How many milliseconds it took to actually query our database
• search_parameters: A dict showing how we interpreted your search request. The elements in this dict should match what you sent through. It helps you confirm that we interpreted your search the way you were expecting. If you don't see something you intended to search for here then you may not be sending it correctly.

result key elements

Remember: there are some message_code values which are common to all end points (eg api_authentication_invalid) - Read more.

Possible message_code when code is success

Possible message_code when code is error

Search Limitations

The user agent database search is a new API end point and while it's not considered a "beta" release, there are a few things which we haven't built into it (yet?). We are considering these additional capabilities and may one day add them. We wanted to discuss them briefly to let you know that we are considering them and welcome your thoughts on them.

Pagination

Currently search results are not paginated; you can request up to 500 results.

Boolean/advanced search

Currently search is limited to searching for one value per field at once (eg you can't search for "Chrome or Firefox" in the one request), and doesn't include "not" or "or" operators (eg you can't search for "Chrome on mobile but not android or iOS").

If you really require these kinds of search capabilities you may be able to approximate them by making several search requests and then merging/excluding the results. Another (and probably better) alternative is to actually download the entire database and perform the advanced SQL queries in your own system.

Search speed considerations

Our database of user agents makes heavy use of column indexes and multi-column (composite) indexes to help provide search results as quickly as possible.

We monitor all search times to find outliers and situations where we may need to add additional multi-column indexes to help improve search requests. Most search requests should take a maximum of a few seconds to complete, depending on their complexity and the number of results returned.

If you find a particular search query is taking more than a few seconds, rest assured that we will notice and do our best to optimise our code and database to help. If you continue to have problems with speed, then don't hesitate to get in touch and let us know. We'd be happy to provide feedback on our progress.

Debugging

Introduction

Have you run into a problem? Something not working the way you were expecting? Here are some tips to get you on the right track.

If there's anything you think is missing here, or if you need further help, refer to our Get Help and we'll sort you out!

Debugging Authentication Problems

The two message_code errors relating to authentication which can occur are: missing_api_authentication and api_authentication_invalid.

• missing_api_authentication
  

  This happens when - for some reason - our API servers don't see the X-API-KEY HTTP Header in your request.

  Common reasons for this are:

  • The header is misspelled in your request
  • Your code isn't sending it properly (it's not actually putting it in the request)
  • Your server is behind some kind of proxy/gateway which is stripping that header out

• api_authentication_invalid
  

  This happens when the API key you send in the HTTP Header is incorrect.

  Common reasons for this are:

  • You created a new API Key but are still sending the old one
  • You are accidentally sending a wrong value

A good way of checking to see exactly what your system is sending in its API requests is a handy website called RequestBin. Read our section on Debugging using RequestBin for instructions on how to use it.

Debugging JSON Problems

There are two main classes of JSON problems that you may encounter when using the API:

• Sending requests containing invalid JSON
• Sending JSON with an incorrect structure

Requests containing invalid JSON

These kinds of errors - where the API returns a result -> message_code of invalid_json - occur mainly when developers try to construct the JSON themselves by hand - as opposed to using whatever JSON library their programming language provides to do the heavy-lifting for you.

For example, hand-crafting JSON in python (don't do this!):

In the fourth line of the example above, you can see the actual JSON string being constructed by hand: '{"user_agent": "%s"}' % user_agent.

That example does actually work; but it's very prone to problems.

You become responsible for getting the JSON format perfect; if you miss a semi-colon:

you'll get:

This isn't likely to happen on simple examples, but when you start to get into the batch processing requests and other more complicated requests, problems become more likely. Since all modern languages provide some kind of in-built JSON library, you should just take advantage of it and make your own life easier.

From a security/integrity perspective, it's also a bad idea to roll your own JSON strings. The "hand made" example above is vulnerable to injection issues (what if the user agent had a " in it? It would break your JSON.) And so you have to start to worry about escaping values... and suddenly things just got a lot more complicated for you.

Instead, (in the case of Python), you should use the inbuilt json module, which provides all of these niceties, making it much, much easier for you to generate JSON that won't be syntactically wrong (and which is also automatically escaped, etc).

For example, properly creating JSON in python:

On line 5, a normal Python dictionary is created, using "user_agent" as the only key. Then on the last line, where the request is sent, json.dumps() is used to automatically convert that python dictionary into a JSON dictionary, where escaping and other things are safely considered.

If you use your language's inbuilt JSON functions, you are much more likely to prevent invalid_json errors.

Incorrect JSON structure

Sending the wrong JSON structure in your request will result in errors like:

This is occuring because the JSON structure didn't look like:

Maybe "user_agents" was misspelled:

and so we couldn't find it in your request.

Maybe it was nested under something else by mistake:

And so, while both of those examples are syntactically correct JSON, they will result in a no_user_agent message_code because we couldn't find user_agent where it was supposed to be.

If you get an error like this, make sure that you are sending the JSON with the correct structure.

You can use RequestBin and look at the POST BODY section to see what you've sent through. You can also use a JSON validator to ensure that what you're sending is valid JSON and conforms to the structure we expect.

Debugging API requests with RequestBin

A great tool for debugging problems with the API is a website called RequestBin. It lets you send any kind of HTTP request to your own special location on their site, where they then give you a detailed read-out of exactly what you sent; including headers, parameters and request body. This shows you exactly what your server is transmitting (or not transmitting) and it can be an invaluable tool in locating problems.

1. Create a RequestBin:

1. Visit their homepage: https://requestbin.com/
2. Complete the Captcha
3. We recommend you tick the Private (only viewable from this browser) checkbox
4. Click the green Create a RequestBin button.

2. Use your RequestBin:

In the code that you're debugging; change the request URL from https://api.whatismybrowser.com/api/v2/... to the url at the top of your RequestBin page (eg. https://requestbin.com/abcd1234 ).

So now, when you run your code, instead of sending the request to the WhatIsMyBrowser.com API servers, it sends that request to your unique RequestBin URL.

RequestBin will now be expecting your request, so when you execute your code, it captures the request and shows you exactly what you sent.

3. Inspect your RequestBin

After you've triggered your code to send its request to the RequestBin you've just created, press Refresh in your browser to reload the "inspect" page for your RequestBin. You should see a read-out showing information about what you just sent.

If you send more than one request to the same RequestBin, additional requests are added to the top of the page, one after the other.

Debugging Authentication problems using RequestBin

Here are some screenshots of parse_user_agent requests sent through RequestBin with different sorts of authentication problems.

Missing X-API-KEY
This screenshot shows a scenario where the X-API-KEY wasn't sent to the server. Note that you can't see it anywhere in the list of headers.

This generates a missing_api_authentication message code when it is sent to our server.

If you are getting missing_api_authentication errors from the API; send a request to your RequestBin and if it is similar to this one - missing a X-API-KEY header - then something is definitely wrong with your request. Confirm that nothing is stripping out that header before it reaches us (switch to the https protocol to help prevent this), make sure your code is actually setting the header on your request, and make sure that you haven't misspelled the header name (remember, capitalisation of the header name doesn't matter).

Incorrect X-API-KEY
This screenshot shows a scenario where the X-API-KEY was sent to the server but is wrong. It appears in the list of headers but it's the QWERTYIOPSDFJLKJ clearly an incorrect key (copied and pasted from an example at the start of this guide!)

This generates a api_authentication_invalid message code when it is sent to our server.

If you are getting api_authentication_invalid errors from the API; send a request to your RequestBin and inspect the result. Does your X-API-KEY header have the wrong key in it by mistake? Compare it with your key in the Accounts System. Have you created a new API key but are still sending the old one by mistake? Is the key being truncated somehow?

In both requests, you can also see the "RAW BODY" of the HTTP POST request at the bottom; it contains the valid JSON that our test script generated and sent to the server.

Debugging JSON problems using RequestBin

When you send your requests to RequestBin, you will see the Raw HTTP POST Body displayed at the bottom of the read-out in green.

Invalid JSON
This screenshot of a RequestBin shows a scenario where invalid JSON was sent.

This generates a invalid_json message code when it is sent to our server. Please notice the missing colon between the user_agent key and the user agent string which is causing this error.

If the problem with your JSON is not immediately apparent to you, you can copy and paste the Raw HTTP Body into a JSON Validator tool, which will validate and format it to be readable.

If your JSON has a syntax error, the validator will indicate where it thinks the problem is. This example is telling you that it expects a colon, not a string.

If you're still stuck, you are always welcome to contact us and we'll see if we can spot the problem for you.

Conclusion

Introduction

This is the end of the API Integration Guide. We hope you've found it useful.

Hopefully by this point, your system is hooked up to the API and working without any problems.

If you're having any issues, don't hesitate to contact us to get further help. We're always willing to give you whatever we can to get you going.

Feedback

We are very focused on providing a high quality product and excellent documentation. If there's anything you think is wrong or missing from the documentation, or from the API itself, then please let us know about it. We're always looking for feedback on what we're doing. Good or bad - let us know.

Testimonials

We love it when our customers love our API, and if you'd like to share how the API has made your job easier, or how easy it was to get connected then we'd love to feature you in our testimonials section.

Even if you just want your logo to be included in the "This API is used by..." section, let us know!

References

API Specification

We use Swagger UI to provide an interactive API Specification.

Sample Code

We provide sample code for a number of popular programming languages, to give you examples on how to get started.

Support

In addition to the sample code and this Integration Guide, we have a support section which can give you further help.

Accounts System

Any time you need to discover or change something about your API account with us, head to our Accounts System: https://accounts.whatismybrowser.com/

There you can:

• Change your billing details
• Upgrade/Downgrade your API plan
• Cancel your API plan
• Get and change your API key
• Monitor your monthly API usage
• Contact us with questions or suggestions

Back to the main API page