In October 2022 we launched Version 3 of the WhatIsMyBrowser.com API. This document outlines the reasons for the new version, the changes, and how you need to modify your system's code to work with the new version.
There have been some big changes recently in the world of web browsers, relating to the way browsers can be identified. Until recently, you could identify the browser, OS, device, (etc) that someone was using, simply by sending your visitor's User Agent String to the API.
However, with the introduction of Client Hints to Chromium-based browsers, and with a number of web browsers minimizing or "freezing" the information in their user agent strings, accurate browser detection now relies on more than just analysing User Agents.
With the switch to using more than just User Agents to perform browser detection, we made the decision to leave User Agent Parsing in Version 2, and create Version 3 which takes a broader and more future proof approach to browser detection.
The new Version 3 of the API looks at all the HTTP Header values (focusing on both the User Agent and Client Hints headers) from your site visitors to more accurately detect what your visitors are using.
It's still very common for bots and scripts to impersonate real traffic and browsers just by faking their user agent header; or for a user to change their user agent string in their browser. But since we're looking at all their headers, unless they've taken extra special care to fake all of their HTTP headers, we'll be able to identify the discrepancies between what their headers are and should be.
User Agents aren't going away any time soon though, and Version 2 will continue to exist and be operational for all your User Agent related needs. Parsing, Batch Parsing, and Downloading or Searching the Database of User Agent strings will all remain operational, but won't be included in Version 3.
A significant part of the new Version 3 of the API still relies on parsing User Agents, so the User Agent Parsing features of Version 2 will still continue to be developed and maintained. In other words, even as we work on the new, all encompasing Version 3 Browser Detection, it will also further improve the user agent parser too.
This is for customers who use the API to detect the browsers, operating systems, devices, hardware, and so on that your visitors are using: you are encouraged to follow this guide to switch to Version 3.
If you really do need to just parse user agents or work with the database of user agents, then you can certainly keep using the older Version 2 end points.
The following API end points were in Version 2, but aren't in Version 3. They remain operational, so if you need to, you can still keep using them.
The API User Agent Parse end point has been retired and replaced by Version 3's "Detect" end point.
If you still have a use-case for decoding user agent strings then you can still keep calling the User Agent Parse end point with those user agents - We will keep developing the user agent parser library and new detection will continue to be added for it, but for general "browser detection" you should be looking to the new Version 3 "Detect" API End point for all your browser detection needs.
For much the same reasons that we are retiring the Parse end point, we are also retiring the User Agent Batch Parsing end point.
And in the same way too; if you still have a database or log file of user agents you need to decode, then you can still always access the Version 2 batch parse end point with them, but there won't be something like this in the new version of the API.
As discussed, user agent strings - by themselves - are being left in the past, and so the user agent string database is going to be less and less useful. Since everything related to User Agents is staying in Version 2, it's only fitting that the database downloads and search remain here too; the database won't be available in Version 3; if you still need to search or download it, use the Version 2 end points.
There are a few things that need to change on your end to switch to Version 3. None of these are big departures from the way that Version 2 did things. In short you will need to:
Lets go over these in detail:
Browsers will normally only send a fraction of the Client Hints headers that they're capable of sending, unless your server requests that they send them all. You need to modify the HTTP headers in your Server Responses to include two new headers: accept-ch and critical-ch.
Rather than repeating ourselves, you can find the full values for those headers in the Integration Guide on the Detect Requests page.
Version 3 of the API no longer uses just the User Agent header, it works best when you send all the HTTP headers from your visitors to it. This helps us identify people and bots visiting your site who are faking their user agents.
The API response in Version 3 is very similar to the response from Version 2. There are a few differences that you will need to adapt to:
Hopefully these changes aren't too much of a hassle for you to make. If you ever need help, just get in touch.
Welcome to the new version of the API!