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

Cloud API

Using NET 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 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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/match?user-agent=iphone&values=Id+HardwareVendor+HardwareName");
	dynamic match = Newtonsoft.Json.Linq.JObject.Parse(json);
	return match;
}

This sample requires the Newtonsoft.Json package.

@using (var webClient = new System.Net.WebClient())
{
  string json = webClient.DownloadString(String.Format(
  "https://cloud.51degrees.com/api/v1/{0}/match?user-agent={1}&values=HardwareVendor+DeviceType",
  "YOUR KEY HERE",
  HttpUtility.UrlEncode(Request.UserAgent)));

  dynamic match = Newtonsoft.Json.Linq.JObject.Parse(json);
  SortedList<string, string[]> values = Newtonsoft.Json.JsonConvert.DeserializeObject<SortedList<string, string[]>>(match.Values.ToString());
  string[] hvValues;
  if (values.TryGetValue("HardwareVendor", out hvValues))
  {
    foreach (string s in hvValues)
    {
	<h4>
		Hardware vendor:
		@s
	</h4>
    }
  }
  else
  {
    <h4>Match did not return any results for HardwareVendor.</h4>
  }

  if (values.TryGetValue("DeviceType", out hvValues))
  {
    foreach (string s in hvValues)
    {
	<h4>
		Hardware vendor:
		@s
	</h4>
    }
  }
  else
  {
    <h4>Match did not return any values for DeviceType.</h4>
  }
}

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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/profile?id=15364");
	dynamic profile = Newtonsoft.Json.Linq.JObject.Parse(json);
	return profile;
}

This sample requires the Newtonsoft.Json package.

@using (var webClient = new System.Net.WebClient())
{
  Profile p;
  string json = webClient.DownloadString(String.Format(
  "https://cloud.51degrees.com/api/v1/{0}/profile?id=15364",
  "LICENCE_KEY_HERE",
  HttpUtility.UrlEncode(Request.UserAgent)));
  p = Newtonsoft.Json.JsonConvert.DeserializeObject<Profile>(json);

  <h3>Profile: </h3>
  <h4>ID: @p.Id</h4>
  <h4>Name: @p.Name</h4>
  <h4>Component name: @p.ComponentName</h4>
}

Where Profile is the following class:

public class Profile
{
  public int Id { get; set; }
  public string Name { get; set; }
  public string ComponentName { get; set; }
}

Remarks

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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/profilevalues?profileid=15364");
	dynamic profileValues = Newtonsoft.Json.Linq.JArray.Parse(json);
	return profileValues;
}

This sample requires the Newtonsoft.Json package.

The following code prints a table of all values mapped to profile with ID 15364.

@using (var webClient = new System.Net.WebClient()) {
  Value[] val;
  string json = webClient.DownloadString(String.Format(
  "https://cloud.51degrees.com/api/v1/{0}/profilevalues?profileid=15364",
  "LICENCE_KEY_HERE"
  ));
  val = Newtonsoft.Json.JsonConvert.DeserializeObject<Value[]>(json);

  //List all values mapped to speciffic profile
  <table>
    <tr>
      <th>Property name</th>
      <th>Value</th>
      <th>Description</th>
      <th>URL</th>
    </tr>
    @foreach (Value v in val)
    {
    <tr>
      <td>@v.PropertyName</td>
      <td>@v.Name</td>
      <td>@v.Description</td>
      <td>@v.Url</td>
    </tr>
    }
  </table>
}

Value class is listed below.

public class Value
{
  public string PropertyName { get; set; }
  public string Name { get; set; }
  public string Description { get; set; }
  public string Url { get; set; }
}

Remarks

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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/values?propertyname=HardwareVendor");
	dynamic values = Newtonsoft.Json.Linq.JArray.Parse(json);
	return values;
}

This sample requires the Newtonsoft.Json package.

The following examples displays all Values associated with HardwareVendor property. Please note: you can request values without specifying the property, however it will take a signifficant amount of time to load the object of that size.

@using (var webClient = new System.Net.WebClient())
{
  Value[] val;
  string json = webClient.DownloadString(String.Format(
  "https://cloud.51degrees.com/api/v1/{0}/values?propertyname=HardwareVendor",
  "LICENCE_KEY"
  ));
  val = Newtonsoft.Json.JsonConvert.DeserializeObject<Value[]>(json);

  //List all values mapped to speciffic profile
  <table>
    <tr>
      <th>Property name</th>
      <th>Value</th>
      <th>Description</th>
      <th>URL</th>
    </tr>
    @foreach (Value v in val)
    {
    <tr>
      <td>@v.PropertyName</td>
      <td>@v.Name</td>
      <td>@v.Description</td>
      <td>@v.Url</td>
    </tr>
    }
  </table>
}

Value class is as follows:

public class Value
{
  public string PropertyName { get; set; }
  public string Name { get; set; }
  public string Description { get; set; }
  public string Url { get; set; }
}

Remarks

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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/value?name=Apple&propertyname=HardwareVendor");
	dynamic value = Newtonsoft.Json.Linq.JObject.Parse(json);
	return value;
}

This sample requires the Newtonsoft.Json package.

@using (var webClient = new System.Net.WebClient())
{
  Value val;
  string json = webClient.DownloadString(String.Format(
  "https://cloud.51degrees.com/api/v1/{0}/value?name=Apple&propertyname=HardwareVendor",
  "LICENCE_KEY"
  ));
  val = Newtonsoft.Json.JsonConvert.DeserializeObject<Value>(json);

  <h3>@val.PropertyName</h3>
  <h3>@val.Name</h3>
  <h3>@val.Description</h3>
  <h3>@val.Url</h3>
}

Value class is as follows:

public class Value
{
  public string PropertyName { get; set; }
  public string Name { get; set; }
  public string Description { get; set; }
  public string Url { get; set; }
}

Remarks

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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/properties?componentname=HardwarePlatform");
	dynamic properties = Newtonsoft.Json.Linq.JArray.Parse(json);
	return properties;
}

This sample requires the Newtonsoft.Json package.

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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/property?name=HardwareVendor");
	dynamic properties = Newtonsoft.Json.Linq.JObject.Parse(json);
	return properties;
}

This sample requires the Newtonsoft.Json package.

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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/components");
	dynamic components = Newtonsoft.Json.Linq.JArray.Parse(json);
	return components;
}

This sample requires the Newtonsoft.Json package.

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

C#

using (var webClient = new System.Net.WebClient())
{
	string json = webClient.DownloadString("https://cloud.51degrees.com/api/v1/*LICENCE_KEY*/component?name=HardwarePlatform");
	dynamic component = Newtonsoft.Json.Linq.JObject.Parse(json);
	return component;
}

This sample requires the Newtonsoft.Json package.

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