Read a forecast file
Reads a booked forecast file into decline curves, one per well, reserves category, design and stream.
Read a forecast file
/forecast-sources/readReads a booked forecast file into decline curves, one per well, reserves category, design and stream. rows lists the rows with an issue and warnings what to check. Nothing is stored: POST /forecast-sources saves a read.
Formats
The header picks the format, and options.format overrides it. Numbers are decimals only: 0x1F is a row issue, not 31.
valnav_decline: a Val Nav decline CSV, its six segment templates, Di and Df in percent.valnav_constants: a Val Nav constants CSV of ratios, sent asconstantswith a decline file.novi_arps: Novi's own arps.csv, from POST /exports.combocurve_parameters: a ComboCurve forecast parameters CSV. Seriesbestreads as P50, and wells key on Chosen ID, else INPT ID. Incline and ratio segments are row issues.mosaic_decline: a Mosaic decline CSV saved from its workbook. Di, else Dei, else Desi; ∆ T over Tf; dates as text or spreadsheet serials; ratios decline on the parent's cumulative volume.aries: ARIES import text as Novi's ARIES export writes it, from the production section's OIL, GAS, WTR and CND lines. Ratio, LIN and dated segments are row issues.- It is told by its first two non-blank lines: a well's name in column 1, then PRODUCTION.
- Its lines state their units and have no columns, so
options.unitsandoptions.columnsare 400s with it. - A row's
idis a line's index from 0, blank lines counted. A well name over 200 characters is a row issue that leaves its curves out.
Upload
Send the file as a multipart/form-data file part, with an optional constants part for a Val Nav decline file. Clients limited to JSON send the text as csv and constants_csv.
Workbooks
Either part may be an Excel workbook (.xlsx), read as a CSV of the sheet's stored cell values would be. options.sheet picks the sheet; absent, the first, with a warning when there are more. A constants workbook reads its first sheet.
- Dates are serial numbers in the workbook's own date system: 1900, or 1904 when it says so.
- Formulas read as the values the workbook saved (none is calculated), numbers as stored, unrounded whatever their display format, and booleans as TRUE or FALSE.
- A row with a formula error (#N/A, #DIV/0!) in a column the format reads is left out, with the error in
rows[].issues.
Options
options says how to read the file; see its fields. Condensate reads as oil unless products maps it. In Novi arps.csv, P50 reads as category P50 unless p_levels maps it, and P10 or P90 without a map is left out with a warning.
Include
warning_codes adds each warning's stable code and the fields it names (a product, a count, a unit system), so a client can word it against its own controls. sheets adds a workbook file's sheet and sheets, for a sheet list; a constants workbook isn't listed, and CSV text answers as without it.
Limits
- The 64 MB request body; a body over it is a 413.
- 30,000 curves (past them, a 400 with
details.maxanddetails.count) and 600,000 lines of ARIES text (a 400 withdetails.max). - A workbook: 1,000 zip entries, 32 MB for each part it reads and 64 MB in all, 1,000,000 shared strings, 2,000,000 cells with a value and 500 columns.
- A workbook's reading work, set to hold the server under a second (about 50,000 rows of 13 columns): past it, a 400 with
details.max_work. Save a larger sheet as CSV.
Errors
A 400 naming the fix refuses an .xls or a workbook saved with a password; .xlsm, .xltx and .xlsb; a part declaring a DTD or entities; a damaged workbook; an unknown options.sheet (details.sheets lists the sheets); and options.sheet with CSV text.
Request body
The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.
filestringRequiredFile
The forecast CSV or .xlsx workbook, as a file part; CSV text may also come as a text part, read as UTF-8 (a file part reads Windows-1252 too).
constantsstringOptionalFile
A Val Nav constants CSV or .xlsx workbook, as a file part (CSV also as a text part), read with the Val Nav decline file.
optionsstringOptionalAs options in the JSON body, as JSON text: {"units": "metric"}.
includestringOptionalAs include in the JSON body, as JSON text: ["warning_codes", "sheets"].
csvstringRequiredThe forecast file's text. Where you can, upload the file itself as multipart/form-data instead.
constants_csvstringOptionalA Val Nav constants CSV's text, read with a Val Nav decline file in csv.
optionsobjectOptionalHow to read the file; every member is optional.
ShowHide 8 child fields
formatstringOptionalThe file's format, when its header could read as another; absent, the header decides.
"valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"unitsstringOptionalThe file's unit system; absent, a Val Nav units row or a Mosaic file's header unit labels decide, else imperial (bbl/d, Mcf/d; metric m³/d, e³m³/d).
"imperial""metric"productsobjectOptionalup to 100 keys
A file product (any case and spacing) to the stream it reads as, or skip, as {"CONDENSATE": "skip"}; a ratio product (GOR, OGR, CGR, WOR, WGR) maps only to its own stream or skip.
gas_basisstringOptionalraw or sales gas; absent, sales when the file names sales gas, else raw.
"raw""sales"reserves_categoriesarray of stringsOptionalup to 100 itemsItems 1 to 200 characters
The categories to keep; absent keeps every one.
p_levelsobjectOptionalNovi arps.csv only: the reserves category each P-level reads as, each its own, as {"P10": "1P"}.
ShowHide 3 child fields
P10stringOptionalIts reserves category.
P50stringOptionalIts reserves category; absent, P50.
P90stringOptionalIts reserves category.
columnsobjectOptionalup to 100 keys
A role to the file's header for it, when the file names a column otherwise, as {"uwi": "Well ID"}; a role the format lacks or a header the file lacks is a 400.
sheetstring or integerOptional≥ 01 to 200 characters
An .xlsx file's sheet to read: its name, exact or in any case, or its index from 0, as "Declines" or 0; absent, the first. A sheet the workbook lacks is a 400 with details.sheets, and sheet with CSV text a 400.
includearray of stringsOptionalup to 2 items
warning_codes adds warning_details, each warning's code and fields beside its sentence; sheets adds a workbook's sheet and sheets. Each at most once.
"warning_codes""sheets"
Responses
200 OK
The curves, and the rows with an issue.
formatstringRequiredThe format read.
"valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"detected_fromarray of stringsRequiredThe headers that picked the format; ARIES text gives ["PRODUCTION"], also when options.format named it.
unitsobjectRequiredUnits.
ShowHide 5 child fields
systemstringRequiredThe unit system read.
"imperial""metric"fromstringRequiredWhat set it.
"options""units row""format""default"ratesobjectRequiredThe rate units read, converted to bbl/d and mcf/d.
ShowHide 3 child fields
oilstringRequiredIts rate unit.
gasstringRequiredIts rate unit.
waterstringRequiredIts rate unit.
ratiosobjectRequiredA ratio product to its unit.
rowobject or nullRequiredA Val Nav units row or a Mosaic file's header unit labels, header to unit, or null.
productsobjectRequiredProducts.
ShowHide 3 child fields
foundarray of objectsRequiredEvery product in the file.
ShowHide 2 child fields in each item
valuestringRequiredAs the file has it.
curvesintegerRequired≥ 0
Curves.
mappedarray of objectsRequiredProducts read.
ShowHide 3 child fields in each item
valuestringRequiredThe product.
streamstringRequiredThe stream it reads as.
"oil""gas""water"fromstring or nullRequiredThe parent stream of a ratio.
"oil""gas"
skippedarray of objectsRequiredProducts left out.
ShowHide 2 child fields in each item
valuestringRequiredAs the file has it.
curvesintegerRequired≥ 0
Curves.
gas_basisstringRequiredraw or sales gas.
"raw""sales"reserves_categoriesarray of objectsRequiredEvery reserves category with a curve.
ShowHide 3 child fields in each item
valuestringRequiredAs the file has it.
curvesintegerRequired≥ 0
Curves.
keptbooleanRequiredWhether options.reserves_categories keeps it.
curvesarray of objectsRequiredThe curves read, in file order.
ShowHide 10 child fields in each item
well_idstringRequiredThe Well ID, as the file has it.
reserves_categorystringRequiredIts reserves category (a Novi P-level reads as P50 or its options.p_levels category).
designstring or nullRequiredIts completion design (Novi arps.csv), or null.
streamstringRequiredThe stream it forecasts.
"oil""gas""water"productstringRequiredThe file's product it came from.
ratiostring or nullRequiredThe ratio it is, its stream from its parent's, or null.
"gor""ogr""cgr""wor""wgr"profilestringRequiredThe decline conventions it runs under (GET /conventions include=decline_profiles).
"valnav""mosaic""combocurve""novi""aries"start_datestring or nullRequiredThe date of day 0, or null when the file counts ip days.
templatestring or nullRequiredThe Val Nav template it matched, ComboCurve's Segment Types in order, or null.
segmentsarray of objectsRequiredIts segments in order, each starting where the one before ends.
ShowHide 9 child fields in each item
startnumberRequiredThe day it starts, from day 0.
qinumberRequiredRate at start: bbl/d for oil and water, mcf/d for gas; for a ratio, the ratio (GOR scf/bbl, OGR, CGR and WGR bbl/MMcf, WOR bbl/bbl).
dinumberRequiredNominal decline per year at start; below 0 for an incline.
bnumberRequiredArps b: 0 exponential, 1 harmonic, -1 a straight line.
endnumber or nullOptionalThe day it ends; absent or null runs to qf, df or the curve's end.
qfnumber or nullOptionalThe rate it ends at.
dfnumber or nullOptionalThe nominal decline it ends at.
max_ratenumber or nullOptionalA cap on the rate.
slopestringOptionalWhat a ratio declines with: time or the parent stream's cumulative volume.
"time""volume"
rowsarray of objectsRequiredOnly the rows with an issue.
ShowHide 7 child fields in each item
filestringRequiredThe part or field the row is in: file, constants, csv or constants_csv.
idintegerRequired≥ 0
Its data row in that file, from 0.
well_idstring or nullRequiredIts Well ID, or null.
productstring or nullRequiredIts product, or null.
segmentinteger or nullRequiredIts segment number, or null.
left_outbooleanRequiredTrue when its curve was left out.
issuesarray of stringsRequiredWhat was wrong with it.
warningsarray of stringsRequiredWhat to check.
sheetstringOptionalThe sheet read; only with include ["sheets"], for a workbook file.
sheetsarray of stringsOptionalEvery sheet in workbook order, chartsheets included, so a position is the index options.sheet takes; only with include ["sheets"], for a workbook file, never the constants part's.
warning_detailsarray of objectsOptionalOnly with include warning_codes: each warning's code and fields, one per warning, in the same order.
ShowHide 22 child fields in each item
codestringRequiredStable code; more may come. Each code carries only the fields listed with it.
workbook_first_sheet: file, sheet, sheet_countformulas_without_values: file, sheet, cell_countconstants_without_units: fileconstants_on_time: file, row_countconstants_cut_off: file, row_countseries_left_out: file, row_count, seriesproduct_not_found: productreserves_category_not_found: reserves_categoryunit_not_recognized: label, from, quantity, unitcurves_left_out: curve_count, total_curve_countrows_without_curve: row_countp_levels_not_read: formatp_levels_left_out: curve_countcondensate_as_oil: productsales_gas: productmixed_gas_basis: sales_product, raw_productdefault_units: system, ratesconstants_onlymultiple_reserves_categories: well_countmultiple_designs: well_countsections_not_read: file, row_count
messagestringRequiredIts sentence in warnings, written for API callers.
filestringOptionalThe part or field it is about: file, constants, csv or constants_csv.
sheetstringOptionalThe workbook sheet read, as the sentence names it.
sheet_countintegerOptional≥ 0
Sheets in the workbook.
cell_countintegerOptional≥ 0
Formula cells without a saved value.
row_countintegerOptional≥ 0
Rows it counts.
seriesarray of stringsOptionalThe series left out.
productstringOptionalThe product, as the file or options.products spells it.
reserves_categorystringOptionalThe category, as options.reserves_categories sent it.
labelstringOptionalThe unit label the file gives.
fromstringOptionalWhere the label is.
"header""units row"
Show all 22 fields
quantitystringOptionalWhat the label was read for: oil and water rates, gas rates or a ratio.
"oil_water_rates""gas_rates""gor""ogr""cgr""wor""wgr"unitstringOptionalThe unit it reads in instead.
curve_countintegerOptional≥ 0
Curves it counts.
total_curve_countintegerOptional≥ 0
Curves the file made.
formatstringOptionalThe format read.
"valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"sales_productstringOptionalThe sales gas product.
raw_productstringOptionalThe raw gas product.
systemstringOptionalThe unit system read.
"imperial""metric"ratesobjectOptionalThe rate units read, as units.rates.
ShowHide 3 child fields
oilstringRequiredIts rate unit.
gasstringRequiredIts rate unit.
waterstringRequiredIts rate unit.
well_countintegerOptional≥ 0
Wells it counts.
Errors
| Status | When |
|---|---|
| 413 | The request body is over 64 MB. |
Shared errors400401403500What they mean