How userstack Delivers a Scalable, Real Time Cloud-based User-Agent API

userstack's User-Agent Detection and Parsing

As web developers, we see User-Agent strings all the time. You know them on sight, they're both ubiquitous and invisible. For example:

"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Safari/605.1.15"

Whether you're trying to customize content for particular groups of customers or browsing logs, you're familiar with them. But do you know how to take advantage of them to enhance your website's user experience?

Today, I'm introducing userstack, a cloud-based REST APITrack this API service for sniffing browsers and devices to parse the User-Agent string your customers arrive with. It's not exactly new but evolved from the well known and widely accepted UserAgent API. (Fortunately, there's a legacy mode for pre-existing users.)

The userstack home page, detect and parse any browser device and OS in real time. Start using the API, brought to you by apilayer.

The userstack home page, detect and parse any browser device and OS in real time. Start using the API, brought to you by apilayer

Userstack provides an instant, secure User-Agent string lookup JSON REST API which makes it easy to translate User-Agent strings from your customers' browser or device to determine which browser they're using, which operating system and which device. It can also help you detect bots and crawlers.

In JavaScript for example, you can access the User-Agent string with:
window.navigator.userAgent

The image below shows the live userstack home page demo of parsing a User-Agent string into its components parts e.g. browser, OS, device and brand:

Screenshot of demo area of home page. User-Agent String discerned into parts, User-Agent, Type, Brand, Name and URL by userstack.com.

Screenshot of demo area of home page. User-Agent String discerned into parts, User-Agent, Type, Brand, Name and URL by userstack.com.

Try it on the home page by clicking the green "Run Check" button.

Exploring Common Scenarios

Static image, animated at userstack.com, depicts unknown visitors arriving at your website or service, using the API to identify their browser e.g. Safari, device e.g. MacOS to deliver a brighter future in the form of a sun.

Static image, animated at userstack.com, depicts unknown visitors arriving at your website or service, using the API to identify their browser e.g. Safari, device e.g. MacOS to deliver a brighter future in the form of a sun.

The userstack website animates the image above, demonstrating some key uses of the API:

  • Custom Content. User-Agents can tell you if a browser is a phone, tablet or desktop, customizing the layouts and features delivered beyond Bootstrap or CSS.
  • Native App Download. If you're selling software applications, you can provide specific product descriptions and links for Mac customers and others for Windows or Linux.
  • Tailored Advertising. If you're displaying advertisements, information about the visitors allows you to customize them and sell page views specifically by browser and device.
  • Spambot Detection. userstack can identify fake User-Agent strings allowing you to block or redirect bot traffic.
  • Crawler Protection. Web spyders make up a huge portion of website traffic, mostly unwanted with no productive purpose. userstack makes it easy to block unwanted crawlers, saving outbound bandwidth and improving your servers' performance.

This is what the User-Agent string was designed for in HTTP, negotiating with the visitor's browser so you can best tailor and customize content for it.

"In HTTP, the User-Agent string is often used for content negotiation, where the origin server selects suitable content or operating parameters for the response. For example, the User-Agent string might be used by a web server to choose variants based on the known capabilities of a particular version of client software. The concept of content tailoring is built into the HTTP standard in RFC 1945 'for the sake of tailoring responses to avoid particular User-Agent limitations.'" — User Agent String, Wikipedia

The userstack API is highly scalable for enterprise customers and it uses a proprietary database mapping of User-Agent strings, updating it frequently during the week. It serves more than 10,000 companies around the world including Apple, Intuit and Zendesk. The User-Agent string can also be used to exclude browsers from content via robots.txt.

You can request decoding of individual User-Agent strings in realtime from the API or you can parse logs and request bulk User-Agent parsing. You can customize results to optimize performance and receive them in either JSON or XML.

And, userstack is affordable.

Accessible Pricing

Pricing table, free with 10,000 lookups per month, basic, business, business pro and enterprise plans.

Pricing table, free with 10,000 lookups per month, basic, business, business pro and enterprise plans.

userstack's browser detection api is still free to use for new users up to 10,000 requests per month. For smaller applications, this may be all you need. To access userstack's complete suite of features, you'll need to choose a plan from $10 monthly up to $99.99, or request a custom enterprise plan.

Bulk lookups are only available at the Business plans shown above starting at $49.99 per month. And, you can save 20 percent on any plan by paying annually. HTTPS encryption is only available with a paid plan. Language and Code Compatibility

As a REST API, userstack is easily accessed with a variety of languages. Here's Node.js:

Screenshot of embedded code example on home page for accessing the userstack API from Nodejs. PHP, Python, JQuery, Go and Ruby are also offered.

Screenshot of embedded code example on home page for accessing the userstack API from Nodejs. PHP, Python, JQuery, Go and Ruby are also offered.

And, here's a Ruby example:

Require 'net/http'
require 'json'
params = {
  :access_key => "YOUR_ACCESS_KEY",
  :ua => "Mozilla/5.0 (iPad; CPU OS 9_3_2 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13F69 Safari/601.1"
}
uri = URI('http://api.userstack.com/detect')
uri.query = URI.encode_www_form(params)
response = Net::HTTP.get(uri)
json = JSON.parse(response)
if json['device']['type'] == 'tablet'
  print("It's a tablet.\n")
end

Visit the userstack API home page to see embedded code you can copy and paste for PHP, Python, JQuery and Go too. And, since it's a REST API, you can use it with whatever language or platform you choose that provides HTTP services.

Example User-Agent API Results

Here's an example of the detailed response data. There are essentially four components:

  1. User-Agent and Operating System details e.g. browser on MacOS
  2. Device detection including mobile or desktop
  3. Browser sniffing e.g. Opera or Safari
  4. Crawler detection
{
  "ua":"Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.102 Safari\/537.36 OPR\/57.0.3098.116",
  "type":"browser",
  "brand":"Apple",
  "name":"Mac",
  "url":"http:\/\/www.operasoftware.com\/",
  "os":{
    "name":"macOS 10.14 Mojave",
    "code":"macos_10_14",
    "url":"https:\/\/en.wikipedia.org\/wiki\/MacOS_Mojave",
    "family":"macOS",
    "family_code":"macos",
    "family_vendor":"Apple Inc.",
    "icon":"https:\/\/assets.userstack.com\/icon\/os\/macosx.png",
    "icon_large":"https:\/\/assets.userstack.com\/icon\/os\/macosx_big.png"
  },
  "device":{
    "is_mobile_device":false,
    "type":"desktop",
    "brand":"Apple",
    "brand_code":"apple",
    "brand_url":"http:\/\/www.apple.com\/",
    "name":"Mac"
  },
  "browser":{
    "name":"Opera",
    "version":"57.0.3098.116",
    "version_major":"57",
    "engine":"Presto\/Blink"
  },
  "crawler":{
    "is_crawler":false,
    "category":null,
    "last_seen":null
  }
}

Before I walk you further through using userstack's API, I want to mention its service provider.

userstack is Brought to Us by apilayer

This is the sixth product introduction apilayer has asked me to write for ProgrammableWeb.

During this time, I've experienced firsthand the simplicity, affordability, consistency, and integration of all of its API services for Web developers, entrepreneurs, small businesses and enterprise level corporations.

Here are a few earlier articles:

I very much appreciate how their pricing models support both individuals and small startups as well as high scale multinational corporations. I'm genuinely a fan.

Let's get started.

Getting Started with the userstack Service

Sign Up for Your Free Account

To get started with userstack, click the SIGN UP FREE button in the upper right of the navigation bar. Of course, you can also choose a premium plan with higher capacity.

Registration for userstack

The sign up form is very straightforward:

Blank sign up form at userstack's website home page userstack.com

Blank sign up form at userstack's website home page userstack.com.

You'll also be asked to provide your billing information in case you upgrade.

The userstack API Dashboard

The Quickstart Guide
userstack's API dashboard provides your API key and a simple 3 step quickstart guide:

3-step quickstart guide at userstack after sign up. Navigation header on left. Three steps on right: Your API key, API Endpoints and API Integration.

3-step quickstart guide at userstack after sign up. Navigation header on left. Three steps on right: Your API key, API Endpoints and API Integration.

Step 1 - Your API Access Key
Your API access key provides access to the userstack API. It's required to be included as a parameter in every call. You can also reset the key to secure a new one whenever you wish.

Step 2 - Reviewing the Major API Endpoints
There are just two primary methods for working with userstack User-Agent API services:

Base URL: Whichever API method you choose to use, all API requests to the userstack API start out with the following base URL: https://api.userstack.com/detect/

Single Lookup of User-Agent String
Here's the quickstart example for single lookup:

// Single Lookup - look up any User-Agent String
https://api.userstack.com/detect
    ? access_key = YOUR_ACCESS_KEY
    & ua = Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 OPR/57.0.3098.116    
// optional parameters: 
    & output = json
    & fields = type,os,device
    & callback = MY_CALLBACK

Notice your API access_key, shown in redaction above, and the request User-Agent string as parameter ua.

The output parameter allows for JSON or XML. The fields allow you to limit the response data from the API for better performance, and the callback function allows you to send the data as an argument using JSONP.

I'll review this in these response objects in more detail shortly.

Bulk Lookup of User-Agent Strings

Let's say you have a large block of User-Agent strings you'd like to parse, for example from logs or a statistics tracker. You can request userstack parse all the User-Agent strings at once.

// Bulk Lookup - only using HTTP POST to the endpoint URL below with 
// comma-separated User-Agent strings in ua_batch[] object
https://api.ipapi.com/detect
    ? access_key = YOUR_ACCESS_KEY   
// optional parameters: 
    & output = json
    & fields = type,os,device
    & callback = MY_CALLBACK

For bulk lookups, the User-Agent strings are sent via HTTP POST as an array in the body of the request submission. I'll also show an example of this further within.

The optional parameters work identically in this scenario but obviously the performance benefit of reducing requested fields is multiplied by the number of User-Agent strings.

Step 3: Integrate into your application
The final step of the quickstart points us to documentation so we can learn more about integrating the userstack User-Agent parser into our applications for it's operating system detection, browser sniffing, device sniffing and crawler identifier.

Screenshot of userstack API Documentation. Navigation index on the left bar. Content on the right majority of the page.

Screenshot of userstack API Documentation. Navigation index on the lef bart. Content on the right majority of the page.

As you use more apilayer services, you'll appreciate how they all provide the same style of documentation, making it easy to learn each of their services quickly.

 

Comments (0)