Flow calculator API

Programmatic interface for oil, water, and gas flow rates from pressure drop on a Venturi tube. Uses the same physical model as the Flow from pressure drop tab in the calculator.

Getting an API token

API access is provided via an individual token. Tokens are issued by the administrator after reviewing your request.

To request a token, go to Contact (site registration required) and send a message including:

organization or project name;
integration purpose (SCADA, reports, external service, etc.);
expected request rate;
contact email for correspondence.

After approval you will receive the token by email. Keep it like a password: do not publish it in open code or share with third parties.

Purpose

The API solves the direct problem: from measured pressure drop ΔP, MPFM geometry, PVT parameters, and GOR it determines component flow rates.

Typical scenarios:

automatic calculation from telemetry (ΔP, pressure, temperature);
batch processing of measurement archives;
integration into corporate systems and partner applications;
verification of meter readings with model calculations.

The API provides flow calculation from ΔP only. Venturi range sizing, inverse ΔP from rates, Pro sizing analysis, and basic converters are available in the web calculator.

Protocol

Method	`POST`
URL	`https://gvfcalc.ru/api.php`
Format	JSON (`Content-Type: application/json`)
Response encoding	UTF-8

Authorization

Pass the token in one of these ways:

header Authorization: Bearer <TOKEN> — recommended
header X-API-Token: <TOKEN>
field token in JSON body

Without a valid active token the server responds with 401.

Rate limiting

No more than one calculation per 5 seconds per token. When exceeded — response 429 with Retry-After header and retry_after_seconds in the body.

Input parameters

Parameters are sent in the POST request body (JSON).

Parameter	Type	Required	Description
`d_inlet_mm`	number	yes	MPFM inlet diameter, mm (> 0)
`d_throat_mm`	number	yes	MPFM throat diameter, mm (> 0, less than inlet)
`dP_kPa`	number	yes	Pressure drop, kPa (> 0)
`P_MPa_gauge`	number	yes	Operating (gauge) pressure, MPa (> 0)
`T_C`	number	yes	Operating temperature, °C
`WLR`	number	yes	Water cut (water fraction), 0 ≤ WLR < 1
`GOR`	number	yes	Gas-oil ratio, std m³/t (≥ 0)
`rho_oil_std`	number	yes	Oil density at std. conditions (20 °C), kg/m³
`rho_water`	number	yes	Water density, kg/m³
`composition`	array(14)	*	Gas molar composition, % (preferred; Peng–Robinson PVT)
`rho_gas_std`	number	*	Gas density at std. conditions, kg/m³ (if no composition; then Z = 1)
`wc_invers`	number	no	Phase inversion water cut, 0–1 (default 0.5)
`sigma_oil_gas`	number	no	σ oil/gas, N/m (default 0.25)
`sigma_water_gas`	number	no	σ water/gas, N/m (default 0.07)
`mu_gas_pas`	number	no	Gas viscosity, Pa·s (default 1.235×10⁻⁵)
`mu_water_pas`	number	no	Water viscosity, Pa·s (default 1×10⁻³)
`mu_oil_pas`	number	no	Oil viscosity, Pa·s (default 0.02)

* Provide either composition (14 values) or rho_gas_std.

Order in <code>composition</code>: methane, ethane, propane, n-butane, iso-butane, n-pentane, iso-pentane, n-hexane, iso-hexane, H₂S, nitrogen, CO₂, oxygen, other.

Success response (code 200)

{
  "ok": true,
  "result": {
    "m_oil_t_day": 7.46,
    "m_water_t_day": 49.5,
    "m_gas_t_day": 5.98,
    "m_total_t_day": 62.9,
    "Q_oil_m3day": 8.48,
    "Q_liq_m3day": 57.9,
    "Q_gas_std_day": 6717.9,
    "Q_gas_wrk_day": 1620.4,
    "GVF_inlet_pct": 96.5,
    "alpha_throat_pct": 97.1,
    "flow_regime": "annular",
    "Rs": 0.0,
    "rho_liq": 990.1,
    "rho_gas_work": 3.9,
    "ctrl": { "Z": 0.94, "M_gas": 21.4, "rho_oil_work": 880.2 }
  },
  "meta": {
    "token_label": "Партнёр X",
    "rate_limit_seconds": 5,
    "calculated_at": "2026-06-22T21:00:00+03:00"
  }
}

The result block contains mass and volumetric phase rates, inlet GVF, flow regime, and auxiliary values in ctrl (compressibility Z, densities, viscosity, etc.).

Error codes

Code	Meaning
400	Input validation errors (list in `errors` field)
401	Token missing, invalid, or disabled
405	Method other than POST used
422	Calculation did not converge — no solution for given inputs
429	Rate limit exceeded (1 request / 5 s)

Request example

With gas composition (14 components):

curl -X POST https://gvfcalc.ru/api.php \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{
    "d_inlet_mm": 48,
    "d_throat_mm": 30,
    "dP_kPa": 3.91,
    "P_MPa_gauge": 0.411,
    "T_C": 18.5,
    "WLR": 0.857,
    "GOR": 900.5,
    "rho_oil_std": 901,
    "rho_water": 1003,
    "composition": [76.921,9.358,4.595,1.751,1.478,0.226,0.360,0.181,0.093,0.147,2.697,1.548,0.645,0.000]
  }'

Without gas composition (Z = 1):

curl -X POST https://gvfcalc.ru/api.php \
  -H "X-API-Token: ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{
    "d_inlet_mm": 48,
    "d_throat_mm": 30,
    "dP_kPa": 6.3,
    "P_MPa_gauge": 2.5,
    "T_C": 24.7,
    "WLR": 0.17,
    "GOR": 69,
    "rho_oil_std": 850,
    "rho_water": 1010,
    "rho_gas_std": 0.89
  }'

Integration recommendations

Do not store the token in client-side JavaScript on public pages — call the API from your backend proxy.
For batch processing, wait at least 5 seconds between requests with the same token (or use a queue).
Code 422 means no solution for the input combination — handle this in your application logic.
Recommended HTTP client timeout is 30–60 seconds (iterative calculation).
API results match the Flow from pressure drop tab with the same inputs.

For access and token requests, use the Contact section.