API - Introduction and Instruction

Besides providing the current web-based access to fluid engineering software, we have recently designed and developed Web API that allows users to integrate our calculation modules into their desktop software, mobile apps, and even websites.

For instance, in the SCADA (Supervisory Control and Data Acquisition) system, the user requires the information of the fluid compositions, temperature and pressure in the pipelines to calculate the fluid properties and phase behavior in order to make the necessary adjustments on the production operations. Thus, to design and develop specified software is a must, which is time consuming and costly. Using our Web API, the user is able to integrate the calculation modules quickly and seamlessly into their systems.

Instructions for API Use

Please follow the steps below for using the Web API provided by this site:

  1. After register and login, you may click ”API key” tab in “My Account” under your user name.
  2. The top half of this screen is a list of your API Key. You may click “Create API” to generate an API Key. You can only generate prescribed number of API Keys. The bottom half of this screen is your API Key usage history.
  3. You may delete the key you generated from the list, and then re-generate a new API Key.
  4. After generating an API Key, you may integrate it into your own program. Please refer to the Sample Code below.
  5. Each API Key has some usage quota by default. For now, each API Key can be used up to 20 times each day. If you need more computing times, please contact us.
  6. In using API, the calculation options may differ slightly from the ones on the web page.
  7. The property units of API calling are benchmark units, and the composition is in mole percent. You may check the benchmark units for various types of values from https://www.fluidmodelinggroup.com/Tools/fmgUnits
  8. You may select the defined components provided by this site. Should you require your own defined components, please contact us.
  9. Currently, two modules, Phase Envelope which includes Quality Lines and Cricondentherm Hydrocarbon Dew Point and Two Phase P-T flash calculation are available for use. More API applications are under development.

Description of API

The API call address is at https://www.fluidmodelinggroup.com/api. The calling method is POST, and encoded in UTF-8. The Content-Type must be JSON. The data item key name should be capitalized. The detailed descriptions are given below.

  • API_KEY: required, string, the API Key you generated in ”My Account”. Missing or invalid of this item will lead failure in calling API.
  • COMMAND: required, the requested function from the website. Two options,
    • “help”: help information
    • “calc”: calculation
  • MODULE：required, string, calculation module, valid when COMMAND=CALC. Two modules are available right now:
    • “phaseenvelope”: Phase Envelope which includes Quality Lines and Cricondentherm Hydrocarbon Dew Point
    • “ptflash”: Two Phase P-T flash calculation
  • COMPONENTS: required, string array, names of the components used in calculation. Please note that different modules have different selectable components. Please check it from our website. A fluid characterization will be performed if a plus fraction is included in the components.
  • COMPOSITION: required, floating point array, the mole fraction of each component.
  • CONFIG: optional, options of basic calculation methods. The default options will be chosen if this item is missing. The options are:
    • EOS: options of equations of state.
      • PR78: Peng-Robinson 1978 (default)
      • PR76: Peng-Robinson 1976
      • PR90: Peng-Robinson (Magoulas & Tassios Revision) 1990
      • SRK: Soave-Redlich-Kwong 1972
      • ALS: Adachi-Lu-Sugie 1983
      • PT: Patel-Teja 1982
      • VPT: Valderrama-Patel-Teja 1990
      • SW: Schmidt-Wenzel 1980
      • YL: Yu-Lu, 1987
      • MDG: Modified Du-Guo 1989
      • TB: Trebble-Bishnoi 1987
      • SMTD: Salim Modified Trebble-Bishnoi 1994
    • VIS: options of viscosity calculation.
      • 2REF: 2-Reference Corresponding States (default)
      • 1REF: 1- Reference Corresponding States
      • LBC: Lohrenz-Bray-Clark
      • PREOS: Peng-Robinson EoS method
  • CHARACTERIZATION: optional. (The default mothed will be used if a plus fraction is included and no specification is given).
    • DISTRIB_FUNC: Distribution function.
      • PED: Pedersen 1988 (default)
      • WHIT: Whitson 1988
      • MODPED: modified Pedersen 2001 mothed
    • PROP_CORR: correlations of critical properties.
      • PED: Pedersen 1988 (default)
      • RDT: Riazi-Daubert(1980)-Thomasen(1986)
      • LK: Lee-Kesler(1976)
      • CE: Cavett(1964)-Edminstor(1958)
      • LKE: Lee-Kesler(1976)-Edminstor(1958)
      • TLK: Twu(1984)-Lee-Kesler(1976)
      • WSD: Winn(1957)-Sim-Daubert (1980)
      • RAS95: Riazi-Al-Sahhaf (1995)
      • RAS98: Riazi-Al-Sahhaf (1998)
    • PSEUDO_LUMP: lumping mothed of pseudo-components.
      • MASS: by weight (default)
      • MOLE: by mole
      • GAUSS: Gaussian mothed
      • EQUAL: in equivalent
    • PSEUDO_COUNT: integer, number of pseudo-components, default=5.
    • PLUS_MW: float, molecular weight of pseudo-component, can be specified by user.
    • PLUS_DENS: float, density of pseudo-component, can be specified by user.
  • PARAM: optional, calculation parameter. The content has a different structure depending on the calculation module.
    • In phaseenvelope, PARAM is optional. Without PARAM, only phase envelope is calculated. With PARAM, up to 9 quality lines will be calculated. The item “QUALITYLINE_GAS_FRAC”, array, is the percentage of gas contents, with its value between 0 to 100.
    • In ptflash, PARAM is required, which includes an item, “PT_PAIR”, array, a pair of temperatures and pressures. For example, [{"P":60, "T":400}, {“P”:80,”T”:450}], meaning, flash calculations will be performed at pressure=60bar, temperature=400K, and pressure=80bar, temperature=450K, respectively. Up to 9 PT pairs are accepted for calculation.

