Web Services API

This page tells you everything you need to know to make queries to Handset Detection. All web service queries can be made in XML or JSON format.

Version 1.0 of our API is a simple, lightweight api that allows your to query our service with XML or JSON. v1.0 is best used in small sites, one off installs, or custom development. With v1.0 your apikey is like a password, its private and you should not share it with anyone.

Version 2.0 of our API uses X-WSSE. It works with your login email address and a shared secret. v2.0 has more flexibility and security however it is more complex. Software Tokens (apikeys) are no longer associated with individual accounts, rather they relate to a piece of software. In v2.0 apikeys are public. v2.0 is best used to build handset detection into products such as plugins, or cases where greater security is required.

API v1.0 Requests and Replies API v2.0 Requests and Replies

Web Services Call - Vendor
PurposeProvide a list of vendors for all devices in our system. Useful for populating dropdown boxes and select lists on web pages.
XML URI/devices/vendors.xml
JSON URI/devices/vendors.json
API v1.0 Parametersapikey
API v2.0 Parameterswsse headers
Returnsmessage, status plus a list of all vendors sorted alphabetically.
Web Services Call - Model
PurposeProvide a list of models a given vendor. Useful for populating dropdown boxes and select lists on web pages after the vendor has been selected (from above).
XML URI/devices/models.xml
JSON URI/devices/models.json
API v1.0 Parametersapikey, vendor
API v2.0 Parameterswsse headers, vendor
Returnsmessage, status plus a list of all device models for this vendor sorted alphabetically.
Web Services Call - Detect
PurposeDetect a device from the provided data. Can also perform a geoip look up. Usually a detection is called at the start of a session with further calls made to Track (below).
XML URI/devices/detect.xml
JSON URI/devices/detect.json
API v1.0 Parametersapikey, options, client information, server information, other information
API v2.0 Parameterswsse headers, options, client information, server information, other information
Returnsmessage, status plus option information for this device or no information if this device cannot be found.
Other Cool UsesUse detect to discover handset capabilities and format content specifically to a mobile device. Content could be web pages, ringtones, icons, wallpapers, java games.
Web Services Call - Track
PurposeTrack people as they move around your website. When you pass in a tags field it becomes easy to track people, as they move around your site.
XML URI/devices/track.xml
JSON URI/devices/track.json
API v1.0 Parametersapikey, client information, server information, other information
API v2.0 Parameterswsse headers, client information, server information, other information
Returnsmessage, status


DATA
apikeyYour apikey is automatically generated when your account is created. Find it on your My Profile page.
wsse headersGet the full lowdown on WSSE at XML.com
client informationWe use client information to perform device lookups and log analytics information. Client information is the HTTP Request Header as sent to your server by the client. Typically this contains information such as Host, Accept, Accept-Charset, Accept-Language, User-Agent, x-wap-profile. All fields are optional however for most accurate detection we recommend passing User-Agent and x-wap-profile.
server informationWe use server information provide enhanced analytics. This feature is currently in development.
other informationOther information includes ipaddress (or remote_addr) and tags. ipaddress and remote_addr can be used interchangably and are used for geoip lookups. You must specify the geoip option when passing ipaddress or remote_addr to get geoip informaiton returned.

Tags are user definable tags which you can use for anything. For example, you can log usernames against lookups and page views for later analysis. We're still working out funky uses for tags :-) Stay tuned (or drop us an email if you have any ideas).
optionsThese are capabilities (information groups) you wish get from a device query. Valid options are any of the following : product_info, wml_ui, chtml_ui, xhtml_ui, ajax, markup, cache, display, image_format, bugs, wta, security, bearer, storage, object_download, wap_push, drm, streaming, mms, j2me, sms, sound_format, flash_lite, geoip OR all. Add multiple options by separating them with a comma in the options field. If you leave options out, or send an empty options field then we'll send back some of the most common capabilities for your device.
messages & statuses (Error codes) Valid reply messages & statuses are :
API VersionStatus
(Error Code)
MessageMeaning
1,2 0 OKNo Errors
1,2 100 Unknown request type - please use xml or jsonTry setting content-type in headers
2 200 Bad username/secret combination.
2 201 Unmatched digest Digest does not match.
1,2 202 Apikey unknown, Inactive or Suspended
1,2 203 Maximum query limit reached or account suspended
1,2 204 Can not decipher your XML Ensure your XML is well formed
1,2 205 Can not decode your JSON Ensure your JSON is well formed
1,2 206 No data in payload Use http post, Ensure you have data in the payload
1,2 207 Vendor missing ! You must supply a vendor to get a model list
1 208 Apikey not found
2 209 Apikey not set - you must set an apikey header
1,2 300 User-Agent or x-wap-profile missing in request Warning Message - Not fatal.
1,2 301 Not Found Device not found in the database.