The MKS Web Application Programming Interface (API)
Applicability: Cranium, Synapse (core version 0324+)

The MKS Web Application Programming Interface (API) enables a software application (the API client) to access and utilize the functions contained within another software application (the API server). The Web Server Editions of both Cranium and Synapse can function as API servers, providing physical property data and estimates to web pages, web applications, and other externally developed applications.

The MKS Web API uses Javascript-Object-Notation (JSON) to transfer information between Cranium or Synapse and your client application. For example, your webpage can send a JSON-formatted request to Cranium and Cranium will send a JSON-formatted response back to your webpage. The form of a request is:

mkswebapi.com/process?request={json object}

The form of the {json object}, used in both requests and responses, is based on a hierarchy of four objects:

request - entity - property - datum

Note that for uniformity, all values are entered and returned as strings. For example, a chemical's identifier, i.e., its name, could be "Acetone", its boiling point data value "329.15", its boiling point estimated value "329.73745177614", both in units of "K".

Request Object

The request object is the top-level object containing various key-value pairs and an array of entity objects. The figures to the right show an example request and its corresponding response. (The entities array is detailed below and removed here for clarity.)

The attributes that are specified in the request json are:

  • Type: [ required, string] this attribute indicates the type of processing to perform, e.g., 'Get Entities' or 'Get Units'. Processing the 'Get Requests' request type returns a response containing all request types.
  • Arguments: [dependent, object] additional input information required for certain request types. This attribute is a JSON object, entered as a set of keyword-value pairs. (Refer to documentation on each request type for details on required arguments.)
Request JSON
Response JSON

The additional attributes returned in the response json are:

  • Processor: [output, string] a string that denotes the application used to process requests. The string contains the application's name and version information.
  • MKSJSONID: [output, string] this is unique string used to identify that the JSON request was processed by a Molecular Knowledge Systems' application.
  • Date: [output, string] the date and time when the response json was generated.
  • Entities: [input/output, array] an array of entity objects. (See below for details.)

The following list details the request types that can currently be processed by the MKS Web Interface. Each of these request types is discussed further below.

  • Hello: a simple request that returns some basic information about the running api. This request type is typically used when initially developing a frontend for the api. (see below)
  • Get Request Types: returns all of the request types (i.e., the types described in this list) that can be currently processed by the api. (see below)
  • Get Entity Types: the api processes different entity types, e.g., chemicals, mixtures, techniques, references. An entity's type typically must be specified when requesting data and estimates. This request type returns all entity types processed by the api. (see below)
  • Get Entities: returns the identifier, i.e., name, of each entity in the current knowledge base. An entity's identifier is required for requesting its physical property values. (see below)
  • Get Properties: returns all the properties handled by the api. These properties are typically required when making additional requests for data and estimates. (see below)
  • Get Status Values: physical property values are categorized by their status type. For example, some values represent data values while others represent estimated values. A property's status value often must be specified when requesting data and estimates. This request type returns all status values processed by the api. (see below)
  • Get Units: returns all units for a given physical property or units category. For many request types, you must specify the units for input temperatures, pressure, and compositions. (see below)
  • Get Values: returns the physical property data and estimated for a given entity. This is probably the most commonly used request type. However, to make this request, you must typically specify an entity's type, an entity's identifier, a property name, and a status value. All inputs you can obtain by making the other requests documented in this list. (see below)

Each of these request types is explained and demonstrated in the sections below.

Request: Hello

The 'Hello' request is a simple request typically used to test connectivity with the api. Only the request type must be included in the json.

Example: press the process button at the end of this paragraph to show the original request json sent to the api, a link for executing the api call, and the response json received from the api.

Request JSON
MKS Web API Link
Response JSON
Request: Get Request Types

Every request must have a "Type" value. The 'Get Request Types' request returns all of the request types that can be currently processed by the api.

Example: press the process button at the end of this paragraph to show the original request json sent to the api, a link for executing the api call, and the response json received from the api. Note that the response returns data for the '#Virtual Property' and the '#Virtual Entity'. These are just placeholders used to maintain the uniformity of the JSON response.

Request JSON
MKS Web API Link
Response JSON
Request: Get Entity Types

