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.

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
Parameters	apikey
Returns	Status message 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
Parameters	apikey, vendor
Returns	Status message 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
Parameters	apikey, options, client information, server information, other information
Returns	Status message 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

Purpose	Track 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
Parameters	apikey, client information, server information, other information
Returns	Status message.

DATA

apikey	Your apikey is automatically generated when your account is created. Find it on your My Profile page.
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.
status message	Valid status messages are : OK - There were no problems in processing your request. Not Found - Device not found in the database. OK but geoip disabled - ipaddress or remote_addr must be supplied for a geoip lookup (so it was not done). User-Agent missing in request - A device detection was requested without User-Agent supplied. Invalid Format. Could not parse your query. Perhaps your API Key is missing ? - Your APIKey is missing from the request.

Web Services - Requests and Replies

These requests and replies assume you have joined the service and been allocated an API key of 00000000000000000000000000000000.

XML Vendor

Request

<?xml version='1.0'?>
<request>
<apikey>00000000000000000000000000000000</apikey>
</request>

Reply (Note: This is a truncated list)

<?xml version="1.0" encoding="UTF-8" ?>
<reply>
<message>OK</message>
<vendor>Access</vendor>
<vendor>Acer</vendor>
<vendor>Aiko</vendor>
<vendor>Airness</vendor>
<vendor>Alcatel</vendor>
<vendor>AlphaCell Wireless</vendor>
<vendor>Amazon</vendor>
<vendor>Amoi</vendor>
<vendor>Amoisonic</vendor>
<vendor>Android</vendor>
</reply>

XML Model

Request

<?xml version='1.0'?>
<request>
<apikey>00000000000000000000000000000000</apikey>
<vendor>HTC</vendor>
</request>

Reply (Note: This is a truncated list)

<?xml version="1.0" encoding="UTF-8" ?>
<reply>
<message>OK</message>
<model>2125</model>
<model>2125 (vodafone)</model>
<model>3100 (Star Trek)</model>
<model>8100</model>
<model>8500</model>
<model>8900/Pilgrim/Tilt</model>
<model>9090</model>
<model>Artemis</model>
<model>Artist</model>
<model>Athena</model>
<model>Cingular 8125</model>
<model>DopodM700</model>
<model>Excalibur</model>
<model>Gemini</model>
<model>Herald</model>
<model>Hermes</model>
</reply>

XML Detect

Request

<?xml version='1.0'?>
<request>
<apikey>00000000000000000000000000000000</apikey>
<options>geoip, product_info, display</options>
<User-Agent>Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaN95/12.0.013; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413</User-Agent>
<x-wap-profile>http://nds1.nds.nokia.com/uaprof/NN95-1r100.xml</x-wap-profile>
<HOST>www.mydomain.com</HOST>
<Accept-Language>en;q=1.0,id;q=0.5,en;q=0.5</Accept-Language>
<REQUEST_URI>/myWebpage.php</REQUEST_URI>
<HTTP_REFERER>www.somedomain.com/checkthisout.html</HTTPREFERER>
<REMOTE_ADDR>137.121.189.228</REMOTE_ADDR>
<SERVER_ADDR>192.168.1.30</SERVER_ADDR>
</request>

Reply

<?xml version="1.0" encoding="UTF-8" ?>
<reply>
<message>OK</message>
<geoip>
<country>France</country>
<city>Arcueil</city>
<countrycode>FR</countrycode>
<region>A8</region>
<latitude>48.8</latitude>
<longitude>2.3333</longitude>
<isp></isp>
<company></company>
</geoip>
<product_info>
<brand_name>Nokia</brand_name>
<model_name>N95</model_name>
<unique>1</unique>
<ununiqueness_handler></ununiqueness_handler>
<is_wireless_device>1</is_wireless_device>
<device_claims_web_support>1</device_claims_web_support>
<has_pointing_device>1</has_pointing_device>
<has_qwerty_keyboard></has_qwerty_keyboard>
<can_skip_aligned_link_row>1</can_skip_aligned_link_row>
<uaprof>http://nds1.nds.nokia.com/uaprof/NN95-1r100.xml</uaprof>
<uaprof2></uaprof2>
<uaprof3></uaprof3>
<nokia_series>60</nokia_series>
<nokia_edition>3</nokia_edition>
<device_os>Symbian OS</device_os>
<mobile_browser>Nokia</mobile_browser>
<mobile_browser_version></mobile_browser_version>
</product_info>
<display>
<resolution_width>240</resolution_width>
<resolution_height>320</resolution_height>
<columns>15</columns>
<max_image_width>240</max_image_width>
<max_image_height>280</max_image_height>
<rows>6</rows>
</display>
</reply>

