In August 2017 we launched Version 2 of the WhatIsMyBrowser.com API.
Version 2 mostly works the same way as Version 1, however there have been a few changes which help lay the groundwork for the future of the API that break compatibility with the original Version 1 of the API.
We will continue running and supporting Version 1 of the User Agent Parser API, although customers are encouraged to upgrade when they can.
Both Version 1 and Version 2 utilise the same User Agent Parser code to do the detection, so as we add more detection for more browsers, Version 1 will continue to also be able to parse the user agents for them.
However, as we continue to build new API end points - they will not be back ported to Version 1 of the API. If you want to get access to the new API end points, you'll need to use the new Version 2 of the API.
This is a guide to migrating your Version 1 code to Version 2.
The decision to move to a new version of the API wasn't made lightly; but after careful consideration it seemed the best thing to do.
The main reason for switching to a "version 2" of the API was the addition of some new API end points.
In both cases, if we didn't introduce a more unified way of sending requests, it would have introduced quirks or inconsistencies between the various end points.
One of the new end points we've added is the Batch Mode user agent parsing. This required a safe way for you to send hundreds of user agents in a single request, and unfortunately the original way of POSTing a user agent as a form variable would no longer work.
The batch mode clearly required the way to send those hundreds of user agents in a JSON structure, so that we could safely unpack, process, and return the result to you.
With the addition of end points which use a GET HTTP method (such as the Latest Version Numbers end point), it also became impossible for you to POST your API key; and putting the key into URL parameters is a bad idea (typically the entire URL on requests will get logged, so that means your key would inadvertently get logged. So moving to using HTTP auth headers was the best way to proceed; it's also the "modern" way of doing these things now.
The changes are:
The easiest bit to update! The API Endpoint for parsing user agents is now:
The only part of the URL which has changed is the v2 part.
If you're not currently using the HTTPS url, now is a great time to switch to it as well!
Previously - using Version 1 of the API, you would POST user_key (along with user_agent) in the POST body. Our authentication has now changed to use a HTTP header. This is more aligned with current best practices regarding API authentication and also makes GET requests possible without putting your API key in a URL Parameter (which would get stored in log files).
To do this, stop sending user_key as a Form Data POST variable and instead send a X-API-KEY header containing the same API Key that you've been using. You can get your API key from accounts.whatismybrowser.com if you need to.
Previously you needed to POST the user_agent (along with the user_key), however in Version 2, please POST the user agent to be parsed inside a JSON structure in the POST BODY, with user_agent as the dictionary key.
For example:
NOTE: there is basic sample code at the end of this article which demonstrates how to do this. Also don't forget to check out the Version 2 documentation for more information.
During the continual development of the parser, after adding hundreds and hundreds of bots, crawlers and analysers to the detection, it started to feel strange setting the "browser" name for each of them. Bots definitely don't fit into the definition of a web browser... A browser has a human behind it, interacting with your site, whereas a bot tends to be more automated and crawl your website systematically, not browsing it the way a human does.
As such, with the launch of Version 2, we have changed all of the fields which have "browser" in the name to more accurately reflect that they are a kind of software instead of being a browser.
Combined with the software_type and software_sub_type fields returned in the API response, you can get an accurate description of the software which is accessing your site, whether it's a bot or a browser.
| Old Field Name | New Field Name | Example Value |
|---|---|---|
| simple_browser_string | simple_software_string | "Chrome 60 on Mac OS X (Mavericks)" |
| browser | software | "Chrome 60" |
| browser_name | software_name | "Chrome" |
| browser_name_code | software_name_code | "chrome" |
| browser_version | software_version | "60" |
| browser_version_full | software_version_full | ["60", "0", "3112", "90"] |
This is part of us moving away from referring to the software as a "browser", and this could also potentially contain pieces of detection which aren't strictly related to the software being used.
While it essentually contains tabular or Key/Value type data, the format which it returns is a dictionary, so the field name change reflects this as well.
hardware_architecture is no longer its own field - it will now appear in the new extra_info_dict if it can be detected.
This change in the API response simultaneously makes it easier for you to extract just certain parts of the full version number (without having to first split() the version string), and also makes the API response mirror how we handle version numbers inside our code. We handle version numbers as lists of version fragments and find that it works excellently, so we wanted to provide the same interface to you.
The following two fields now return their version numbers as a list of version fragments. For example ["60", "0", "3112", "90"]
Please note that each element in the list will always be a string, never an integer, as some version fragments occasionally contain letters.
In version 1 of the API, next to the parse block, you would also get a result which would be success or a number of other error codes.
Now, in version 2 of the API, result still exists, but contains three sub keys which tell you more about your request. For example:
The code key will either be success or error; so it's very easy to check the response from the server (the appropriate HTTP status codes will be returned as well!). For more detail (for example what kind of error was encountered) you can check the message_code key which will be different depending on the type of error.
For a list of the possible error message_code values, please refer to our API Specification.
Those are all the changes from Version 1 to Version 2. We hope you can migrate your system over painlessly. We're always happy to help in any way we can, so if any part of this wasn't clear, please contact us and we'll help you migrate to the new version.
Putting this all together, here's a very straight forward example of the relevant parts of basic Python-Requests demonstration:
Please note, we have full documentation for how Version 2 works, including a detailed Swagger API File and a sample Postman configuration, this example is to just show a very straight-forward example of how you send the API Key and User Agent.
Please view the Version 2 documentation for more information.