Every input entity must have an "EntityType" value. The 'Get Entity Types' request returns all of the entity types that can be currently processed by the api.

Example: press the process button at the end of this paragraph to show the original request json sent to the api, a link for executing the api call, and the response json from the api. Note that the response returns data for the '#Virtual Property' and the '#Virtual Entity'. These are just placeholders used to maintain the uniformity of the JSON response.

Request JSON
MKS Web API Link
Response JSON
Request: Get Entities

To retrieve physical property data and estimates from the api, you must make a request containing an entity's identifier. The 'Get Entities' request retrieves the identifiers (names) of all entities in the api's 'selected knowledge base. The request retrieves only entity identifiers for a single entity type. You must specify this entity type in the request's arguments object.

Process one of the examples below to show the original request json sent to the api, a link for executing the api call, and the response json received from the api. Note that the difference between requests is that a different entity type is specified in the request's 'Arguments' object. (The list of entity types can be obtained by processing the Get Entity Types request.)

Chemicals: retrieve the names of all chemicals in the current knowledge base. Note the request's arguments object contains the key-value 'Chemical'.

Mixtures: retrieve the names of all mixtures in the current knowledge base. Note the request's arguments object contains the key-value 'Mixture'.

References: retrieve the names of all references in the current knowledge base. Note the request's arguments object contains the key-value 'Reference'.

Techniques: retrieve the names of all estimation techniques in the current knowledge base. Note the request's arguments object contains the key-value 'Technique'.

Request JSON
MKS Web API Link
Response JSON
Request: Get Entities - Pattern Matching

To retrieve a chemical's data values, you must know the chemical's name. Unfortunately, chemicals often have more than one name. For example, 1-butanol is also often called n-butanol, n-butyl alcohol, or just butanol. Several attempts at creating unique names have been undertaken over the years by organizations such as Elsevier Publishing (beilstein numbers), the American Chemical Society (cas numbers), the European Union (ec numbers), and the Flavor Extract Manufacturers Association (fema numbers). Unfortunately, as this brief listing shows, there are many 'unique' names.

To address this issue of multiple identifiers, the api enables you to add qualifiers to the Get Entities request. These qualifiers are added as arguments of the request and thus take the form of an attribute-value pair.

The attributes that are allowed are listed here:

  • Beilstein Number
  • CAS Number
  • EC Number
  • Formula
  • Identifier
  • Synonym

The value of the attribute-value pair is a string that may contain more or more 'pattern-matching' characters. These characters are:

  • $ - the dollar sign will match zero or more characters in an input value. For example, the value "$butanol" will match 1-butanol, n-butanol, cyclobutanol, and several more names.
  • ? - the question mark will match one character in an input value. For example, the value "1-hex?ne" will match 1-hexene and 1-hexyne.

These pattern-matching characters can be combined and used multiple times in a value. For example, the value "$hex?ne" will match cyclohexane, 2-methyl-1-hexene, 3-methylhexane, and several more chemicals.

You may use more than one pattern-matching attribute pair. For example you might combine the pair "Identifier": "$but$" with "Synonym": "$alcohol$" to retrieve a list of butyl alcohols.

Synonym: retrieve the identifiers of all chemicals that have a synonym which matches the input value. Note it is possible that more than one chemical will have the same synonym.

Synonym, common identifier: retrieve the identifiers of all chemicals that have a synonym that matches "$2060". (This is a shorthand term for "FEMA Number: 2060".)

EC Number: retrieve the identifier of the chemical (there should be only one) which has the EC Number equal to "202-859-9".

Formula: retrieve the identifier of the chemicals whose chemical formula contains carbon, nitrogen, and oxygen, i.e., 'C$N$O$'. Note that pattern matching chemical formula is not the best method for finding matching chemical structures. That is because the pattern "C$" will match C8 as well as Cl.

Mixtures: retrieve the identifiers of mixtures containing water as a component. This example shows that pattern-matching works for other entity types as well.

Techniques: retrieve the identifiers of estimation techniques that contain 'Joback' in their name. This is another example showing that pattern-matching works for other entity types as well.

Combinations: more than one pattern-matching attribute-value pair can be added to a request. This example retrieves combines the pair "Identifier": "$but$" with the pair "Synonym": "$alcohol$" to retrieve a list of butyl alcohols.

