This documentation is for an older version of the API. Use the Version 3 Documentation for the best experience.

Version 1 API Reference

Please note: this is for Version 1 of the API which is now deprecated.

If you are new to our API, make sure you use Version 3 instead.

If you still use Version 1, please consider updating your code to use Version 3. It will make your experience of using the API much easier.

Parse User Agent

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/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36
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)"
"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.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"
"Safari 6"
"Silk 2.1"
parse.browser_name
All plans
Just the name part of the browser
"Internet Explorer"
"Chrome"
"Android Browser"
"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
browser
Some kind of user-operated HTTP client.
web-browser
a standard web browser (eg Chrome, Firefox)
in-app-browser
a web browser contained inside some kind of other application (eg Twitter, Google Earth etc)
rss-reader
some kind of RSS feed reader; eg the "view more" panel
ua-anonymizer
some kind of browser which has had it's user agent "anonymized"/randomised so as to be undetectable
email-client
a browser which has been built in to an email client
bot
Some kind of automated system
crawler
Crawling/spidering/caching content from your site
analyser
Analysing some aspect of your site (eg validation/seo)
tool
Miscellaneous software which can't be classified as a crawler or analyser
security-analyser
A system which looks for security problems on your site
site-monitor
A system which is monitoring for down time or changes to your site
feed-fetcher
A system which is fetching some kind of content feed
application
Some kind of application which is not technically a browser
kiosk
A kiosk style application; interactive public access information system
billboard
A system which shows billboard style content (eg large screen advertising)
download-helper
An application which helps with downloading files (eg resuming large downloads etc)
software-library
Some 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
mobile
Some kind of mobile device
phone
We can tell that it's a phone based device
tablet
We can tell that it's a larger-size portable device
phablet
We can tell that it's a mobile/tablet combination
ebook-reader
A device primarily built for reading ebooks
handheld-game
A device primarily built for playing video games (eg PS Vita)
music-player
A device primarily built for playing music (eg iPod, Zune)
handheld-game
A device primarily built for playing video games (eg PS Vita)
wearable
Some kind of wearable mobile device
watch
A watch
glasses
Glasses
vr
Virtual Reality headset
computer
Computer (ie non-mobile) system
desktop
We can tell that it's a desktop computer
portable
We can tell that it's a portable/notebook/laptop computer
appliance
IoT devices are still new and rare but as they become detectable, this is where they'll be identified...
refrigerator
What a world we live in...
toaster
Insert toast and press any key...
lightbulb
large-screen
Some kind of "large screen" system
tv
A "smart" television
kiosk
Kiosk-style hardware; public information system
media-player
Similar to a "smart" TV but as a seperate piece of hardware
game-console
A game console
server
Some kind of server (eg for bot requests)
vehicle
In-car web system
car
We can tell that this is a car
truck
We can tell that this is a truck
train
Train
airplane
Airplane
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. The system will also send appropriate HTTP response codes as well. Please 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 limit 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.