XML Track

Request

<?xml version='1.0'?>
<request>
<apikey>00000000000000000000000000000000</apikey>
<Accept-Language>en</Accept-Language>
<Accept-Encoding>gzip, deflate</Accept-Encoding>
<User-Agent>Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420.1 (KHTML, like Gecko) Version/3.0 Mobile/3B48b Safari/419.3</User-Agent>
<Accept>text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5</Accept>
<Connection>keep-alive</Connection>
<Host>test.zaption.com</Host>
<HTTP_HOST>192.168.1.30</HTTP_HOST>
<HTTP_USER_AGENT>Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.14) Gecko/20080404 Firefox/2.0.0.14</HTTP_USER_AGENT>
<HTTP_ACCEPT>text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5</HTTP_ACCEPT>
<HTTP_ACCEPT_LANGUAGE>en-us,en;q=0.5</HTTP_ACCEPT_LANGUAGE>
<HTTP_ACCEPT_ENCODING>gzip,deflate</HTTP_ACCEPT_ENCODING>
<HTTP_ACCEPT_CHARSET>ISO-8859-1,utf-8;q=0.7,*;q=0.7</HTTP_ACCEPT_CHARSET>
<SERVER_NAME>192.168.1.30</SERVER_NAME>
<SERVER_ADDR>192.168.1.30</SERVER_ADDR>
<REQUEST_URI>/myscript.php?id=IPHONE</REQUEST_URI>
<ipaddress>224.133.33.78</ipaddress>
</request>

Reply

<?xml version="1.0" encoding="UTF-8" ?>
<reply>
<message>OK</message>
</reply>

JSON Vendor

Request

{"apikey":"00000000000000000000000000000000"}

Reply

{"message":"OK","vendor":["Access","Acer","Aiko","Airness","Alcatel","AlphaCell Wireless","Amazon","Amoi","Amoisonic","Android","AnexTek","Apple","ARCELIK"]}

JSON Model

Request

{"apikey":"00000000000000000000000000000000","vendor":"Sagem"}

Reply

{"message":"OK","model":["3000","3016","3XXX","910","912","916","919","920","922","926","929","930","932","936","939","940","942","946"]}

JSON Detect

Request

{"apikey":"00000000000000000000000000000000","User-Agent":"Amoi-A310\/Plat-F-VIM\/WAP2.0\/MIDP1.0\/CLDC1.0 UP.Browser\/6.2.2.7.c.1.102 (GUI) MMP\/1.0","ipaddress":"247.135.228.143","options":"chtml_ui,xhtml_ui,cache,image_format,security,bearer,storage,object_download,drm,mms,j2me,flash_lite","HTTP_HOST":"192.168.1.30","HTTP_ACCEPT_LANGUAGE":"en-us,en;q=0.5","HTTP_REFERER":"http:\/\/192.168.1.30\/test.php?action=detect","PATH":"\/sbin:\/usr\/sbin:\/bin:\/usr\/bin","SERVER_SIGNATURE":"<address>Apache\/2.2.2 (Fedora) Server at 192.168.1.30 Port 80<\/address>\n","SERVER_SOFTWARE":"Apache\/2.2.2 (Fedora)","SERVER_NAME":"192.168.1.30","SERVER_ADDR":"192.168.1.30"}

Reply