Request JSON
MKS Web API Link
Response JSON
Request: Get Properties

To retrieve physical property data and estimates from the api, you must make a request containing one or more properties. The 'Get Properties' request retrieves the names of all properties the api can currently process. Because certain properties, e.g., synonym, cannot be estimated, the api maintains two property lists: one for data properties and one for estimates properties. These two lists are maintained for each entity type. The request retrieves only property names for a single entity type and property type. This property type argument can be either 'Data' or 'Estimates'.

Process one of the examples below to show the original json request sent to the api, a link for executing the api call, and the response from the api. The differences between the requests are the entity type for which properties are requested and the type of property being requested. (Note that the list of entity types can be obtained by processing the Get Entity Types request.)

Chemical Data Properties: retrieves the names of all chemical properties that are of the 'Data' property type. Note that the request json uses its Arguments attribute to specify the entity type and property type.

Chemical Estimates Properties: retrieves the names of all chemical properties that are of the 'Estimates' property type. Comparing the response json of this request to the data property request performed in the previous example, we see that several properties, e.g., formula and notes, are not included.

Mixture Estimates Properties: retrieves the names of all mixture properties that are of the 'Estimates' property type. This is the same request as the previous example but using the 'Mixture' entity type.

Request JSON
MKS Web API Link
Response JSON
Request: Get Status Values

There are often many values reported for a particular physical property value. For example, the boiling point of Acetone has been reported to be 56.0, 56.29, and 56.18 C. All of these values can be stored within an MKS Knowledge Base. Of these values, one is a status value of 'Active' and the other two are assigned a status value of 'Passive'. These status values are assigned when values are entered into a knowledge base and must be specified when requesting values from a knowledge base.

Example: press the process button at the end of this paragraph to show the original request json sent to the api, a link for executing the api call, and the response json from the api. Note that the response returns data for the '#Virtual Property' and the '#Virtual Entity'. These are just placeholders used to maintain the uniformity of the JSON response.

To show how the Status Value is used to retrieve different values, several additional examples are provided below.

Active Status: requests data that have an 'Active' status. Active status values can be considered values recommended by the api. Note how only one value for Acetone's boiling point was returned.

Passive Status: requests data that have a 'Passive' status. Passive data is considered 'good' but not perhaps 'best'. Note how several values are returned for Acetone's boiling point.

Estimated: requests data that have an "Estimated" status. This status value denotes values that have been previously estimated and are already stored within the current knowledge base. Typically, these values were estimated using Cranium or Synapse before the knowledge base was deployed. Note the datum's reference is the name of the estimated technique used to generate the estimated value.