API Results

The calculation results will be returned in format of JSON, which include 3 parts:

  • “status”: indicating whether the calculations success or fail, “SUCCESS” or “FAILED”
  • “message”: returned message. If success, the message indicates the calculation time and time consumed. If fail, the message gives the reason of failure.
  • “result”: calculation results, which differ in structure according to the module.

If a serious error occurs during the calculation, a message, “Calling FMG API Calculation error” will be sent out.

Sample Code

Take Python and C # as examples.

Python:


import json,urllib.request
httpClient = None
try:
    data = {"API_KEY" : "B9E96302C25A40C49491C3BF......39D060D4D9C2B44ABEB405A93197AF8866", #Your API Key
    "COMMAND":"calc", #"help", #
    "MODULE":"phaseenvelope", #"ptflash", #
    "CONFIG":{
        "EOS":"PR76"
    },
    "COMPONENTS":['C1','C2','C3','C7+'], 
    "COMPOSITION":[0.2,0.5,0.1,0.2],
    #"CHARACTERIZATION":{
    #   "DISTRIB_FUNC":"MODPED",
    #   "PROP_CORR": "RDT",
    #   "PLUS_MW": 200,
    #   "PLUS_DENS": 0.95,
    #   "PSEUDO_LUMP": "mole",
    #   "PSEUDO_COUNT": 3
    #}
    #,"PARAM": {
    #   "QUALITYLINE_GAS_FRAC":[10,20,50]   #Quality line for phaseenvelope
    #   "PT_PAIR": [{"P":60, "T": 400}]
    #   }    
    }   
    para = json.dumps(data).encode('utf8')
    req=urllib.request.Request("https://www.fluidmodelinggroup.com/api", data=para, headers={'content-type': 'application/json'})   
    r=urllib.request.urlopen(req)   
    print(r.status)
    print(r.reason)
    txt = r.read()
    f=open('pythonResult.txt','wb')
    f.write(txt)
    f.close()
    print(txt)
except Exception(e):
    print(e)
finally:
    if httpClient:
        httpClient.close()

C#:


using Newtonsoft.Json;
using System.Net;
…

string apiurl = "https://www.fluidmodelinggroup.com/api";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(apiurl);
httpWebRequest.ContentType = "application/json; charset=utf-8";
httpWebRequest.Method = "POST";
httpWebRequest.Accept = "application/json; charset=utf-8";
using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{
    string _data = JsonConvert.SerializeObject(new
    {
        API_KEY = "B9E96302C25A40C49491C3BF......39D060D4D9C2B44ABEB405A93197AF8866", //Your API Key
        COMMAND = "calc", //"help", //
        MODULE = "phaseenvelope", //"ptflash", //
        CONFIG = new
        {
            EOS = "PR90"
        },
        COMPONENTS = new[] { "C1", "C2", "C3", "C7+" },
        COMPOSITION = new[] { 0.2, 0.5, 0.1, 0.2 }, 
        CHARACTERIZATION = new {
            DISTRIB_FUNC = "MODPED",
            PROP_CORR = "RDT",
            PLUS_MW = 200,
            PLUS_DENS = 0.95,
            PSEUDO_LUMP = "mole",
            PSEUDO_COUNT = 3
        }
        ,PARAM = new {
            QUALITYLINE_GAS_FRAC = new[] { 10, 50 }  //Quality line for phaseenvelope
            //PT_PAIR = new[] { new { P = 60, T = 400 }, new { P = 80, T = 450 } }
            }
    });
    streamWriter.Write(_data);
    streamWriter.Flush();
    streamWriter.Close();
    var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
    using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
    {
        string result = streamReader.ReadToEnd();
        textBox1.AppendText(result);
    }
}