Using JavaScript API with 51Degrees cloud
Match
Description
Uses the User-Agent parameter to perform a detection, getting the profile ids and a list of values.
Parameters
| Name | Type | Description |
|---|---|---|
| User-Agent | string | The useragent used to detect a device. |
| Values | string |
A list of property names to get values of. Items in the list should be separated by a '+' and are case sensitive. If a 'Values' parameter isn't provided all values will be returned. e.g. Values=Id+HardwareVendor will only return a value for Id and HardwareVendor. |
An unlimited number of other headers can also be provided. We encourage users to send all the headers from the device with their request as User-Agent does not always have all the information available. It also allows us to improve our detection algorithm.
Response
Match .
Example Urls
Get a match object with all of the matched device's values.
Gets a match object with only HardwareVendor and HardwareModel values. This makes the response considerably smaller.
Other headers can also be included. Here is X-OperaMini-Phone-Ua that is sent by mobile Opera browsers. Including this header can improve detection accuracy.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists the properties required. --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/match?user-agent=" + ua + "&Values=\ HardwareVendor+\ HardwareModel+\ DeviceType+\ ScreenPixelsHeight+\ ScreenPixelsWidth+\ SupportsPhoneCalls" ); <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var match = JSON.parse(xmlhttp.responseText); var text = "" document .getElementById( "id01" ).innerHTML =\ "UserAgent:" + ua + "</br>" + "DeviceType:" + match.Values.DeviceType + "</br>" + "Vendor:" + match.Values.HardwareVendor + "</br>" + "Model:" + match.Values.HardwareModel + "</br>" + "ScreenPixelsHeight:" + match.Values.ScreenPixelsHeight + "</br>" + "ScreenPixelsWidth:" + match.Values.ScreenPixelsWidth + "</br>" + "SupportsPhoneCalls:" + match.Values.SupportsPhoneCalls; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Remarks
Error Codes
- 403 - the licence key is invalid.
Profile
Description
Gets a profile with the given id.
Parameters
| Name | Type | Description |
|---|---|---|
| Id | int | The id of the profile to get. |
Response
Profile .
Example Urls
Gets a profile object for profile 15364.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists the properties required. --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/profile?id=15364" ) <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var profile = JSON.parse(xmlhttp.responseText); document .getElementById( "id01" ).innerHTML = "Profile Id: " + profile.Id + "</br>" + "Name: " + profile.Name + "</br>" + "Component Name: " + profile.ComponentName; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Error codes
- 403 - the licence key is invalid.
- 404 - a profile with the given id does not exist.
Profile Values
Description
Gets all the values mapped to a given profile.
Parameters
| Name | Type | Description |
|---|---|---|
| ProfileId | int | The id of the profile of values to get. |
Response
An array of values .
Example Urls
Gets all the values for the profile as an array of value objects.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists the properties required. --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/profilevalues?profileid=15364" ); <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var profilevalues = JSON.parse(xmlhttp.responseText); var text = "" for (index = 0 ; index < profilevalues.length; ++ index){ text += (profilevalues[index].PropertyName) + ":" + (profilevalues[index].Name) + "</br>" ; } document .getElementById( "id01" ).innerHTML = text; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Error codes
- 403 - the licence key is invalid.
- 404 - a profile with the given id does not exist.
Values
Description
Gets all values for a given property in the dataset. If a property is not specified all values will be returned.
Parameters
| Name | Type | Description |
|---|---|---|
| PropertyName | string | The name of the property to get values from. The name is case-sensitive. If not specified all values will be returned. |
Response
An array of values .
Example Urls
Gets all values in the dataset as an array of value objects.
Gets all values in the dataset that belongs to the HardwareVendor property as an array of value objects.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists the properties required. --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/values?propertyname=HardwareVendor" ) <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var values = JSON.parse(xmlhttp.responseText); var text = "" for (index = 0 ; index < values.length; ++ index){ text += (values[index].Name) + "</br>" ; } document .getElementById( "id01" ).innerHTML = text; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Error codes
- 403 - the licence key is invalid.
- 404 - a property with the given name does not exist.
Value
Description
Gets a given value.
Parameters
| Name | Type | Description |
|---|---|---|
| PropertyName | string | The name of a property the value must belong to. Case-senstive. |
| Name | string | The name of the value. Case-senstive. |
Response
Value .Example Urls
Gets the value in the dataset that belong to the HardwareVendor property with the name Apple as a value object.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists the properties required. --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/value?name=Apple&propertyname=HardwareVendor" ) <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var value = JSON.parse(xmlhttp.responseText); document .getElementById( "id01" ).innerHTML = "PropertyName: " + value.PropertyName + "</br>" + "Name: " + value.Name + "</br>" + "Description: " + value.Description; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Error codes
- 403 - the licence key is invalid.
- 404 - a value with the given name and property combination does not exist.
Properties
Description
Gets all properties for a given component in the dataset. If a component is not specified, all properties will be returned.
Parameters
| Name | Type | Description |
|---|---|---|
| ComponentName | string | The name of the component to get properties from. Case-sensitive. If not specified all properties will be returned. |
Response
An array of properties .
Example Urls
Gets all properties in the dataset as an array of property objects.
Gets all properties in the dataset that belongs to the HardwarePlatform component as an array of property objects.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists the properties required. --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/properties?componentname=HardwarePlatform" ); <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var properties = JSON.parse(xmlhttp.responseText); var text = "" for (index = 0 ; index < properties.length; ++ index){ text += (properties[index].Name) + ":" + (properties[index].Description) + "</br>" ; } document .getElementById( "id01" ).innerHTML = text; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Remarks
Error codes
- 403 - the licence key is invalid.
- 404 - a component with the given name does not exist.
Property
Description
Gets the property with the given name.
Parameters
| Name | Type | Description |
|---|---|---|
| Name | string | The name of the property to get. |
Response
Property .Example Urls
Gets the HardwareVendor property as a property object.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists the properties required. --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/property?name=HardwareVendor" ); <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var property = JSON.parse(xmlhttp.responseText); document .getElementById( "id01" ).innerHTML = "Name: " + property.Name + "</br>" + "Description: " + property.Description + "</br>" + "ComponentName: " + property.ComponentName; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Remarks
Error codes
- 403 - the licence key is invalid.
- 404 - a property with the given name does not exist.
Components
Description
Gets all components in the dataset.
Parameters
None.
Response
An array of components .
Example Urls
Gets all components in the dataset as an array of component objects.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists all components --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/components" ); <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var components = JSON.parse(xmlhttp.responseText); document .getElementById( "id01" ).innerHTML = "HardwarePlatform: " + components[ 0 ].DefaultProfileId + "</br>" + "SoftwarePlatform: " + components[ 1 ].DefaultProfileId + "</br>" + "BrowserUA: " + components[ 2 ].DefaultProfileId + "</br>" + "Crawler: " + components[ 3 ].DefaultProfileId; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Remarks
Error codes
- 403 - the licence key is invalid.
Component
Description
Gets the component with the given name from the dataset.
Parameters
| Name | Type | Description |
|---|---|---|
| Name | string | The name of the component to get. |
Response
Component .Example Urls
Gets the HardwarePlatform component as a component object.
Example Code
JavaScript
<!DOCTYPE html> <html> <body> <p id= "id01" ></p> <script> var xmlhttp = new XMLHttpRequest(); <!-- Insert Cloud key here. --> var key = "Licence Key" <!-- Receives UserAgent from clients connection. --> var ua = window .navigator.userAgent; <!-- Lists the component required. --> var url = ( "https://cloud.51degrees.com/api/v1/" + key + "/component?name=HardwarePlatform" ); <!-- Parses the JSON object from our cloud server and returns values. --> xmlhttp.onreadystatechange = function (){ if ( xmlhttp.readyState == 4 && xmlhttp.status == 200 ){ var component = JSON.parse(xmlhttp.responseText); document .getElementById( "id01" ).innerHTML = "HardwarePlatform: " + component.DefaultProfileId; } } <!-- Sends request to server. --> xmlhttp.open( "GET" , url, true ); xmlhttp.send(); </script> </body> </html>
Remarks
Error codes
- 403 - the licence key is invalid.
- 404 - a component with the given name does not exist.
Published Date
Description
Gets the date that the dataset was published on.
Parameters
None.
Response
Date .
Remarks
Error codes
- 403 - the licence key is invalid.
Next Update Date
Description
Gets when the dataset is scheduled to updated. 51Degrees Cloud cache headers are based on this date. Local caches should be cleared on this date.
Parameters
None.
Response
Date .
Remarks
Error codes
- 403 - the licence key is invalid.
Dataset Name
Description
Gets the name of the dataset that is serving the licence key. This is a quick way of validating the type of licence key that is being used.
Parameters
None.
Response
String .
Remarks
Error codes
- 403 - the licence key is invalid.
Cloud Response Types
Match
Properties
| Name | Type | Description |
|---|---|---|
| MatchMethod | string | Gets the match method used in this detection. Values can be 'exact', 'numeric' and 'closest'. |
| Difference | int | Gets the Difference value in this detection. |
| DetectionTime | double | Gets the time spent detecting the device in milliseconds. |
| Values | dictionary of string arrays | Gets the values of this detection. Values is essentially a JSON object where all of its members are named after property names that are a string array of values for that property. |
| DataSetName | string | Gets the name of the data set used in this detection. |
| Published | date | Gets when the dataset used in this detection was published. |
| SignaturesCompared | int | Gets the signature compared in this detection. |
| ProfileIds | int[] | Gets the ProfileIds found in this detection. The index of a profile id is the component id of the profile. |
| Useragent | string | Gets the user agent of the matching device with irrelevant characters removed. |
| TargetUseragent | string | Gets the useragent used in this detection. For debugging. |
Example
{
"MatchMethod"
:
"Exact"
,
"Difference"
:
0
,
"DetectionTime"
:
0
,
"Values"
: {
"HardwareModel"
: [
"iPhone"
],
"HardwareVendor"
: [
"Apple"
],
"Id"
: [
"12280-19826-18431-18092"
]
},
"DataSetName"
:
"PremiumV3"
,
"Published"
:
"2015-01-21T00:00:00Z"
,
"SignaturesCompared"
:
0
,
"ProfileIds"
: {
"1"
:
12280
,
"2"
:
19826
,
"3"
:
18431
,
"4"
:
18092
},
"Useragent"
:
"Mozilla\/5.0 (iPhone; CPU iPhone OS 6_1 Mac OS X) AppleWebKit\/ Gecko) Version\/6.0 Mobile Safari\/853"
,
"TargetUseragent"
:
"Mozilla\/5.0 (iPhone; CPU iPhone OS 6_1_3 like Mac OS X) AppleWebKit\/536.26 (KHTML, like Gecko) Version\/6.0 Mobile\/10B329 Safari\/8536.25"
}
Component
Properties
| Name | Type | Description |
|---|---|---|
| Name | string | Gets the name of the component. |
| DefaultProfileId | int | Gets the profile id that should be used for this component if a better one cannot be found for detection. |
Example
{
"Name"
:
"HardwarePlatform"
,
"DefaultProfileId"
:
15364
}
Property
Properties
| Name | Type | Description |
|---|---|---|
| Name | string | Gets the name of the property. |
| DisplayOrder | byte | Gets the DisplayOrder. |
| IsMandatory | bool | Gets if this property is mandatory and is guraranteed to have a value for every profile. |
| IsObsolete | bool | Gets if the property is obsolete. Obsolete properties should not be used in new projects. |
| IsList | bool | Gets if this property can have multiple values. |
| Show | bool | Gets if the values the property returns are relevant to configuration user interfaces and are suitable to be selected from a list of table of options. This is different from ShowValues. |
| ShowValues | bool | Gets if property's values should be shown in the 51Degrees property dictionary. |
| Description | string | Gets the description for this property. |
| Category | string | Gets the category of this property. |
| Url | string | Gets a url for this property explaining more about it. |
| ValueType | string | Gets the type of this property. |
| Maps | string[] | Gets dataset types this property belongs to. |
| ComponentName | int | Gets the id of the component this property belongs to. |
Example
{
"Name"
:
"HardwareVendor"
,
"DisplayOrder"
:
4
,
"IsMandatory"
:
true
,
"IsObsolete"
:
false
,
"IsList"
:
false
,
"Show"
:
true
,
"ShowValues"
:
true
,
"Description"
:
"The company that manufactures the device or primarily sells it. May return 'Unknown'."
,
"Category"
:
"Name"
,
"Url"
:
null
,
"ValueType"
:
"string"
,
"Maps"
: [
"Premium"
,
"Enterprise"
,
"PremiumV3"
],
"ComponentName"
:
"HardwarePlatform"
}
Value
Properties
| Name | Type | Description |
|---|---|---|
| PropertyName | string | Gets the name of the property this value belongs to. |
| Name | string | Gets the name of this value. |
| Description | string | Gets the description of this value. |
| Url | string | Gets a url for this value that explains more about it. |
Example
{
"PropertyName"
:
"IsMobile"
,
"Name"
:
"True"
,
"Description"
:
"This device is mobile."
,
"Url"
:
null
}
Profile
Properties
| Name | Type | Description |
|---|---|---|
| Id | int | Gets the id of the profile. |
| Name | string | Gets the name of the profile. |
| ComponentName | int | Gets the name of the component this profile belongs to. |
Example
{
"Id"
:
15364
,
"Name"
:
"Emulator\/Desktop"
,
"ComponentName"
:
"HardwarePlatform"
}