New Estimate: this status value instructs the api to generate a new physcial property estimate, even if one is already present in the selected knowledge base. Note that the new estimate generated using this status value is different than the estimated returned by the 'Estimated' status value. (This is becuase the estimate stored in the knowledge base, i.e., the value with the 'Estimated' status value, was estimated using a different estimation technique. Comparing the reference of this request's datum with that of the 'Estimated' status value request shows this difference.)

Request JSON
MKS Web API Link
Response JSON
Request: Get Units

For many request types, you must specify the units for input temperatures, pressures, and compositions. You may also specify that the data and estimates returned from a request be in certain units. The 'Get Units' request returns all units for all properties or a specified property.

When making a Get Units request, you must supply a value for the UnitsType argument. This argument can be set to either 'AllPropertyUnits' or 'PropertyUnits'.

AllPropertyUnits: this request returns all possible units for every physical property currently processed by the api. (The response json can be quite large.) Note that the request's Arguments object has the key value of 'PropertyType' set to the value of 'AllPropertyUnits'.

PropertyUnits: this request returns all possible units for each specified physical property. Thus, you must also include one or more property objects in your request. You must also set the request's Argument's 'PropertyType' key to a value of 'PropertyUnits'.

Request JSON
MKS Web API Link
Response JSON
Request: Get Values

The 'Get Values' request is probably the most commonly used request type. To make this request, you must typically specify an entity's type, an entity's identifier, a property name, and a status value. To generate new estimates, you may also have to specify one or more datum values containing values for temperature, pressure, and composition.

Conceptually, you can think of a Get Values request as a form. You first add information you know on the form. You then submit the form to the api. The api returns the form to you with the missing information, or much of it, filled in.

The following examples demonstrate various Get Values requests. Click on the 'process' link at the end of each paragraph to see the request json and the response json.

Chemical Property Values: returns a data value and a newly estimated value for the boiling point of 1,2-Dichlorobenzene. Note that the only difference between the two property objects is their status values.

New Mixture Estimates: creates a new mixture and estimates the activity coefficients of component 1 at several compositions. Note that you must specify the names of the new mixture's components as datum objects within a 'Components' property object.

Estimates from Chemical Structure: the api can receive chemical structure information in SMILES notation or MolFile format. This request estimates several properties for OC(=O)CCCCCCCCCCC, which is the chemical structure of lauric acid. Note that the chemical's structure is given in the request json as an 'Active' status value datum and the properties to be estimated have status values of 'New Estimate'. This instructs the api to 'cache' the input, active data. See caching data values below for more details on this capability.

To properly form Get Values requests, it is helpful to understand entities, properties, and data. The following sections document each of these objects.

Request JSON
MKS Web API Link
Response JSON
Entity Object: Attributes

For most Get Values requests you will need to specify some information about an entity. For example, to request a chemical's critical pressure data value, you must specify the chemical's identifier attribute. To request a mixture's estimated liquid density, you must specify the mixture's identifier and list of components attributes. The following list details these attributes:

  • Identifier: [ required, string] the entity's name or other value used to uniquely identify the entity. The Get Entities request can be used to retrieve a list of entities of a specific entity type.
  • EntityType: [ required, string] one of the entity types handled by the api. The Get Entity Types request can be used to retrieve a list of entity types.
  • Properties: [input/output, array] an array of property objects. These objects are used as input for certain request types and returned as output for other request types. (See below for details.)

The following examples demonstrate various ways in which entity objects are used in requests. Click on the 'process' link at the end of each paragraph to see the request json and the response json. These examples also show how the form of a request json is fairly consistent - the requests are all similar in form.

Chemical Data: returns property data and estimates for the entity with the identifier 'Toluene' which is a 'Chemical' entity type.

Mixture Data: returns property data and estimates for the entity with the identifier '1-Butanol + Methanol' which is a 'Mixture' entity type.

Structure Estimate: returns estimates for a new chemical entity given its molecular structure in SMILES notation. Note that when estimating physical properties for a new chemical, you must use an entity identifier beginning with the phrase '#Virtual Chemical'. This entity refers to a chemical in the current knowledge base that contains no data, i.e., a new chemical.

New Mixture Estimate: returns estimates for a new quaternary mixture entity given the names of its four components. (The four components must be added as active data.) Note that when estimating physical properties for a new mixture, you must use an entity identifier beginning with the phrase '#Virtual Mixture'. This entity refers to a mixture in the current knowledge base that contains no data, i.e., a new mixture.

Reference Data: returns property data for the entity with the identifier 'Joback + Reid (1987)' which is a 'Reference' entity type.

Technique Data: returns property data for the entity with the identifier 'Cp,s,298: Hurst + Harrison [MKS]' which is a 'Technique' entity type.

Request JSON
MKS Web API Link
Response JSON
Property Object: Attributes

For most Get Values requests you will need to specify some information about one or more properties. For example, to request a chemical's liquid density data values, you must specify the chemical entity and the liquid density property object. Specifically, the property object's name, status value, and component. The following list details these attributes:

  • Name: [ required, string] the property's name. The Get Properties request can be used to retrieve a list of property names of a specific entity type and property type.
  • Status: [ required, string] the status value of the property data being requested. See documentation on the Get Status Values request for an explanation of status values.
  • Component: [ required, string] certain physical properties of mixtures, e.g., the activity coefficient, fugacity coefficient, diffusion coefficient, and partial molar properties, are actually properties of the mixture's components. For example, a mixture containing chemical 1 and chemical 2 does not have an activity coefficient. Chemical 1 in the mixture 1 + 2 has an activity coefficient and chemical 2 in the mixture 1 + 2 activity coefficient.
  • Thus to retrieve data and estimates for these mixture physical properties, you must set the component's index in the property object's Component attribute. Two important notes: 1) the component index is 'zero-based', e.g., in a binary mixture the components are 0 and 1; 2) although the component index is an integer, it is always entered as a string value for consistency, e.g., "0" or "1".
  • Only a few mixture properties are 'component dependent'. Thus, for most properties you will simply specify a value of "0" for the component attribute.
  • Data: [input/output, array] an array of datum objects. These objects are used as input for certain request types and returned as output for other request types. (See below for details.)

