Skip to content
Developers
Get an API token

Read planned wells from a file

Planned wells from a file, as the wells POST /forecasts and POST /plans take, with what became of each row.

Read planned wells from a file

POST/inventories/read

Planned wells from a file, as the wells POST /forecasts and POST /plans take, with what became of each row. Nothing is stored: send the file again to read it again.

Send a Novi API token as a bearer token on every request. Authentication
Upload

Send the file as multipart/form-data, a file part and each option as its own part, as curl -F file=@wells.csv -F formation="WOLFCAMP A" <origin>/api/v1/inventories/read. Clients limited to JSON, such as MCP tools, send csv (the text), geojson or shapefile (the zip in base64) in a JSON body instead; the answer is the same. A zip holding [Content_Types].xml is a workbook and any other zip a line shapefile; a JSON object with a type is GeoJSON; anything else is a CSV. An .xls is a 400: save it as .xlsx or CSV.

The wells

wells post as they are to POST /forecasts (up to 50) or POST /plans, each with the fields its row read cleanly (see wells). Positions are WGS 84 degrees, as the file has them when they needed no shift or projection, else rounded to 1e-7°.

  • Wells with decline need "eur": true, and wells read with eur_water: true need "eur_water": true too, or the request is a 400.
  • A well with no tvd_ft that POST /tvd-estimates can't estimate fails the request it is posted in (a plan with per_well_errors: true, only that well), so give it one.
  • Names stay in rows (wells[k] is the row whose well is k), unless well_names: true puts them on the wells.
Rows

