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
| Purpose | Provide 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 Parameters | apikey |
| API v2.0 Parameters | wsse headers |
| Returns | message, status plus a list of all vendors sorted alphabetically. |
Web Services Call - Model
| Purpose | Provide 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 Parameters | apikey, vendor |
| API v2.0 Parameters | wsse headers, vendor |
| Returns | message, status plus a list of all device models for this vendor sorted alphabetically. |
Web Services Call - Detect
| Purpose | Detect 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 Parameters | apikey, options, client information, server information, other information |
| API v2.0 Parameters | wsse headers, options, client information, server information, other information |
| Returns | message, status plus option information for this device or no information if this device cannot be found. |
| Other Cool Uses | Use 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
DATA
| apikey | Your apikey is automatically generated when your account is created. Find it on your My Profile page. |
| wsse headers | Get the full lowdown on WSSE at XML.com |
| client information | We 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 information | We use server information provide enhanced analytics. This feature is currently in development. |
| other information | Other 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). |
| options | These 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 Version | Status
(Error Code) | Message | Meaning |
| 1,2 | 0 | OK | No Errors |
| 1,2 | 100 | Unknown request type - please use xml or json | Try 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. |
|