When the api retrieves physical property data, it returns those data in their original units, i.e., the units in which they were reported in their source reference. For example, if you retrieve liquid density data for 1,1,1-Trichloroethane, some data will have the temperature in 'C' and the value in 'g/cm 3' while other data will have the temperature in 'K' and the value in 'kg/m 3'.

When the api generates physical property estimates, these values are returned in 'standard units'. These are just units selected for each physical property used for internal api calculations.

If you wish to have physical property values returned in other units, you can specify these desired units in the property object. The api will then automatically perform units conversion before the values are returned. (Note that certain units conversions require knowledge of a chemical's or mixture component's molecular weight, e.g., converting g/cm 3 to g-mol/cm 3. The api will automatically retrieve or estimate the required molecular weight when needed. However, there can be instances in which the molecular weight cannot be obtained. In these cases the returned values will have a comment indicated a 'units conversion error' occurred. This error can be corrected by specifying a molecular weight or requesting data be returned in other units which do not require a mass-molar units conversion.)

The attributes that specify the units in which physical property values should be returned are detailed in the following list. Note that you can use the Units Request to obtain the list of units available for any particular physical property.

  • TemperatureUnits: [input] specifies the units in which temperature values are returned. Note that these units are used only for temperatures, not for 'temperature-like' property values, e.g., boiling point or melting point. The units for these property values must be specified using the ValueUnits attribute. (See the property units conversion example below.)
  • PressureUnits: [input] specifies the units in which pressure values are returned. Note that these units are used only for pressures, not for 'pressure-like' property values, e.g., critical pressure or vapor pressure. The units for these property values must be specified using the ValueUnits attribute. (See the property units conversion example below.)
  • CompositionUnits: [input] specifies the units in which composition values are returned. Since composition values can be either molar-base or mass-based, you might receive a 'units conversion error' if a chemical's molecular weight cannot be obtained. See the discussion above for additional details on how to correct these errors.
  • ValueUnits: [input] specifies the units in which the physical property's values are returned.

Several additional attributes are available for the property object:

  • ManualTechnique: [input] typically api estimations are run in an 'automatic mode'. In this mode, the api examines input information, e.g., temperatures, pressures, and chemical structure, and then selects the best estimation technique. You can use this attribute to specify the name of the estimation technique that should be used instead of using the automatic process.
  • DataType: [output] this attribute is being used for future development.

The following examples demonstrate various ways in which property objects are used in requests. Click on the 'process' link at the end of each paragraph to see the request json and the response json.

Data and Estimates: returns property data and estimates for 1-Octanol.

Status Values: returns property data having various status values for Benzene.

Units Conversion: returns Bubble Point data for the mixture 'Acetone + Methanol' in their original units and converted into a set of selected units. Note that this request json has two property objects that refer to the same property. Using such 'duplicate' objects is often a good way to obtain values for comparison, e.g., between data and estimates, or between different estimation techniques.

Manual Techniques: returns estimates for the critical pressure of 2-Ethoxyethyl acetate using several manually selected techniques and one performed in automatic mode. (The automatic mode estimate is the one without a manual technique entry.)

Component Index: returns estimates for the activity coefficients of each component in a new, ternary mixture. Note that the property objects differ only in their value of the component attribute. (Remember that this value is 'zero-based'.)

Request JSON
MKS Web API Link
Response JSON
Data Caching

When the api processes a 'Get Values' request it conceptually processes the request twice. During the first processing, the api parses and temporarily stores all Active data found in the request json into the current knowledge base. For example, if the request json has Active boiling point data, these values will be temporarily stored, or cached, in the current knowledge base. During the second processing, all other data and estimated will be retrieved.

