APIv3 Site Calls

Detect a Device

/apiv3/site/detect/{site id}.json

Perform a device detection for this site profile. Parameters : headers. Returns : messagestatus plus device information.

Example Command

curl -u "api-username:api-secret" --digest -H "Content-Type: application/json" -X POST -d '{"user-agent":"NokiaN95"}' http://api.handsetdetection.com/apiv3/site/detect/22.json
Pro Tip : Remember to set the Content-Type: application/json http header in your request, also change the '22' in the URL to your Site ID.

Example Detection Reply

{
    "hd_specs":{
        "general_aliases":[],
        "general_battery":["Li-Ion 950 mAh","BL-5F"],
        "general_cpu":["Dual ARM 11","332Mhz"],
        "design_sidekeys":["Volume","Camera","Multimedia"],
        "display_other":[],
        "memory_internal":["160MB","64MB RAM","256MB ROM"],
        "memory_slot":["microSD","8GB","128MB"],
        "network":["GSM850","GSM900","GSM1800","GSM1900","UMTS2100","HSDPA2100","Infrared port","Bluetooth 2.0","802.11b","802.11g","GPRS Class 10","EDGE Class 32"],
        "media_camera":["5MP","2592x1944"],
        "media_secondcamera":["QVGA"],
        "media_videocapture":["VGA@30fps"],
        "media_videoplayback":["MPEG4","H.263","H.264","3GPP","RealVideo 8","RealVideo 9","RealVideo 10"],
        "media_audio":["MP3","AAC","AAC+","eAAC+","WMA"],
        "media_other":["Auto focus","Video stabilizer","Video calling","Carl Zeiss optics","LED Flash"],
        "features":["Unlimited entries","Multiple numbers per contact","Picture ID","Ring ID","Calendar","Alarm","To-Do","Document viewer","Calculator","Notes","UPnP","Computer sync","VoIP","Music ringtones (MP3)","Vibration","Phone profiles","Speakerphone","Accelerometer","Voice dialing","Voice commands","Voice recording","Push-to-Talk","SMS","MMS","Email","Instant Messaging","Stereo FM radio","Visual radio","Dual slide design","Organizer","Word viewer","Excel viewer","PowerPoint viewer","PDF viewer","Predictive text input","Push to talk","Voice memo","Games"],
        "connectors":["USB","miniUSB","3.5mm Headphone","TV Out"],
        "general_vendor":"Nokia",
        "general_model":"N95",
        "general_platform":"Symbian",
        "general_platform_version":"9.2",
        "general_browser":"",
        "general_browser_version":"",
        "general_image":"nokia^n95.gif",
        "general_type":"Mobile",
        "general_language":"",
        "design_formfactor":"Dual Slide",
        "design_dimensions":"99 x 53 x 21",
        "design_weight":"120",
        "design_antenna":"Internal",
        "design_keyboard":"Numeric",
        "design_softkeys":"2",
        "display_type":"TFT",
        "display_color":"Yes",
        "display_colors":"16M",
        "display_size":"2.6\"",
        "display_x":"240",
        "display_y":"320",
        "general_eusar":"0.50"
    },
    "class":"Mobile",
    "message":"OK",
    "status":0
}

This example includes different detection options. If no options are passed then the API assumes you want the default options which are the device specs from the v3 schema (hd_specs). You can override this by passing custom options. To query the v2 schema include the ‘legacy’ option and any legacy capability groups you require.

The geoip option will return geoip information.

Example Command : Passing different options

curl -u "api-username:api-secret" --digest -H "Content-Type: application/json" -X POST -d '{"user-agent":"NokiaN95","options":"legacy,product_info,geoip","ipaddress":"64.34.165.180"}' http://api.handsetdetection.com/apiv3/site/detect/22.json

Example Detection Reply

