API Reference

Request format

This is the format of the POST request which you send to the API.

Field Description
user_key This is the your account's "user key". It identifies your account to the API.
a1b2c3d3x4mpl3us3rk3f0rth3ap1234
user_agent The user agent string you want to parse.
Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; FunWebProducts; GTB7.4; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; InfoPath.2; OfficeLiveConnector.1.4; OfficeLivePatch.1.3; .NET4.0C; AskTbFWV5/5.14.1.20007; Media Center PC 6.0; MDDR; MS-RTC LM 8; BRI/2)
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36
Mozilla/5.0 (Linux; U; Android 2.3.6; en-gb; GT-N7000 Build/GINGERBREAD) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1
Mozilla/5.0 (iPhone; CPU iPhone OS 6_1_3 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10B329 Safari/8536.25
Mozilla/5.0 (Linux; U; en-us; KFTT Build/IML74K) AppleWebKit/535.19 (KHTML, like Gecko) Silk/2.1 Safari/535.19 Silk-Accelerated=true
Response format

This is the format of the JSON response you will receive from the API.

Field Description
result
All plans
Was your request successfully sent and received?
"success"
"error"
error_message
All plans
If the "result" element was "error", there will also be "error_message" and "error_message_code" fields which provide more information about the error.
"Invalid HTTP request method. Please use POST."
"No api user_key provided in the request."
error_message_code
All plans
The error_message_code field contains a code string which corresponds to the error message. Use this for programatic comparison.
"invalid_http_request_method"
"no_api_user_key"
parse.simple_browser_string
All plans
This is the main string which describes the user's browser and system in a single, human readable sentence. It is typically a combination of the Browser and Operating System.
"Internet Explorer 8 on Windows 7"
"Chrome 35 on Mac OS X (Snow Leopard)"
"Android Browser 4 on Android (Gingerbread)"
"Mobile Safari 6 on iOS 6.1"
"Silk 2.1 on Fire OS"
parse.simple_sub_description_string
All plans
Describes a little bit more about the browser. It is derived from the "extra_info" items that are designated as being "more important". It is used very sparingly.
"Internet Explorer 7 Compatibility View"
parse.simple_operating_platform_string
All plans
This contains relevant platform/hardware. It is often blank for non mobile/tablet devices. In some cases for desktops/notebooks it's possible to figure out some information about the platform, so it will be included here.
"Dell"
"Samsung Galaxy Note (GT-N7000)"
"Apple iPhone"
"Amazon Kindle Fire HD 7\""
parse.simple_major
parse.simple_medium
parse.simple_minor
All plans
These three fields will have the same information as "simple_browser_string", "simple_sub_description_string", and "simple_operating_platform_string". Since those three fields may or may not have values (depending on the User Agent) it can make more work for your system to determine how to display those fields to your users/employees. These three fields will always have values in descending order. Refer to our blog post for more information.
parse.browser
All plans
The browser string - made up of the browser name and the browser version number (if the version number exists: some web browsers don't actually report a version number.)
"Internet Explorer 8"
"Chrome 35"
"Android Browser 4"
"Mobile Safari 6"
"Silk 2.1"
parse.browser_name
All plans
Just the name part of the browser
"Internet Explorer"
"Chrome"
"Android Browser"
"Mobile Safari"
"Silk"
parse.browser_name_code
All plans
A slugged version of the browser name. Useful for comparision via software, used as a css class name and so on.
"internet-explorer"
"chrome"
"android-browser"
"mobile-safari"
"silk"
parse.browser_version
All plans
The shortened browser version number, good for displaying to users (some browsers have long complicated version numbers that can be intimidating for users). If the second element of the version number (ie after the ".") a zero, it is not included (eg 35.0.1916...), however if it is non-zero (eg 2.1), it is.
"8"
"35"
"4"
"6"
"2.1"
parse.browser_version_full
All plans
The full version number for the browser
"8.0"
"35.0.1916.153"
"4.0"
"6.0"
"2.1"
parse.operating_system
All plans
The operating system string - made up of the operating system name and the operating system version number (if it exists: some web browsers don't actually report an operating system version.)
"Windows 7"
"Mac OS X (Snow Leopard)"
"Android (Gingerbread)"
"iOS 6.1"
"Fire OS"
parse.operating_system_name
All plans
Just the name part of the operating system
"Windows"
"Mac OS X"
"Android"
"iOS"
"Fire OS"
parse.operating_system_name_code
All plans
A slugged version of the operating system name. Useful for comparision via software, used as a css class name, etc
"windows"
"mac-os-x"
"android"
"ios"
"fire-os"
parse.operating_system_flavour
All plans
If there is a particular variant or "flavour" of the operating system which can be detected, it will be included here.
"Debian"
"Ubuntu"
"Slackware"
"CentOS"
parse.operating_system_flavour_code
All plans
A slugged version of the operating system flavour. Useful for comparision via software, used as a css class name, etc
"debian"
"ubuntu"
"slackware"
"centos"
parse.operating_system_version
All plans
The shortened or "friendly" version of the operating system version, good for displaying to users.
"7"
"Snow Leopard"
"Gingerbread"
"6.1"
parse.operating_system_version_full
All plans
The "full" operating system version number. This is often complicated or unintuitive and may refer to internal development names instead of commonly known version numbers (eg. "Windows NT 6.1" instead of "7").
"Windows NT 6.1"
"10.6.8"
"2.3.6"
"6.1.3"
parse.operating_system_frameworks
Pro & Enterprise plans only
This shows operating system frameworks that announce themselves in the user agent. Note that this field provides "name", "code" and "versions" elements; the "versions" elements contain "simple" and "full" version numbers (if appropriate).
[ { "name":"Microsoft .Net", "code":"microsoft-dotnet", "versions":[ { "simple":"2.0", "full":"2.0.50727" }, { "simple":"3.0", "full":"3.0.30729" }, { "simple":"3.5", "full":"3.5.30729" }, { "simple":"4.0", "full":"4.0C" } ] } ]
parse.operating_platform
Pro & Enterprise plans only
A nice name for the platform. It makes up part of the "simple_operating_platform_string" element. It's more commonly present for mobile/tablet/gaming devices, as desktop/laptop systems don't tend to announce themselves in the user agent as much.
Note that as per the JSON specification, some characters will be safely escaped; you will need to unescape them to display them to your users.
"Galaxy Note"
"iPhone"
"Kindle Fire HD 7\""
parse.operating_platform_code
Pro & Enterprise plans only
This contains any model numbers or codes that can be extracted from the User Agent.
"GT-N7000"
parse.operating_platform_vendor_name
Pro & Enterprise plans only
The name of the vendor of the platform; as with the other platform elements, this tends to be found more in the mobile/tablet/gaming user agents. However some desktop/laptops do announce their platform vendors.
"Dell"
"Samsung"
"Apple"
"Amazon"
parse.hardware_architecture
Pro & Enterprise plans only
Some user agents include their hardware architecture.
"i386"
"i686"
"MIPS"
"ARM"
parse.extra_info
Pro & Enterprise plans only
This contains various bits of information that can be gathered from the user agent but which doesn't fit in to any of the other API fields. It is multidimensional; the elements under the "10" element are considered "more significant" than the rest; they are the ones which are combined to make up the "simple_sub_description_string". There are not many things which are marked as "10"s. The elements under the "20" element are of "medium" level significance. "30" has been reserved for "low" level significance, however at this time (July 2014) nothing has been assigned to "30".
"10":[ "Internet Explorer 7 Compatibility View" ], "20":[ "Media Center PC v6.0" ]
parse.detected_addons
Pro & Enterprise plans only
Detected Addons list all of the detected addons that have been installed either by the vendor or by the user. Please note that this section can only show addons which announce themselves in the user agent.
[ "Google Toolbar v7.4", "Fun Web Products", "Bing Toolbar v2", "InfoPath XML MIME Filter v2", "Live Meeting 2007", "Microsoft Office Live Connector v1.4", "Microsoft Office Live Patch v1.3", "Microsoft Windows Security Licensing v2.0", "Ask Toolbar 5 v5.1" ]
parse.browser_capabilities
Pro & Enterprise plans only
This is a general element which includes various detected capabilities that the browser possesses.
[ "Silk Accelerated" ]
parse.extra_info_table
Pro & Enterprise plans only
Somewhat similar to "extra_info", this is a general collection of things we detected from the user agent which don't belong in the structured elements of the API response. However "extra_info_table" has a key/value structure, with the key being a human readable description of the value.
{ "System Build":"Gingerbread" }
{ "Mobile Build":"10B329" }
{ "System Build":"IML74K" }
{ "iPad Version Full": "iPad 3 WiFi", "Mobile Build": "10B329" }
parse.software_type
parse.software_sub_type
Standard, Pro & Enterprise plans
Describes the "type" and "sub_type" of client software.

Instead of merely a single "type" field to describe the user agent; we have "software" type and "hardware" type fields. This lets you look for whether it's a "browser", independent of whether it's on a computer or on a phone.

The "software_type" field will show you what kind of software is being used to make the HTTP request.

We also have the concept of "sub types", so you will typically also see a "software_sub_type".

For example: If you want to simply check that it's some kind of "browser", look in the "software_type" for "browser". This will be some kind of user-operated browser.

Then, if you look at the "software_sub_type" field; you would see that perhaps it's a "web-browser" (ie Chrome or Firefox), or maybe it's a "in-app-browser" (perhaps the Twitter App's browser). Maybe it's a "rss-reader" or a "email-client".

These are all classified as "browsers"; the "software_sub_type" gives you more information about what "type" of browser it is.

Or maybe it's some kind of "bot"; an automated piece of software which is accessing your site; the main "software_type" will be "bot", but then in the "software_sub_type" field we'll identify whether it's a "crawler", an "analyser", a "feed-fetcher" and so on.

software_typesoftware_sub_typedescription
browserSome kind of user-operated HTTP client.
web-browsera standard web browser (eg Chrome, Firefox)
in-app-browsera web browser contained inside some kind of other application (eg Twitter, Google Earth etc)
rss-readersome kind of RSS feed reader; eg the "view more" panel
ua-anonymizersome kind of browser which has had it's user agent "anonymized"/randomised so as to be undetectable
email-clienta browser which has been built in to an email client
botSome kind of automated system
crawlerCrawling/spidering/caching content from your site
analyserAnalysing some aspect of your site (eg validation/seo)
toolMiscellaneous software which can't be classified as a crawler or analyser
security-analyserA system which looks for security problems on your site
site-monitorA system which is monitoring for down time or changes to your site
feed-fetcherA system which is fetching some kind of content feed
applicationSome kind of application which is not technically a browser
kioskA kiosk style application; interactive public access information system
billboardA system which shows billboard style content (eg large screen advertising)
download-helperAn application which helps with downloading files (eg resuming large downloads etc)
software-librarySome kind of software library is being used to access your site: eg "Python-urllib/2.7"
parse.hardware_type
parse.hardware_sub_type
parse.hardware_sub_sub_type
Standard, Pro & Enterprise plans
Describes the "type", "sub_type" and "sub_sub_type" of client hardware.

These fields are the other "side" of the "software_type" fields. They describe the hardware type.

This becomes very helpful when making the distinction between browsers on computers and browsers on mobile. It will also give you insight into the growing field of wearable devices and IoT enabled devices.

Be aware that some of these "types" have not been seen in the wild yet; but rest assured that we are planning for the day in which they become more common. We have already mapped out how we will detect/report these devices for you in the future (eg the specific types of wearables or vehicles).

It's possible to get really specific about what type of hardware is in use; for example, a web browser on some kind of Smart Glasses can be classified broadly as Mobile, but can then also have a "hardware_sub_type" of "wearable", and can then also have a "hardware_sub_sub_type" of "glasses" (provided the glasses browser user-agent includes enough to identify itself!)

In some instances (eg "computer") we may be able to tell based on the user-agent whether it's a desktop or a portable computer and will include this information in the hardware_sub_type field. If not, the hardware_type is still "computer".

hardware_typehardware_sub_typehardware_sub_sub_typedescription
mobileSome kind of mobile device
phoneWe can tell that it's a phone based device
tabletWe can tell that it's a larger-size portable device
phabletWe can tell that it's a mobile/tablet combination
ebook-readerA device primarily built for reading ebooks
handheld-gameA device primarily built for playing video games (eg PS Vita)
music-playerA device primarily built for playing music (eg iPod, Zune)
handheld-gameA device primarily built for playing video games (eg PS Vita)
wearableSome kind of wearable mobile device
watchA watch
glassesGlasses
vrVirtual Reality headset
computerComputer (ie non-mobile) system
desktopWe can tell that it's a desktop computer
portableWe can tell that it's a portable/notebook/laptop computer
applianceIoT devices are still new and rare (and mostly a joke) but as they become detectable, this is where they'll be identified...
refrigeratorWhat a world we live in...
toasterInsert toast and press any key...
lightbulbYou know it will happen one day...
large-screenSome kind of "large screen" system
tvA "smart" television
kioskKiosk-style hardware; public information system
media-playerSimilar to a "smart" TV but as a seperate piece of hardware
game-consoleA game console
serverSome kind of server (eg for bot requests)
vehicleIn-car web system
carWe can tell that this is a car
truckWe can tell that this is a truck
trainTrain
AirplaneAirplane
parse.layout_engine_name
Pro & Enterprise plans only
The name of the rendering engine used to layout the HTML on the page.
"Trident"
"WebKit"
parse.layout_engine_version
Pro & Enterprise plans only
The version number of the rendering engine used to layout the HTML on the page.
"4.0"
"537.36"
"533.1"
"536.26"
"535.19"
parse.is_abusive
All plans
Does the user agent you submitted appear abusive? Some attackers send user agents which contain SQL injection attempts, or spam links in the hope that your system will be compromised. If a user agent appears abusive, it will not be parsed any further.
true
false
parse.user_agent
All plans
We also send back the user agent to you in this element; this can help when analysing repsonses; you can check exactly what was sent in your request.
version_check.is_checkable
Normal, Pro & Enterprise plans only
Can we work out if this web browser is up to date or not? We keep the latest version data for Chrome, Safari on Mac, FireFox, Internet Explorer and Opera.
true
false
version_check.is_up_to_date
Normal, Pro & Enterprise plans only
If this is one of the browsers that can be checked if it's up to date, this will tell you if it is up to date or not. If it is not one of those browser, this field will not appear in the API response.
true
false

Error Codes:

These are possible response codes. Make sure your code deals gracefully with any of these errors that it may encounter.

  • No User Agent Provided

    { 'result': "error", 'message': "No user_agent provided in the request.", 'message_code': "no_user_agent", }
    You haven't included a user agent to parse in your request to the API.
    To resolve this: Please ensure that you are POSTing the user agent in a field called "user_agent"
  • No API User Key Provided

    { 'result': "error", 'message': "No api user_key provided in the request.", 'message_code': "no_api_user_key", }
    You haven't included your API User Key in the request to the API.
    To resolve this: Please ensure that you are POSTing your API user key in a field called "user_key". You can find this key on your Applications page
  • API User Key Invalid

    { 'result': "error", 'message': 'user key "%s" is invalid', 'message_code': "user_key_invalid", }
    You are sending an incorrect API key in your request.
    To resolve this: Please ensure that you are POSTing your correct API user key in a field called "user_key". You can find this key on your Applications page
  • API Usage Limit Exceeded

    { 'result': "error", 'message': "Your account has gone over its limit for this month. Please consider upgrading your plan.", 'message_code': "usage_limit_exceeded", }
    Your account has reached its usage limite for the month.
    To resolve this: Wait until your monthly usage is reset at the beginning of the month, or upgrade your plan to a higher level to receive a much higher quota. You must watch the API responses for this error and ensure that your system doesn't send further API requests once your account has gone over its quota for the month.
  • API Unknown Error

    { 'result': "error", 'message': "We're sorry, the system encountered an error, CODE: %s. Request ID: %s" 'message_code': "unknown_error", }
    Something has gone wrong in the internals of the API and no further information can be provided.
    To resolve this: If these errors ever occur, they are logged in detail and our staff are notified; we will fix it as a high priority issue. If you are continuing to get these errors, please contact us and quote the CODE and any Request IDs and we'll be able to tell you more about what's happened and debug it for you if the errors are continuing for you.