{"message":"OK","chtml_ui":{"chtml_display_accesskey":false,"emoji":false,"chtml_can_display_images_and_text_on_same_line":false,"chtml_displays_image_in_center":false,"imode_region":"none","chtml_make_phone_call_string":"tel:","chtml_table_support":false},"xhtml_ui":{"xhtml_honors_bgcolor":false,"xhtml_supports_forms_in_table":false,"xhtml_support_wml2_namespace":false,"xhtml_autoexpand_select":true,"xhtml_select_as_dropdown":false,"xhtml_select_as_radiobutton":false,"xhtml_select_as_popup":false,"xhtml_display_accesskey":false,"xhtml_supports_invisible_text":true,"xhtml_supports_inline_input":true,"xhtml_supports_monospace_font":true,"xhtml_supports_table_for_layout":true,"xhtml_supports_css_cell_table_coloring":true,"xhtml_format_as_css_property":true,"xhtml_format_as_attribute":true,"xhtml_nowrap_mode":true,"xhtml_marquee_as_css_property":true,"xhtml_readable_background_color1":"#99CCFF","xhtml_readable_background_color2":"#FFFFFF","xhtml_allows_disabled_form_elements":true,"xhtml_document_title_support":true,"xhtml_preferred_charset":"iso8859","opwv_xhtml_extensions_support":true,"xhtml_make_phone_call_string":"wtai:\/\/wp\/mc;","xhtmlmp_preferred_mime_type":"text\/html","xhtml_table_support":true,"xhtml_send_sms_string":"none","xhtml_send_mms_string":"none","xhtml_supports_file_upload":false,"xhtml_file_upload":"supported"},"cache":{"total_cache_disable_support":false,"time_to_live_support":false},"image_format":{"wbmp":true,"bmp":false,"epoc_bmp":false,"gif_animated":false,"jpg":true,"png":true,"tiff":false,"transparent_png_alpha":false,"transparent_png_index":false,"svgt_1_1":false,"svgt_1_1_plus":false,"greyscale":false,"gif":true,"colors":256},"security":{"https_support":true,"https_detectable":false,"phone_id_provided":false},"bearer":{"max_data_rate":9,"wifi":false},"storage":{"max_deck_size":4096,"max_url_length_in_requests":0,"max_url_length_homepage":0,"max_url_length_bookmark":0,"max_url_length_cached_page":0,"max_no_of_connection_settings":0,"max_no_of_bookmarks":0,"max_length_of_username":0,"max_length_of_password":0,"max_object_size":0},"object_download":{"downloadfun_support":false,"directdownload_support":false,"inline_support":false,"oma_support":true,"ringtone":false,"ringtone_3gpp":false,"ringtone_midi_monophonic":false,"ringtone_midi_polyphonic":false,"ringtone_imelody":false,"ringtone_digiplug":false,"ringtone_compactmidi":false,"ringtone_mmf":false,"ringtone_rmf":false,"ringtone_xmf":false,"ringtone_amr":false,"ringtone_awb":false,"ringtone_aac":false,"ringtone_wav":false,"ringtone_mp3":false,"ringtone_spmidi":false,"ringtone_qcelp":false,"ringtone_voices":1,"ringtone_df_size_limit":0,"ringtone_directdownload_size_limit":0,"ringtone_inline_size_limit":0,"ringtone_oma_size_limit":0,"wallpaper":false,"wallpaper_max_width":0,"wallpaper_max_height":0,"wallpaper_preferred_width":0,"wallpaper_preferred_height":0,"wallpaper_resize":"none","wallpaper_wbmp":false,"wallpaper_bmp":false,"wallpaper_gif":false,"wallpaper_jpg":false,"wallpaper_png":false,"wallpaper_tiff":false,"wallpaper_greyscale":false,"wallpaper_colors":2,"wallpaper_df_size_limit":0,"wallpaper_directdownload_size_limit":0,"wallpaper_inline_size_limit":0,"wallpaper_oma_size_limit":0,"screensaver":false,"screensaver_max_width":0,"screensaver_max_height":0,"screensaver_preferred_width":0,"screensaver_preferred_height":0,"screensaver_resize":"none","screensaver_wbmp":false,"screensaver_bmp":false,"screensaver_gif":false,"screensaver_jpg":false,"screensaver_png":false,"screensaver_greyscale":false,"screensaver_colors":2,"screensaver_df_size_limit":0,"screensaver_directdownload_size_limit":0,"screensaver_inline_size_limit":0,"screensaver_oma_size_limit":0,"picture":false,"picture_max_width":0,"picture_max_height":0,"picture_preferred_width":0,"picture_preferred_height":0,"picture_resize":"none","picture_wbmp":false,"picture_bmp":false,"picture_gif":false,"picture_jpg":false,"picture_png":false,"picture_greyscale":false,"picture_colors":2,"picture_df_size_limit":0,"picture_directdownload_size_limit":0,"picture_inline_size_limit":0,"picture_oma_size_limit":0,"video":false,"video_real_media_8":false,"video_real_media_9":false,"video_real_media_10":false,"video_3gpp":false,"video_3gpp2":false,"video_mp4":false,"video_wmv":false,"video_mov":false,"video_max_frame_rate":0,"video_max_width":0,"video_max_height":0,"video_qcif":false,"video_sqcif":false,"video_preferred_width":0,"video_preferred_height":0,"video_df_size_limit":0,"video_directdownload_size_limit":0,"video_inline_size_limit":0,"video_oma_size_limit":0,"video_vcodec_h263_0":false,"video_vcodec_h263_3":false,"video_vcodec_h264":"none","video_vcodec_mpeg4":false,"video_acodec_amr":false,"video_acodec_awb":false,"video_acodec_aac":false,"video_acodec_aac_ltp":false,"video_acodec_qcelp":false},"drm":{"oma_v_1_0_forwardlock":true,"oma_v_1_0_combined_delivery":false,"oma_v_1_0_separate_delivery":false},"mms":{"receiver":false,"sender":false,"mms_max_size":0,"mms_max_height":0,"mms_max_width":0,"built_in_recorder":false,"built_in_camera":false,"mms_jpeg_baseline":false,"mms_jpeg_progressive":false,"mms_gif_static":false,"mms_gif_animated":false,"mms_png":false,"mms_bmp":false,"mms_wbmp":false,"mms_amr":false,"mms_wav":false,"mms_midi_monophonic":false,"mms_midi_polyphonic":false,"mms_midi_polyphonic_voices":0,"mms_spmidi":false,"mms_mmf":false,"mms_mp3":false,"mms_evrc":false,"mms_qcelp":false,"mms_ota_bitmap":false,"mms_nokia_wallpaper":false,"mms_nokia_operatorlogo":false,"mms_nokia_3dscreensaver":false,"mms_nokia_ringingtone":false,"mms_rmf":false,"mms_xmf":false,"mms_symbian_install":false,"mms_jar":false,"mms_jad":false,"mms_vcard":false,"mms_vcalendar":false,"mms_wml":false,"mms_wbxml":false,"mms_wmlc":false,"mms_video":false,"mms_mp4":false,"mms_3gpp":false,"mms_3gpp2":false,"mms_max_frame_rate":0},"j2me":{"j2me_cldc_1_0":false,"j2me_cldc_1_1":false,"j2me_midp_1_0":false,"j2me_midp_2_0":false,"doja_1_0":false,"doja_1_5":false,"doja_2_0":false,"doja_2_1":false,"doja_2_2":false,"doja_3_0":false,"doja_3_5":false,"doja_4_0":false,"j2me_jtwi":false,"j2me_mmapi_1_0":false,"j2me_mmapi_1_1":false,"j2me_wmapi_1_0":false,"j2me_wmapi_1_1":false,"j2me_wmapi_2_0":false,"j2me_btapi":false,"j2me_3dapi":false,"j2me_loctapi":false,"j2me_nokia_ui":false,"j2me_motorola_lwt":false,"j2me_siemens_color_game":false,"j2me_siemens_extension":false,"j2me_heap_size":0,"j2me_max_jar_size":0,"j2me_storage_size":0,"j2me_max_record_store_size":0,"j2me_screen_width":0,"j2me_screen_height":0,"j2me_canvas_width":0,"j2me_canvas_height":0,"j2me_bits_per_pixel":0,"j2me_audio_capture_enabled":false,"j2me_video_capture_enabled":false,"j2me_photo_capture_enabled":false,"j2me_capture_image_formats":"none","j2me_http":false,"j2me_https":false,"j2me_socket":false,"j2me_udp":false,"j2me_serial":false,"j2me_gif":false,"j2me_gif89a":false,"j2me_jpg":false,"j2me_png":false,"j2me_bmp":false,"j2me_bmp3":false,"j2me_wbmp":false,"j2me_midi":false,"j2me_wav":false,"j2me_amr":false,"j2me_mp3":false,"j2me_mp4":false,"j2me_imelody":false,"j2me_rmf":false,"j2me_au":false,"j2me_aac":false,"j2me_realaudio":false,"j2me_xmf":false,"j2me_wma":false,"j2me_3gpp":false,"j2me_h263":false,"j2me_svgt":false,"j2me_mpeg4":false,"j2me_realvideo":false,"j2me_real8":false,"j2me_realmedia":false,"j2me_left_softkey_code":0,"j2me_right_softkey_code":0,"j2me_middle_softkey_code":0,"j2me_select_key_code":0,"j2me_return_key_code":0,"j2me_clear_key_code":0,"j2me_datefield_no_accepts_null_date":false,"j2me_datefield_broken":false},"flash_lite":{"flash_lite_version":"","fl_wallpaper":false,"fl_screensaver":false,"fl_standalone":false,"fl_browser":false,"fl_sub_lcd":false}}

JSON Track

Request

{"apikey":"00000000000000000000000000000000","User-Agent":"MOT-V51","ipaddress":"96.215.44.9","options":"geoip,wml_ui,xhtml_ui,markup,cache,display,security,bearer,object_download,drm,streaming,mms,j2me,sms,sound_format","HTTP_HOST":"192.168.1.30","HTTP_ACCEPT_LANGUAGE":"en-us,en;q=0.5","HTTP_REFERER":"http:\/\/192.168.1.30\/test.php?action=detect","REQUEST_URI":"\/test.php?action=track"}

Reply

{"message":"OK"}