{
    "product_info":{
        "brand_name":"Nokia",
        "can_assign_phone_number":"true",
        "can_skip_aligned_link_row":"true",
        "device_claims_web_support":"true",
        "device_os":"Symbian OS",
        "device_os_version":"9.2",
        "has_qwerty_keyboard":"false",
        "is_tablet":"false",
        "is_wireless_device":"true",
        "marketing_name":"",
        "mobile_browser":"Safari",
        "mobile_browser_version":"",
        "model_extra_info":"",
        "model_name":"N95",
        "nokia_edition":"3",
        "nokia_feature_pack":"0",
        "nokia_series":"60",
        "pointing_method":"joystick",
        "release_date":"2008_january",
        "uaprof":"http:\/\/nds1.nds.nokia.com\/uaprof\/NN95-1r100.xml",
        "uaprof2":"",
        "uaprof3":"",
        "unique":"true",
        "ununiqueness_handler":"",
        "hd_image1":"nokia^n95.gif"
    },
    "display":{
        "columns":"25",
        "dual_orientation":"true",
        "max_image_height":"273",
        "max_image_width":"234",
        "physical_screen_height":"57",
        "physical_screen_width":"43",
        "resolution_height":"320",
        "resolution_width":"240",
        "rows":"15"
    },
    "geoip":{
        "country":"United States",
        "city":"Herndon",
        "countrycode":"US",
        "region":"Virginia",
        "regioncode":"VA",
        "latitude":38.9266,
        "longitude":-77.3936,
        "isp":"Peer 1 Network",
        "company":"ServerBeach"
    },
    "class":"Mobile",
    "message":"OK",
    "status":0
}

FetchSpecs (Ultimate Detection Only)

/apiv3/site/fetchspecs/{site id}.json

Download handset database (used in conjunction with fetchtrees, our detection ruleset) for performing local device detections. Parameters : headers. Returns : message, status plus device matching trees (if successful).

You'll need to purchase an Ultimate Detection licence to have access to this data locally on your own servers.

Example Fetchspecs Command

curl -u "api-username:api-secret" --digest -H "Content-Type: application/json" http://api.handsetdetection.com/apiv3/site/fetchspecs/8500.json

Example Fetchspecs Reply : No Permission

{
    "message":"API : AuthMethod digest. Error : You do not have permission to download this file. Perhaps your licence expired ?",
    "status":229
}

Example Fetchspecs Reply : Success (truncated)