Every row is in rows, in file order, with its issues and well, its index in wells or null. A file whose rows all fail is a 200 with count: 0. A row is left out for:

  • a blank or unreadable position, or a lateral outside 100 to 50,000 ft;
  • no end in the dataset's bbox, so its TVD couldn't be estimated;
  • no formation, or one this dataset lacks;
  • repeating an earlier well: the same name, the same ends (and heel, when read) to 1e-6° and the same inventory name ("same well as row k"; the first row's values stand). The same name at other ends is kept, with an issue.

A TVD outside 0 to 40,000 ft (exclusive) is dropped with an issue and estimated instead. A TIL date not in one of the three date forms (YYYY-MM-DD, YYYY/M/D, YYYYMMDD), or outside the dataset's as_of to 30 years from today, is dropped with an issue, and the well takes the next wider layer's date. A kept TVD more than 50 ft above its formation's top or below its base at the well, where the set's grids give both (as landing_fraction measures them), stays, with an issue saying by how much.

Lateral lengths

A stated lateral length is the well's typed_lateral, which the model takes in place of the drawn length when it is within 5% of it or within 100 to 50,000 ft. One more than 5% off gets an issue saying the model takes it, which catches a surface hole read as the heel and lengths in metres; one also outside 100 to 50,000 ft is ignored, with an issue.

CSV

As Novi's earlier Forecast Engine takes inventory and forecast input uploads, and as Novi's inventory exports write them: RFC 4180, comma- or tab-separated by whichever the header line has more of, UTF-8 else Windows-1252, a leading BOM dropped. The first non-blank line is the header; rows are numbered from 0 after it, blank lines left out, and a row with more or fewer cells than the header is left out.

Positions are latitude and longitude in decimal degrees (as 31.93 or -1.2e2), WGS 84 unless crs says otherwise. One out of range leaves its row out, with a hint that the two may be swapped. A name, formation, inventory name or pad cell that starts with an apostrophe before =, +, -, @, a tab or a carriage return (or more apostrophes, then one of those) loses one apostrophe, undoing POST /inventories/write's spreadsheet quoting.

Workbooks

A sheet reads as a CSV does (format: xlsx), from each cell's stored value: number formats aren't applied, so a number shown as 00123 reads 123. A row that ends before the header's last column reads the rest as blank. Dates are read from their serials in the workbook's date system (1900 or 1904), the time of day dropped.

sheet picks a workbook's sheet by name (exact, else in any case) or index from 0, else the first, with a warning when there are more; one the workbook lacks is a 400 with details.sheets. A name of digits only reads as an index, so pick a sheet by its position in sheets (include ["sheets"]), where a name over 31 characters is cut to 31 and ends in ….

Lines

A GeoJSON FeatureCollection, Feature, LineString or MultiLineString, or a zip's first PolyLine (Z or M) layer (a warning names the others), as Intelligence's map export gives them. A line runs from its heel, the first vertex of its first part, to its toe, the last vertex of its last part: its well's shl is the line's start, with no heel. The vertices between are dropped, and a line of several parts gets an issue. Other geometries, null shapes and deleted records are rows left out; a shapefile's records past its .dbf's last row aren't read, with a warning. The coordinate system is found as POST /areas finds it.

Columns

Each role reads the first of its names the file has, compared lowercased with all but letters and digits dropped (Heelpoint Latitude is heelpointlatitude), or the column columns names:

  • name: noviwellname, wellname, name, well, uniqueid, api10, uwi, api14, api12, chosenid
  • formation: noviformation, targetformation, formation, targetzone, landingzone, zone
  • tvd_ft: novitvd, tvd, tvdft
  • til_date: novitildate, tildate, til
  • lateral_length_ft: novilaterallength, laterallength, laterallen

The answer's columns holds an optional role only when the file has it.

Completion columns

Read into each well whether or not the model set's models read them:

  • fluid_bbl_per_ft: novicalcfluidperlength, fluidbblperft, fluidperft, fluidperlength
  • proppant_lb_per_ft: novicalcproppantperlength, proppantlbperft, proppantperft, proppantperlength, propperft
  • stage_length_ft: novistagelength, novicalcstagespacing, stagelengthft, stagelength, stagespacing, stagespacingft, stagelen
  • clusters_per_stage: noviclustersperstage, novicalcclustersperstage, clustersperstage, cluststg
  • frac_rate_bbl_per_min: novifracrate, fracratebblpermin, fracrate, fracratebblmin, fracratebpm, fracbpm

A blank cell leaves the well to the request's completions. A value out of range (fluid over 0 and under 1,000 bbl/ft, proppant over 0 and under 20,000 lb/ft, stage length over 0 and under 2,000 ft, clusters per stage over 0 and under 100, frac rate over 0 and under 500 bbl/min) is dropped with an issue. A warning names filled stage columns the model set's models don't read.

Scenario and pad columns
  • scenario: wellinventoryname, inventoryname, scenario, wellinven. The inventory's name; one over 60 characters is dropped with an issue.
  • pad: novipadname, padname, pad, novipadn. Text, read as scenario is; see WellInput pad.

A warning says when only some wells have an inventory name, since a plan takes a scenario on every well or none, and when the file names more than 20.

Decline columns

A discrete forecast input file's EUR settings, read into each well's decline:

  • eur_years: euryears
  • oil: oil_min_b oilminb, oil_max_b oilmaxb, oil_terminal_decline oilterminaldecline, oiltermin
  • gas: gas_min_b gasminb, gas_max_b gasmaxb, gas_terminal_decline gasterminaldecline, gastermin
  • water, into decline.water, only with eur_water: true: water_min_b waterminb, watermin, water_max_b watermaxb, watermax, water_terminal_decline waterterminaldecline, waterterm

A blank cell leaves the well to the request's settings. A value outside the API's bounds is dropped with an issue (those files' terminal decline can run past 0.01 to 0.2), and a min b at or above its row's max b drops both. On a model set whose oil slot holds condensate, condensate_min_b, condensate_max_b and condensate_terminal_decline fill the oil roles in place of oil's names when the file has any of them. On a set that doesn't serve oil or gas, that stream's names aren't looked for, but a role named in columns or column_hints reads. A warning names decline columns no role reads.

Positions

A CSV's ends; a line's are its vertices.

  • The heel: noviheellatitude, heelpointlatitude, heellatitude, heellat, lplatitude, each with longitude, lng or lon for the longitude.
  • The surface hole: novisurfaceholelatitude, surfaceholelatitude, topholelatitude, shllatitude, shllat.
  • The bottom hole: novibottomholelatitude, bottomholelatitude, bhllatitude, bhllat, toelatitude, toelat.

shl reads the heel when the file has its latitude and longitude, else the surface hole, with a warning. A file with both reads both: shl is the surface hole and heel the heel, unless a row's surface hole is blank, unreadable or more than 50,000 ft from its heel (dropped with an issue; the heel goes in shl). From a file with only a surface hole, laterals start there, and the length check flags it when the file states lengths.

In columns, name an end's latitude and longitude together (shl_lat and shl_lng, heel_lat and heel_lng, bhl_lat and bhl_lng; a 400 on one left out). A named heel pairs with a surface hole as a found one does; naming shl_lat and shl_lng without the heel's reads no heel. A CSV without both ends' columns is a 400.

Column hints

column_hints names columns to try for a role columns and the names above leave unread: 1 to 20 names per role, each 1 to 200 characters, compared as the names above, a name the file lacks skipped, so one team's hints serve every file. Teams keep them in the saved collection column-mappings. A CSV's end (shl, heel or bhl) takes its hinted latitude and longitude only when both are found and the file has no columns for that end by name (for shl, neither the heel's nor the surface hole's) or in columns (for heel, nor a named shl); the end then reads as if named in columns.

Units

units is the file's system. Values are converted to ft, bbl/ft, lb/ft and bbl/min before they are checked, so every bound and the 5% check hold in those units, and wells are always in them. An issue on a converted value quotes the file's value and unit, then the converted one. Clusters per stage have no unit.

  • A header ending in a unit in parentheses or brackets, as TVD (m) or Fluid per Length [m3/m], is in that unit whatever units says, and so is a column whose name says ft, bbl/ft, lb/ft or bbl/min.
  • Those names: tvdft, fluidbblperft, fluidperft, proppantlbperft, proppantperft, propperft, stagelengthft, stagespacingft, fracratebblpermin, fracratebblmin, fracratebpm, fracbpm.
  • For TVD, lateral length, fluid, proppant, stage length and frac rate, a header that matches no name whole is matched by the name before its unit: Lateral Length (ft) reads as lateral_length_ft. Other bracketed headers, as Zone (ft), are matched whole.
  • Header units, in any case (³ or 3): length ft, feet, foot, m, metre, metres, meter, meters; fluid per length bbl/ft, bbls/ft, gal/ft, gals/ft, m3/m; proppant per length lb/ft, lbs/ft, kg/m, t/m, tonne/m, tonnes/m; fluid per minute bbl/min, bbls/min, bpm, m3/min.
  • A header naming a unit of another kind, as TVD (bbl/ft), is read in the request's units with a warning.

A shapefile whose records all carry a UNITS attribute of exactly ft, or all exactly m, is read in that system whatever units says (with a warning when units names the other), as POST /inventories/write marks them; a header's unit still wins. When some records say ft or m but not every record says the same, UNITS is ignored with a warning; when none says either, without one. The answer's units gives the system and each role's unit and where it came from.

Formations

A row's formation maps through formations (up to 100 of the file's names), then matches GET /formations in any case and comes back as it names it; a blank takes the request's formation (a 400 when GET /formations lacks it). A mapping value that isn't a name is a 400 on formations.<name>. unknown_formations lists the names that matched nothing: map them in formations and send the file again.

Dates

With til_from_dates (even {}), the drill_date (novidrillingdate, novispuddate, drilldate, drillingdate, spuddate, novispud) and completion_date (novifracdate, completiondate, fracdate, compldate, novifrac) columns are read in the three date forms. A well whose TIL date is blank, unreadable or dropped takes its completion date plus completion_to_til_days, else its drill date plus drill_to_completion_days and completion_to_til_days: whole days from 0 to 365, 42 each by default.

A derived date is checked as a TIL date is, and dropped with an issue naming the date it came from; rows[].til_from says where each kept well's date came from, and a warning counts the wells that took one. Unreadable dates, a drill date after the completion date and a completion date after the kept TIL date are issues. Without the option these columns aren't read, and naming them in columns is a 400.

Several rows per well

With designs_from_rows: true, a row that repeats a well (the key under Rows) with a completion the well doesn't have yet is that well under another design, so a file listing each well once per completion reads as its wells under the file's designs. A completion is its completion_name (novicompletionname, completionname, designname, design; text, a name over 60 characters dropped with an issue) when filled, else its fluid, proppant and the stage inputs the model set's models read. A stage input the models don't read is the completion's first row's.

When some well has rows of two completions, the answer adds designs, one per completion in first-seen order, and each kept row's design, its index there; its wells carry no completions. A design is named by its completion_name, else <proppant> lb/ft · <fluid> bbl/ft (default for a blank value), then · <v> ft, · <v>/stage and · <v> bbl/min for its stage inputs, or · #<n> when that would pass 60 characters.

Send wells and designs to POST /plans as they are; warnings count the forecasts (wells × designs) and say when they pass GET /dataset limits.plan_wells. A row whose completion name an earlier row set with other values is left out, naming that row, and so are the rows of the 11th completion on (a plan takes 10 designs), with a warning.

Limits
  • The 64 MB request body.
  • GET /dataset limits.plan_wells rows, a 400 with details.max and details.count (split the file); a CSV is read only to the first row past it, so its details.count is details.max + 1.
  • A CSV header of 500 columns, cells cut at 200 characters.
  • A workbook of 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, and a fixed amount of reading work (a 400 with details.max_work).
  • A GeoJSON file's first 500 property names (a columns name past them is a 400); a zip as POST /areas reads one; for lines, a fixed amount of reading and projection work (a 400 "too complex").
Errors

400 with details.field naming the input: csv, geojson, shapefile or file for the file (unreadable, empty, no line layer, too many rows), sheet, crs (with details.supported), formation, formations or formations.<name>, columns.<role>, include and include[0] (an unknown value, with details.allowed), body, or an unknown multipart part's name. A body over 64 MB is a 413.

Parameters

Query parameters

  • model_setstringOptional

    pattern ^[a-z0-9][a-z0-9-]{0,62}$

    The model set to answer from, an id from GET /model-sets. Absent: the set GET /model-sets names as default, the base dataset unless the server answers from a published set.

    • model_set=default reaches the base dataset; once the server retires it, a 400 naming the set answering instead.
    • An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in details.allowed (published sets only once default is retired); a set that can't load, a 503 with the reason.
    • Plans and exports stay in their set: a call naming them (by path, plan, ids, source.plan, a scenario's plan.id, or a comparison's a.plan and b.plan, also under source.comparison) reaches it without model_set.
    • An explicit model_set wins; naming resources of two sets in one request is a 400.

Request bodyRequired

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

  • filestringRequired

    File

    The CSV, Excel workbook (.xlsx), GeoJSON file or zipped line shapefile, as a file part (curl -F file=@wells.csv). Text may come as a text part (curl -F file=<wells.csv), read as UTF-8: send Windows-1252 as a file part.

    An .xls (an OLE file, or a workbook saved with a password) is a 400. A zip with [Content_Types].xml is a workbook, any other zip a line shapefile; else a JSON object with a type is GeoJSON, anything else a CSV.

  • crsstringOptional

    As crs in the JSON body: an EPSG code.

  • formationstringOptional

    As formation in the JSON body.

  • unitsstringOptional

    As units in the JSON body, as plain text: imperial or metric.

  • columnsstringOptional

    As columns in the JSON body, as JSON text: {"name": "Lease Well"}.

  • column_hintsstringOptional

    As column_hints in the JSON body, as JSON text: {"pad": ["Pad ID", "Lease"]}.

  • formationsstringOptional

    As formations in the JSON body, as JSON text: {"WFMP A": "WOLFCAMP A"}.

  • eur_waterstringOptional

    As eur_water in the JSON body, as JSON text: true or false.

  • well_namesstringOptional

    As well_names in the JSON body, as JSON text: true or false.

  • sheetstringOptional

    An Excel workbook's sheet: its name (exact, else in any case) or its index from 0, as Wells or 0; default the first, with a warning when there are more. A 400 with any other file.

  • includestringOptional

    JSON text, as ["sheets"]: a workbook's answer adds sheet and sheets; any other file's answer is unchanged.

  • til_from_datesstringOptional

    As til_from_dates in the JSON body, as JSON text: {"completion_to_til_days": 30}.

  • designs_from_rowsstringOptional

    As designs_from_rows in the JSON body, as JSON text: true or false.

Responses

200 OK

The wells, and every row in file order.

  • countintegerRequired

    ≥ 0

    Wells read: the length of wells.

  • formatstringRequired

    How the file was read.

    "csv""xlsx""geojson""shapefile"
  • crsobjectRequired

    The coordinate system the file was read in, and how sure that is.

    ShowHide 6 child fields
    • codestringRequired

      The system read: an EPSG code, as EPSG:2277, or the .prj's name when no supported system matches it (it was read through the .prj itself).

    • namestringRequired

      Its name, as NAD83 / Texas Central (ftUS).

    • sourcestringRequired

      request: the request's crs; file: the .prj, the GeoJSON (crs member, or degrees per RFC 7946) or a KML (WGS 84); detected: the first supported system that puts the areas on the dataset.

      "request""file""detected"
    • datum_shiftstring or nullRequired

      nadcon_conus: NAD27, shifted to NAD83 with NOAA's NADCON conus grid; else null.

      "nadcon_conus"
    • max_offset_ftintegerRequired

      ≥ 0

      The largest alternative's offset_ft, or 0: how far the areas could be off if the file is in another system that also fits.

    • alternativesarray of objectsRequired

      With detection: the other systems that fit, in preference order, under 1 ft apart listed once.

      ShowHide 3 child fields in each item
      • codestring or nullRequired

        Its EPSG code; null for an international-foot variant, which crs can't name.

      • namestringRequired

        Its name.

      • offset_ftintegerRequired

        ≥ 1

        The farthest a sampled vertex lands from where it is read now, ft.

  • columnsobjectRequired

    The column each role was read from, or null when the file has none.

    ShowHide 31 child fields
    • namestring or nullRequired

      The column names came from, or null.

    • formationstring or nullRequired

      Formations'.

    • tvd_ftstring or nullRequired

      TVDs'.

    • til_datestring or nullRequired

      TIL dates'.

    • lateral_length_ftstring or nullRequired

      Stated lateral lengths'.

    • shl_latstring or nullRequired

      A CSV's shl latitudes'; null for lines.

    • shl_lngstring or nullRequired

      A CSV's shl longitudes'; null for lines.

    • bhl_latstring or nullRequired

      A CSV's bhl latitudes'; null for lines.

    • bhl_lngstring or nullRequired

      A CSV's bhl longitudes'; null for lines.

    • drill_datestringOptional

      Drill dates; only with til_from_dates, when the file has the column.

    • completion_datestringOptional

      Completion dates; only with til_from_dates, when the file has the column.

    • heel_latstringOptional

      A CSV's heel latitudes'; only when the heel is read apart from shl.

    Show all 31 fields
    • heel_lngstringOptional

      A CSV's heel longitudes'; only when the heel is read apart from shl.

    • fluid_bbl_per_ftstringOptional

      Fluid per ft's; only when the file has the column.

    • proppant_lb_per_ftstringOptional

      Proppant per ft's; only when the file has the column.

    • stage_length_ftstringOptional

      Stage lengths'; only when the file has the column.

    • clusters_per_stagestringOptional

      Clusters per stage; only when the file has the column.

    • frac_rate_bbl_per_minstringOptional

      Frac rates'; only when the file has the column.

    • scenariostringOptional

      Inventory names'; only when the file has the column.

    • padstringOptional

      Pad names'; only when the file has the column.

    • eur_yearsstringOptional

      Years to EUR'; only when the file has the column.

    • oil_min_bstringOptional

      Oil b_min's; only when the file has the column.

    • oil_max_bstringOptional

      Oil b_max's; only when the file has the column.

    • oil_terminal_declinestringOptional

      Oil terminal declines'; only when the file has the column.

    • gas_min_bstringOptional

      Gas b_min's; only when the file has the column.

    • gas_max_bstringOptional

      Gas b_max's; only when the file has the column.

    • gas_terminal_declinestringOptional

      Gas terminal declines'; only when the file has the column.

    • water_min_bstringOptional

      Water b_min's; only with eur_water: true, when the file has the column.

    • water_max_bstringOptional

      Water b_max's; only with eur_water: true, when the file has the column.

    • water_terminal_declinestringOptional

      Water terminal declines'; only with eur_water: true, when the file has the column.

    • completion_namestringOptional

      Completion names'; only in an answer with designs, when the file has the column.

  • fieldsarray of stringsRequired

    The file's columns (a CSV's header, or the lines' attributes), in file order.

  • wellsarray of objectsRequired

    The wells, in file order, to post as wells to POST /forecasts or POST /plans. Posting a decline needs "eur": true; posting wells read with eur_water: true needs "eur_water": true.

    Each has shl (the heel, or the surface hole with heel), heel when the file has both, bhl, formation, and typed_lateral from a stated lateral length unless it is both over 5% off the drawn one and outside 100 to 50,000 ft. tvd_ft, til_date, fluid_bbl_per_ft, proppant_lb_per_ft, stage_length_ft, clusters_per_stage, frac_rate_bbl_per_min, scenario, pad and decline come when the file has good ones; name with well_names: true.

    ShowHide 22 child fields in each item
    • shl[number, number]Required

      Surface hole location, [lng, lat].

    • bhl[number, number]Required

      Bottom hole (toe) location, [lng, lat]. The lateral runs from heel, else shl, to bhl and must be 100 to 50,000 ft long.

    • formationstring or nullOptional

      Target formation (case-insensitive; GET /formations lists them). Needed to forecast and to estimate TVD.

    • tvd_ftnumber or nullOptional

      > 0, < 40000

      True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.

    • landing_below_top_ftnumber or nullOptional

      > -40000, < 40000

      Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's subsurface_sampling (GET /model-sets).

    • heel[number, number] or nullOptional

      Where the lateral starts, [lng, lat], when not at shl, the surface hole; absent or null, it starts at shl. shl must be within 50,000 ft of it.

      With it, the lateral length and its 100 to 50,000 ft check, spacing, gun barrel laterals, PDP wells and model analogs run from heel to bhl. Subsurface grids still sample at shl and bhl as the set's subsurface_sampling says, and structure tops, landing, TVD estimates, the KB elevation and the model's surface hole inputs stay at shl.

    • typed_lateralobject or nullOptional

      A lateral length typed for the well, as an inventory file gives it: length_ft, and the heel (the well's heel, else its shl) and bhl it was typed for.

      The model gets length_ft as novi_lateral_length, and spacing, the completion totals, analogs, normalize_lateral_ft and pricing use it, while the well's heel (else shl) and bhl equal those two exactly and it is within 5% of the length measured between them or within 100 to 50,000 ft; otherwise the measured length. A client that moves an end can send it unchanged: the well then uses the measured length.

      Reads give the length used as lateral_length_ft, with lateral_length_source. Optional: absent or null, the measured length.

      POST /inventories/read sets it from a file's stated length unless that is both more than 5% off the drawn one and outside 100 to 50,000 ft, with an issue when it is more than 5% off.

      ShowHide 3 child fields
      • length_ftnumberRequired

        ≥ 0, ≤ 1000000

        The typed length, ft.

      • heel[number, number]Required

        Where the lateral started when the length was typed: the well's heel, else its shl, [lng, lat].

      • bhl[number, number]Required

        The bottom hole the length was typed for, [lng, lat].

    • lateral_outsidestring or nullOptional

      Ignored; accepted so POST /layouts/fill wells with lateral_check can be sent as they are.

      "above""below"
    • landing_fractionnumber or nullOptional

      ≥ 0, ≤ 1

      Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.

      The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.

      The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.

      Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.

      Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:

      • its formation has no grid there or no place in the column;
      • no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
      • the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
      • top and base averaged over the ends are under a foot apart: the zone pinches out.

      A well's inputs echo it when it was sent.

    • lateral_length_ftnumber or nullOptional

      Ignored: the lateral runs from heel, else shl, to bhl, unless typed_lateral applies. Accepted so POST /layouts/fill wells can be sent as they are.

    • til_datestring or nullOptional

      Format date

      TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.

      From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.

    • partinteger or nullOptional

      Ignored, as is bench: accepted so POST /layouts/fill wells can be sent as they are.

    Show all 22 fields
    • benchinteger or nullOptional

      Ignored.

    • padnumber or string or nullOptional

      The pad the well is on: a whole number, as POST /layouts/fill numbers them, or text of 1 to 60 characters, trimmed; 1 and "1" are one pad.

      POST /plans keeps a valid key whenever sent, for group_by=pad and the pad= filter, and doesn't echo it on wells; other requests read it only with pads. It is checked (a 400 on a bad value) only with pads; without pads, a value that isn't a pad is ignored.

    • scenariostringOptional

      1 to 60 characters

      The alternative the well is in: a scenario's wells space against only each other and existing wells, never another scenario's. A name of 1 to 60 characters, trimmed.

      Equal names (exact, case-sensitive) are one scenario; with pdp false its wells space against only each other. Give every well a scenario, or none (400 at the first without one). At most 10 scenarios on POST /forecasts, each its own spacing run, and 20 on POST /plans (400 at the first well past it, with details.max and details.count). Designs and pdp apply to every scenario unless scenarios sets its own.

    • fluid_bbl_per_ftnumber or nullOptional

      > 0, < 1000

      This well's fluid in bbl per lateral ft.

      Each field takes the narrowest layer that sets it, on its own: the well, its pad's entry in pads or its layout (the bench or formation entry, then overall), its entry in scenarios (formation entry, then overall), the design's formations entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.

      Needs one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds resolved to every well's inputs in the request.

    • proppant_lb_per_ftnumber or nullOptional

      > 0, < 20000

      This well's proppant in lb per lateral ft.

      Each field takes the narrowest layer that sets it, on its own: the well, its pad's entry in pads or its layout (the bench or formation entry, then overall), its entry in scenarios (formation entry, then overall), the design's formations entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.

      Needs one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds resolved to every well's inputs in the request.

    • stage_length_ftnumber or nullOptional

      > 0, < 2000

      Stage length in ft.

      Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

    • clusters_per_stagenumber or nullOptional

      > 0, < 100

      Perforation clusters per stage; fractions are accepted.

      Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

    • frac_rate_bbl_per_minnumber or nullOptional

      > 0, < 500

      Frac pump rate in bbl per minute.

      Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

    • declineobjectOptional

      EUR settings for this well; needs eur on.

      With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

      Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

      A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

      ShowHide 7 child fields
      • eur_yearsintegerOptional

        ≥ 10, ≤ 50

        Years to EUR: the extension runs to the last 30-day step within eur_years × 365 days.

      • terminal_declinenumberOptional

        ≥ 0.01, ≤ 0.2

        Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.

      • b_minnumberOptional

        ≥ 0, ≤ 2.5

        Lowest hyperbolic b the fit may use; below b_max.

      • b_maxnumberOptional

        ≥ 0, ≤ 2.5

        Highest hyperbolic b the fit may use; above b_min.

      • oilobjectOptional

        Oil's own settings over these.

        ShowHide 3 child fields
        • terminal_declinenumberOptional

          ≥ 0.01, ≤ 0.2

          Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.

        • b_minnumberOptional

          ≥ 0, ≤ 2.5

          Lowest hyperbolic b the fit may use; below b_max.

        • b_maxnumberOptional

          ≥ 0, ≤ 2.5

          Highest hyperbolic b the fit may use; above b_min.

      • gasobjectOptional

        Gas's own settings over these.

        Same fields as StreamDeclineSettings.

      • waterobjectOptional

        Water's own settings over these, only with eur_water: true, else a 400. Unlike oil and gas it doesn't set per-stream settings: oil and gas keep theirs and their calls.

        Same fields as StreamDeclineSettings.

    • namestring or nullOptional

      up to 60 characters

      Your name for the well, 1 to 60 characters once trimmed, on POST /plans, POST /forecasts and POST /inventories/write; other routes that take wells answer 400. null is none; a blank name is a 400.

      Names needn't be unique. Reads show it beside label, which stays Plan well N (Drawn well N on POST /forecasts). A plan's export tables put it in their well column, keeping their row order, with a leading quote where a spreadsheet would read it as a formula. ARIES heads the well with it, unquoted, and sorts by header, so wells with one name share a header: send aries.well_key: id to keep them apart.

  • rowsarray of objectsRequired

    Every row of the file, in file order.

    ShowHide 8 child fields in each item
    • idintegerRequired

      ≥ 0

      Its row in the file from 0: a CSV's data row (blank lines not counted), or a line's record or feature index.

    • namestring or nullRequired

      Its name from the name column, or null.

    • wellinteger or nullRequired

      ≥ 0

      Its index in wells, or null when it was left out (issues says why).

    • lateral_length_ftinteger or nullRequired

      Feet from the heel, else shl, to bhl, rounded; null without a usable position.

    • in_datasetboolean or nullRequired

      True when an end lies in GET /dataset's bbox; null without a usable position.

    • issuesarray of stringsRequired

      Why it was left out, or what was dropped or doubted in a well kept; empty when it read cleanly.

    • designintegerOptional

      ≥ 0

      Its index in designs: only in an answer with designs, on every kept row.

    • til_fromstring or nullOptional

      Where its TIL date came from, only with til_from_dates; null without an accepted date or when left out.

      "file""completion_date""drill_date"
  • unknown_formationsarray of objectsRequired

    Formation names that matched nothing, most rows first: map them in formations.

    ShowHide 2 child fields in each item
    • valuestringRequired

      A formation name in the file.

    • rowsintegerRequired

      ≥ 1

      Rows naming it.

  • warningsarray of stringsRequired

    What to check: a surface hole read as shl, rows left out or with issues, unknown formations, other layers, the coordinate system's doubt, wells without an inventory name, more names than a plan takes.

    Also unread decline columns (water's without eur_water: true; condensate's unless the set's oil slot holds condensate; oil's when condensate's fill its roles; a stream's the set doesn't serve) and filled stage columns the set's models don't read.

  • sheetstringOptional

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

  • sheetsarray of stringsOptional

    Every sheet in workbook order, chartsheets included, so a position is the index sheet takes; only with include ["sheets"], for a workbook.

  • unitsobjectOptional

    Units read, only when units was sent, a shapefile's UNITS attribute is read or a resolved column header names a recognized unit.

    ShowHide 2 child fields
    • systemstringRequired

      A shapefile's UNITS system when it has one, else the request's, imperial when absent.

      "imperial""metric"
    • columnsobjectRequired

      Only roles whose column the file has.

      ShowHide 6 child fields
      • tvd_ftobjectOptional

        The unit read for this column.

        ShowHide 2 child fields
        • unitstringRequired

          The unit read.

        • fromstringRequired

          Where the unit came from: file is a shapefile's UNITS attribute.

          "header""file""request""default"
      • lateral_length_ftobjectOptional

        The unit read for this column.

        ShowHide 2 child fields
        • unitstringRequired

          The unit read.

        • fromstringRequired

          Where the unit came from: file is a shapefile's UNITS attribute.

          "header""file""request""default"
      • fluid_bbl_per_ftobjectOptional

        The unit read for this column.

        ShowHide 2 child fields
        • unitstringRequired

          The unit read.

        • fromstringRequired

          Where the unit came from: file is a shapefile's UNITS attribute.

          "header""file""request""default"
      • proppant_lb_per_ftobjectOptional

        The unit read for this column.

        ShowHide 2 child fields
        • unitstringRequired

          The unit read.

        • fromstringRequired

          Where the unit came from: file is a shapefile's UNITS attribute.

          "header""file""request""default"
      • stage_length_ftobjectOptional

        The unit read for this column.

        ShowHide 2 child fields
        • unitstringRequired

          The unit read.

        • fromstringRequired

          Where the unit came from: file is a shapefile's UNITS attribute.

          "header""file""request""default"
      • frac_rate_bbl_per_minobjectOptional

        The unit read for this column.

        ShowHide 2 child fields
        • unitstringRequired

          The unit read.

        • fromstringRequired

          Where the unit came from: file is a shapefile's UNITS attribute.

          "header""file""request""default"
  • designsarray of objectsOptional

    Only with designs_from_rows when some well has rows of two completions: the file's completions in first-seen order, at most 10, to send as designs to POST /plans with wells.

    ShowHide 7 child fields in each item
    • namestring or nullOptional

      up to 60 characters

      Your name for the design; defaults to Design 1, Design 2, ….

    • fluid_bbl_per_ftnumber or nullOptional

      > 0, < 1000

      Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

    • proppant_lb_per_ftnumber or nullOptional

      > 0, < 20000

      Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

    • stage_length_ftnumber or nullOptional

      > 0, < 2000

      Stage length in ft.

      Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

    • clusters_per_stagenumber or nullOptional

      > 0, < 100

      Perforation clusters per stage; fractions are accepted.

      Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

    • frac_rate_bbl_per_minnumber or nullOptional

      > 0, < 500

      Frac pump rate in bbl per minute.

      Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

    • formationsarray of objectsOptional

      Per-formation overrides, each formation at most once.

      ShowHide 6 child fields in each item
      • formationstringRequired

        Formation (case-insensitive).

      • fluid_bbl_per_ftnumber or nullOptional

        > 0, < 1000

        Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

      • proppant_lb_per_ftnumber or nullOptional

        > 0, < 20000

        Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

      • stage_length_ftnumber or nullOptional

        > 0, < 2000

        Stage length in ft.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • clusters_per_stagenumber or nullOptional

        > 0, < 100

        Perforation clusters per stage; fractions are accepted.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • frac_rate_bbl_per_minnumber or nullOptional

        > 0, < 500

        Frac pump rate in bbl per minute.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

Errors

StatusWhen
413

The request body is over 64 MB.

Shared errors400401403500503What they mean