Skip to content
Developers
Get an API token

Read a forecast file

Reads a booked forecast file into decline curves, one per well, reserves category, design and stream.

Read a forecast file

POST/forecast-sources/read

Reads 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.

Send a Novi API token as a bearer token on every request. Authentication
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 as constants with a decline file.
  • novi_arps: Novi's own arps.csv, from POST /exports.
  • combocurve_parameters: a ComboCurve forecast parameters CSV. Series best reads 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.units and options.columns are 400s with it.
    • A row's id is 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.max and details.count) and 600,000 lines of ARIES text (a 400 with details.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 bodyRequired

The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.

  • filestringRequired

    File

    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).

  • constantsstringOptional

    File

    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.

  • optionsstringOptional

    As options in the JSON body, as JSON text: {"units": "metric"}.

  • includestringOptional

    As include in the JSON body, as JSON text: ["warning_codes", "sheets"].

Responses

200 OK

The curves, and the rows with an issue.

  • formatstringRequired

    The format read.

    "valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"
  • detected_fromarray of stringsRequired

    The headers that picked the format; ARIES text gives ["PRODUCTION"], also when options.format named it.

  • unitsobjectRequired

    Units.

    ShowHide 5 child fields
    • systemstringRequired

      The unit system read.

      "imperial""metric"
    • fromstringRequired

      What set it.

      "options""units row""format""default"
    • ratesobjectRequired

      The rate units read, converted to bbl/d and mcf/d.

      ShowHide 3 child fields
      • oilstringRequired

        Its rate unit.

      • gasstringRequired

        Its rate unit.

      • waterstringRequired

        Its rate unit.

    • ratiosobjectRequired

      A ratio product to its unit.

    • rowobject or nullRequired

      A Val Nav units row or a Mosaic file's header unit labels, header to unit, or null.

  • productsobjectRequired

    Products.

    ShowHide 3 child fields
    • foundarray of objectsRequired

      Every product in the file.

      ShowHide 2 child fields in each item
      • valuestringRequired

        As the file has it.

      • curvesintegerRequired

        ≥ 0

        Curves.

    • mappedarray of objectsRequired

      Products read.

      ShowHide 3 child fields in each item
      • valuestringRequired

        The product.

      • streamstringRequired

        The stream it reads as.

        "oil""gas""water"
      • fromstring or nullRequired

        The parent stream of a ratio.

        "oil""gas"
    • skippedarray of objectsRequired

      Products left out.

      ShowHide 2 child fields in each item
      • valuestringRequired

        As the file has it.

      • curvesintegerRequired

        ≥ 0

        Curves.

  • gas_basisstringRequired

    raw or sales gas.

    "raw""sales"
  • reserves_categoriesarray of objectsRequired

    Every reserves category with a curve.

    ShowHide 3 child fields in each item
    • valuestringRequired

      As the file has it.

    • curvesintegerRequired

      ≥ 0

      Curves.

    • keptbooleanRequired

      Whether options.reserves_categories keeps it.

  • curvesarray of objectsRequired

    The curves read, in file order.

    ShowHide 10 child fields in each item
    • well_idstringRequired

      The Well ID, as the file has it.

    • reserves_categorystringRequired

      Its reserves category (a Novi P-level reads as P50 or its options.p_levels category).

    • designstring or nullRequired

      Its completion design (Novi arps.csv), or null.

    • streamstringRequired

      The stream it forecasts.

      "oil""gas""water"
    • productstringRequired

      The file's product it came from.

    • ratiostring or nullRequired

      The ratio it is, its stream from its parent's, or null.

      "gor""ogr""cgr""wor""wgr"
    • profilestringRequired

      The decline conventions it runs under (GET /conventions include=decline_profiles).

      "valnav""mosaic""combocurve""novi""aries"
    • start_datestring or nullRequired

      The date of day 0, or null when the file counts ip days.

    • templatestring or nullRequired

      The Val Nav template it matched, ComboCurve's Segment Types in order, or null.

    • segmentsarray of objectsRequired

      Its segments in order, each starting where the one before ends.

      ShowHide 9 child fields in each item
      • startnumberRequired

        The day it starts, from day 0.

      • qinumberRequired

        Rate 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).

      • dinumberRequired

        Nominal decline per year at start; below 0 for an incline.

      • bnumberRequired

        Arps b: 0 exponential, 1 harmonic, -1 a straight line.

      • endnumber or nullOptional

        The day it ends; absent or null runs to qf, df or the curve's end.

      • qfnumber or nullOptional

        The rate it ends at.

      • dfnumber or nullOptional

        The nominal decline it ends at.

      • max_ratenumber or nullOptional

        A cap on the rate.

      • slopestringOptional

        What a ratio declines with: time or the parent stream's cumulative volume.

        "time""volume"
  • rowsarray of objectsRequired

    Only the rows with an issue.

    ShowHide 7 child fields in each item
    • filestringRequired

      The 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 nullRequired

      Its Well ID, or null.

    • productstring or nullRequired

      Its product, or null.

    • segmentinteger or nullRequired

      Its segment number, or null.

    • left_outbooleanRequired

      True when its curve was left out.

    • issuesarray of stringsRequired

      What was wrong with it.

  • warningsarray of stringsRequired

    What to check.

  • sheetstringOptional

    The sheet read; only with include ["sheets"], for a workbook file.

  • sheetsarray of stringsOptional

    Every 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 objectsOptional

    Only with include warning_codes: each warning's code and fields, one per warning, in the same order.

    ShowHide 22 child fields in each item
    • codestringRequired

      Stable code; more may come. Each code carries only the fields listed with it.

      • workbook_first_sheet: file, sheet, sheet_count
      • formulas_without_values: file, sheet, cell_count
      • constants_without_units: file
      • constants_on_time: file, row_count
      • constants_cut_off: file, row_count
      • series_left_out: file, row_count, series
      • product_not_found: product
      • reserves_category_not_found: reserves_category
      • unit_not_recognized: label, from, quantity, unit
      • curves_left_out: curve_count, total_curve_count
      • rows_without_curve: row_count
      • p_levels_not_read: format
      • p_levels_left_out: curve_count
      • condensate_as_oil: product
      • sales_gas: product
      • mixed_gas_basis: sales_product, raw_product
      • default_units: system, rates
      • constants_only
      • multiple_reserves_categories: well_count
      • multiple_designs: well_count
      • sections_not_read: file, row_count
    • messagestringRequired

      Its sentence in warnings, written for API callers.

    • filestringOptional

      The part or field it is about: file, constants, csv or constants_csv.

    • sheetstringOptional

      The 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 stringsOptional

      The series left out.

    • productstringOptional

      The product, as the file or options.products spells it.

    • reserves_categorystringOptional

      The category, as options.reserves_categories sent it.

    • labelstringOptional

      The unit label the file gives.

    • fromstringOptional

      Where the label is.

      "header""units row"
    Show all 22 fields
    • quantitystringOptional

      What the label was read for: oil and water rates, gas rates or a ratio.

      "oil_water_rates""gas_rates""gor""ogr""cgr""wor""wgr"
    • unitstringOptional

      The unit it reads in instead.

    • curve_countintegerOptional

      ≥ 0

      Curves it counts.

    • total_curve_countintegerOptional

      ≥ 0

      Curves the file made.

    • formatstringOptional

      The format read.

      "valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"
    • sales_productstringOptional

      The sales gas product.

    • raw_productstringOptional

      The raw gas product.

    • systemstringOptional

      The unit system read.

      "imperial""metric"
    • ratesobjectOptional

      The rate units read, as units.rates.

      ShowHide 3 child fields
      • oilstringRequired

        Its rate unit.

      • gasstringRequired

        Its rate unit.

      • waterstringRequired

        Its rate unit.

    • well_countintegerOptional

      ≥ 0

      Wells it counts.

Errors

StatusWhen
413

The request body is over 64 MB.

Shared errors400401403500What they mean