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:
The form of the {json object}, used in both requests and responses, is based on a hierarchy of four objects:
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".
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:
The additional attributes returned in the response json are:
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.
Each of these request types is explained and demonstrated in the sections below.
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.
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.
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.
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'.
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:
The value of the attribute-value pair is a string that may contain more or more 'pattern-matching' characters. These characters are:
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$O$N$'. 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.
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.
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.)
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'.
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.
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:
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.
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:
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.
Several additional attributes are available for the property object:
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'.)
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.
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:
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.
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:
| 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. |