This two step processing enables you to add values to the knowledge base, albeit temporarily, which can then be used in all subsequent estimations. The examples below demonstrate the advantage of this approach. They both estimate the vapor pressure at 85C of 2-Hexanol. The literature value for this property is 11.466 kPa.

Estimated Boiling Point: in this example the request json simply adds the chemical's SMILES string to the current knowledge base. The SMILES string is cached because it is given with an Active status value. The api then generates a new estimate for the vapor pressure at 85C which requires also estimating the unknown boiling point value. (Note the value of the resulting estimate.)

Cached Boiling Point: in this example the request json adds the chemical's SMILES string to the current knowledge base as well as the known value for the chemical's normal boiling point, 139.89C. Both of these values are cached because both are given with Active status values. The api then generates a new estimate for the vapor pressure at 85C. In this case, a value for the normal boiling point does not need to be estimated. (Note the value of the resulting estimate.)

Comparing the two vapor pressure estimates, we find that the estimate that used the known value for the boiling point was more accurate than the estimated that used an estimated value for the boiling point. You can use data caching in this manner to take advantage of all the data you have on unknown chemicals and mixtures.

Request JSON
MKS Web API Link
Response JSON
Datum Object: Attributes

The Datum is the basic value-containing object used to exchange information with the MKS Web API. A Datum can have a variety of different attributes depending upon its containing Property object. The most common datum attributes are listed here:

  • Value: [input/output, string] the value of the datum may be a string, integer, or floating point number. (Note that all of these values are presented as a string in both request and response jsons.) If you assign a value to the Value attribute then must also assign a value to the ValueUnits attribute unless the containing property is dimensionless.
  • ValueAccuracy: [output, string] a non-negative number that represents the accuracy of the datum's value.
  • ValueUnits: [input/output, string] the units in which the datum's value and value accuracy are given.
  • Temperature: [input/output, string] the temperature at which the datum value was or will be determined. If you assign a value to the Temperature attribute then must also assign a value to the TemperatureUnits attribute.
  • TempAccuracy: [output, string] a non-negative number that represents the accuracy of the datum's temperature value.
  • TempUnits: [input/output, string] the units in which the datum's temperature and temperature accuracy are given.
  • Pressure: [input/output, string] the pressure at which the datum value was determined. If you assign a value to the Pressure attribute then must also assign a value to the PressureUnits attribute.
  • PresAccuracy: [output, string] a non-negative number that represents the accuracy of the datum's pressure value.
  • PresUnits: [input/output, string] the units in which the datum's pressure and pressure accuracy are given.
  • XValues: [input/output, string] an array containing the composition of each component in a mixture entity. If you assign a value to the XValues attribute then must also assign a value to the XUnits attribute.
  • XAccuracies: [output, string] containing the accuracy of each composition value.
  • XUnits: [input/output, string] the units in which the datum's compositions and composition accuracies are given.
  • Reference: [output, string] the name of the source of the datum's value. This source can be a reference's identifier or a technique's identifier.
  • Comment: [output, string] additional information regarding this datum. If an error occurred during processing, its value will be assigned to this attribute.

The following examples demonstrate various ways in which datum objects are used in requests. Click on the 'process' link at the end of each paragraph to see the request json and the response json.

Datum Attributes: returns vapor viscosity data values the mixture 'Methane + n-Decane'. The returned data have values for many attributes described above.

State Variables: returns property vapor pressure estimates for 1,1-Dichloro-2,2,2-trifluoroethane. Datum objects are used to specify the state variables, temperatures for this example, at which estimates are generated. Note that these state variables can be input in whatever units are convenient.

Request JSON
MKS Web API Link
Response JSON
Example Usage

Interacting with the MKS Web API typically involves three steps: 1) creating a request json; 2) processing the request with the api; 3) parsing the response json for values. We have found that javascript functions can be very useful in performing each of these steps.

Javascript objects and array can be easily created:

Request json can be processed by the api using javascript's fetch function:

Finally, the response json can again be easily parsed using javacript:

Related Documentation
Topic Description
Getting Started using Cranium provides a quick tour of Cranium's capabilities including physical property estimation and a discussion of structure editing.
Getting Started using Synapse provides a quick tour of Synapse's capabilities including examples of chemical product design.