API Frequently Asked Questions

  • How do the API quota limits work? What happens if I exceed my quota?

    Each API Tier has it's own quota for monthly use. Each API End point's quota is metered independantly; so for example if you exceed the Batch Parse quota but not the Parse quota, you can still send individual parse requests. The quota resets at the start of each month.

    You are not charged any extra if you exceed the monthly quota, you are simply no longer able to use that end point.

    If you have exceeded your quota, you can switch to a higher API plan.

  • I have used all my API Tier's quota for the month. What now?

    If you are on the Free, Standard, or Pro tiers, you can simply change your plan to a higher tier. We charge pro-rata for the days you are on each plan, so you are only charged for the days that you use each tier. Once the new calendar month starts and your monthly quota is reset, you can change your plan back to your normal one.

    If you are on the Enterprise tier and have exceeded the quota on that, you can start to customise your Enterprise plan by adding on extra amounts of API quota. To do this, please send us a message detailing what you would like to do, and we will take care of it for you.

  • Can I pay with PayPal?

    We prefer not to receive payments with PayPal; it's best if you enter your credit card details in the Accounts System. However, if PayPal is the only way you can pay for the API, we will accept it for annual payments only. Please contact us and we'll arrange your payment for the year.

  • Which user agent parsing library do you use?

    We use our own proprietary user agent parsing library. It is the same library which powers the homepage of whatismybrowser.com.

    We have been developing this parser since 2010 and it now detects thousands of different browsers & bots and tens of thousands of devices and platforms.

  • How is the parsing library developed?

    The development process basically works like this:

    1. In our day-to-day operation of the API and the website, we store all the useragents our systems see, in a big database
    2. These user agents are automatically grouped together, so that very similar user agents can be handled together (eg, there's no difference between a Chrome 89 and Chrome 90 user agents other than the version number and we basically treat them the same way)
    3. Each day when we sit down to develop the parser, we look for the next "group" of user agents which hasn't been handled yet, based on the number of times it's been seen
    4. We pick a few user agents out of the group and test them against our user agent parser with our specialised tester tool; if the parser doesn't handle the user agents properly, we extend and develop the parser until it does. Sometimes this can be as simple as picking up a new fragment and figuring out what it refers to, sometimes it requires a lot of detective work to determine what the various arcane fragments mean and how they work together
    5. When it seems like the parser is handling the new user agents correctly, we run our unit tester for the parser to ensure that there are no feature regressions and if there were any fixes or improvements to existing functionality then they are working 100% correctly. We have several thousand test cases now.
    6. When all the unit tests pass correctly, we create a new test case for the user agent, to ensure that the detection will always work in the future
    7. If there are other "similar but different" user agents for the same group, we repeat the same process for them too
    8. Once that group of related user agents has detection written for it, we mark that group as "good", and move on to the next one

    That's the basic gist of it; sometimes if there's a really weird fragment that we can't figure out, we add it to a list and then on the homepage of whatismybrowser.com, if someone comes along with that fragment in their user agent, we show a small question and form to them, asking if they have any idea about what it might mean.

    Occasionally, we reach out to manufacturers too, to ensure that we are detecting their software or platform correctly.

    There are also regular maintenance tasks we perform too; for example, we have a number of version number mappings (eg for Kindle devices, Darwin to macOS/iOS version numbers, etc) and we regularly update the mapping information for them.

  • What is the difference between the User Agent Parse end-point and the User Agent Database/Database Search?

    • The User Agent Database (and Database Search) is for searching the database for many user agents that match certain criteria
    • The User Agent Parse (and Batch Parse) is for decoding user agent strings into the different bits of information.

    For example, you can use the Database Search to search for "Chrome user agents on Android tablets" and you will get many, many results from the database. You can get pretty detailed with your queries too - you can search for specific version numbers, dates they were first seen at, hardware types (general mobile/phone/tablet), software types (bots, browsers, applications, in app browsers etc), operating systems, operating platforms and so on.

    In short, the user agent database search will return user agent strings that we've seen on the website or via the API which match your search criteria.

    The User Agent Parse is for decoding user agents. It doesn't query the database; when you send a user agent to User Agent Parse, our custom software runs each time and analyses the user agent. It figures out the software (Chrome, Firefox, Safari, Googlebot, or hundreds of other software that we know about), it figures out the operating system, the hardware type, software type, platform, if it's a spammy or weird or dangerous user agent and many other things.

    In short, if you're trying to decode a user agent, use the User Agent Parse API. If you need to search for a group of user agents that match certain criteria, use the Search API end point.

    Why would you use each one?

    User Agent Search:
    • Find the 50 most recent Chrome user agents
    • Find 500 user agents for Safari on iPhone that have been seen since 2018
    • Find variations of Googlebot user agents
    User Agent Parse:
    • Decode this user agent and tell me the software name, version, if it's up to date and what operating system they're using

    It is theoretically possible to try to use the User Agent Database to decode user agents. You would do this by searching for the exact user agent you are trying to decode, and then looking at the parse information that the database has for it. However we really, really don't recommend doing this. The problem is that the database would need to have the exact same user agent string as the one you are searching for, for it to work. If a single version number fragment in the user agent you are trying to parse is unique, then you won't get a match.

    The Parser doesn't have this problem - you can send it unique user agents (eg a pre-release version of Chrome that we've never seen in our systems before and for which we don't have a database record for yet), and it will still parse the user agent correctly and send you a result.

  • Can I cache the API result?

    Yes, absolutely! You are welcome to cache the query results from our API to help speed up duplicate queries and to help keep your quota low.

    We recommend a cache-time of no more than a few hours, so you've always got the latest "up to date" version checks and version numbers.

  • I'm confused why the parser is detecting a user agent a certain way

    Every bit of detection for user agent parsing is done deliberately and intentionally; if you have a question about it, then we're happy to explain why it's doing what it's doing. We want you to be satisfied with how it works, and perhaps you've found something that's wrong! Either way, get in touch and we can discuss it.

  • Do you work with resellers?

    Yes, if you are a large corporate company and need to get your subscription via a reseller company, get in touch! We are happy to provide arrangements like this.

  • Do you have a DUNS number for US Government contracts?

    Yes, if you are from a US Government Department and wish to use the API, we have a DUNS number which can be used with a contract with us. We also have an NCAGE number. Please contact us for more information.

If you have any questions at all: Sales, Integration, or Trouble-shooting, don't hesitate to get in contact with us.