{
    "_notice":{
        "note":"Copyright (c) Teleport Corp Pty Ltd 2012",
        "generated":"2012-02-19 16:28:23",
        "source":"http:\/\/www.handsetdetection.com"
    },
    "devices":[
        {"Device":{
            "_id":"10",
            "hd_specs":{
                "general_vendor":"Samsung",
                "general_model":"VM-A680 (SPH-A680)",
                "general_platform":"",
                "general_platform_version":"",
                "general_browser":"",
                "general_browser_version":"",
                "general_image":"samsung^vma680(spha680).jpg",
                "general_aliases":"",
                "general_eusar":"",
                "general_battery":["Li - Ion  900 mAh"],
                "general_type":"Mobile",
                "general_cpu":"",
                "design_formfactor":"Clamshell",
                "design_dimensions":"83 x 46 x 24",
                "design_weight":"96",
                "design_antenna":"Internal",
                "design_keyboard":"Numeric",
                "design_softkeys":"2",
                "design_sidekeys":"",
                "display_type":"TFT",
                "display_color":"Yes",
                "display_colors":"65536",
                "display_size":"",
                "display_x":"128",
                "display_y":"160",
                "display_other":"",
                "memory_internal":"",
                "memory_slot":"",
                "network":["CDMA800","CDMA1900","AMPS800"],
                "media_camera":["0.3MP VGA"],
                "media_secondcamera":"",
                "media_videocapture":"",
                "media_videoplayback":"",
                "media_audio":"",
                "media_other":"",
                "features":["Exposure control","GPS","White balance","Multi shot","Self-timer","300 entries","Multiple numbers per contact","Picture ID","Ring ID","Calendar","Alarm","To-Do","Calculator","Stopwatch","SMS","Predictive text input (T9)","Games Downloadable","Computer sync","Polyphonic ringtones (32 voices)","Vibration","Voice dialing (Speaker independent)","Voice recording","TTY\/TDD","Internet Browsing WAP 2.0"],
                "connectors":""
            }
        }},{"Device":{
            "_id":"100",
            "hd_specs":{
                "general_vendor":"Samsung",

FetchTrees (Ultimate Detection Only)

/apiv3/site/fetchtrees/{site id}.json

Download matching trees for performing local detections. Parameters : headers. Returns : messagestatus plus device matching trees (if successful). Note : You”ll need to purchase an Ultimate Licence to get access to this data.

Example Fetchtrees Request Headers (FYI)

Host: api.handsetdetection.com
Content-Type: application/json  
Authorization: Digest username="Demo", realm="APIv3", nonce="APIv3", uri="/apiv3/site/fetchtrees/21.json", qop=auth, nc=00000001, cnonce="12345612345612345612345612345612", response="1234569cd4d41c96562f0e974cc06cb1", opaque="APIv3"
Content-length: 2

Example Fetchtrees Command

curl -u "api-usernme:api-secret" --digest -H "Content-Type: application/json" http://api.handsetdetection.com/apiv3/site/fetchtrees/8500.json

Example Fetchtrees Reply : No Permission

{
    "message":"API : AuthMethod digest. Error : You do not have permission to download this file. Perhaps your licence expired ?",
    "status":229
}

Example Fetchtrees Reply : Success (truncated)

{
    "_notice":{
        "note":"Copyright (c) Teleport Corp Pty Ltd 2012",
        "generated":"2012-02-19 16:28:48",
        "source":"http:\/\/www.handsetdetection.com"
    },
    "trees":{
        "user-agent0":{
            "250":{
                "quattrowireless":{
                    "motoroladroidbionic":"35403",
                    "huaweihuaweiu8180":"35435",
                    "pantechadr89954g":"35462",
                    "samsungshwm250l":"35456",
                    "samsungshwm250s":"35439",
                    "samsunggti9000":"15355",
                    "samsungsght589":"35409",
                    "samsungsphd710":"35440",
                    "samsungsphp100":"35428",
                    "htchtcph06130":"35463",
                    "motorolamb501":"9579",
                    "motorolamb612":"35458",
                    "motorolamb865":"35461",
                    "verizondroid2":"15934",
                    "htcadr6330vw":"35446",
                    "kyoceram9300":"35464",
                    "lglgp505v11e":"35441",
                    "motorolacliq":"21243",
                    "toshibaat100":"35430",
                    "htchtcz710e":"35410",
                    "lglgp503v10":"19386",
                    "htcinspire":"19078",
                    "lglgp500h":"35459",
                    "lglgp505":"35443",
                    "lglgp925":"35444",
                    "lglgv909":"35436",
                    "zteracer":"35404",
                    "htchero":"7709",
                    "lgas740":"35457",
                    "lgp505r":"35406",
                    "mb200":"7708"},
                "sonyericsson":{
                    "sonyericssonu20a":"6808"
                },
                "android":{
                    "lguplusandroidwebkitbuild":"2292",
                    "orangesanfranciscobuild":"6898",
                    "olivettiolipad100build":"4761",
                    "milestonext720build":"6060",
                    "skyima630kizarbuild":"6280",
                    "iconiataba100build":"5391",
                    "wowmobilemytouch3g":"6865",
                    "androideeepcbuild":"2880",
                    "logicpdzoom2build":"4252",
                    "movistarlinkbuild":"4352",
                    "onetouch890dbuild":"4861",
                    "onetouch906ybuild":"4670",

Get Started Today

Our free Express / Cloud plan has 20,000 detections per month. No credit card required. Upgrade when you're ready. We also have a free Community Edition for Ultimate Detection, our high performance local detection library, which you can build into community open source projects.


Get Started. Its Free