• About Us
  • Blog
  • Basket
  • Account
  • Sign In
  •  

Cloud API

Using JavaScript API with 51Degrees cloud

Match

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/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 that to detect a device with.
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 https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/match?user-agent=iphone

Get a match object with all of the matched device's values.

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/match?user-agent=iphone&Values=HardwareVendor+HardwareModel

Gets a match object with only HardwareVendor and HardwareModel values. This makes the response considerably smaller.

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/match?user-agent=OperaMobi&X-OperaMini-Phone-UA=iphone&Values=HardwareVendor+HardwareModel

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/profile?id=15364

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/profilevalues

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/profilevalues?profileid=15364

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/values

Gets all values in the dataset as an array of value objects.

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/values?propertyname=HardwareVendor

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/value?name=Apple&propertyname=HardwareVendor

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/properties

Gets all properties in the dataset as an array of property objects.

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/properties?componentname=HardwarePlatform

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/property?name=HardwareVendor

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/components

Description

Gets all components in the dataset.

Parameters

None.

Response

An array of components.

Example Urls

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/components

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/component?name=HardwarePlatform

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/publisheddate

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/nextupdatedate

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

GET https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/datasetname

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"
}