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
/inventories/readPlanned 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.
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
declineneed"eur": true, and wells read witheur_water: trueneed"eur_water": truetoo, or the request is a 400. - A well with no
tvd_ftthat POST /tvd-estimates can't estimate fails the request it is posted in (a plan withper_well_errors: true, only that well), so give it one. - Names stay in
rows(wells[k]is the row whosewellis k), unlesswell_names: trueputs 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, chosenidformation: noviformation, targetformation, formation, targetzone, landingzone, zonetvd_ft: novitvd, tvd, tvdfttil_date: novitildate, tildate, tillateral_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, fluidperlengthproppant_lb_per_ft: novicalcproppantperlength, proppantlbperft, proppantperft, proppantperlength, propperftstage_length_ft: novistagelength, novicalcstagespacing, stagelengthft, stagelength, stagespacing, stagespacingft, stagelenclusters_per_stage: noviclustersperstage, novicalcclustersperstage, clustersperstage, cluststgfrac_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 asscenariois; see WellInputpad.
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_boilminb,oil_max_boilmaxb,oil_terminal_declineoilterminaldecline, oiltermin - gas:
gas_min_bgasminb,gas_max_bgasmaxb,gas_terminal_declinegasterminaldecline, gastermin - water, into
decline.water, only witheur_water: true:water_min_bwaterminb, watermin,water_max_bwatermaxb, watermax,water_terminal_declinewaterterminaldecline, 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)orFluid per Length [m3/m], is in that unit whateverunitssays, 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 aslateral_length_ft. Other bracketed headers, asZone (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_wellsrows, a 400 withdetails.maxanddetails.count(split the file); a CSV is read only to the first row past it, so itsdetails.countisdetails.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
columnsname 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_setstringOptionalpattern ^[a-z0-9][a-z0-9-]{0,62}$
The model set to answer from, an
idfrom GET /model-sets. Absent: the set GET /model-sets names asdefault, the base dataset unless the server answers from a published set.model_set=defaultreaches 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 oncedefaultis 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'splan.id, or a comparison'sa.planandb.plan, also undersource.comparison) reaches it withoutmodel_set. - An explicit
model_setwins; naming resources of two sets in one request is a 400.
Request body
The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.
filestringRequiredFile
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.
crsstringOptionalAs crs in the JSON body: an EPSG code.
formationstringOptionalAs formation in the JSON body.
unitsstringOptionalAs units in the JSON body, as plain text: imperial or metric.
columnsstringOptionalAs columns in the JSON body, as JSON text: {"name": "Lease Well"}.
column_hintsstringOptionalAs column_hints in the JSON body, as JSON text: {"pad": ["Pad ID", "Lease"]}.
formationsstringOptionalAs formations in the JSON body, as JSON text: {"WFMP A": "WOLFCAMP A"}.
eur_waterstringOptionalAs eur_water in the JSON body, as JSON text: true or false.
well_namesstringOptionalAs well_names in the JSON body, as JSON text: true or false.
sheetstringOptionalAn 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.
includestringOptionalJSON text, as ["sheets"]: a workbook's answer adds sheet and sheets; any other file's answer is unchanged.
til_from_datesstringOptionalAs til_from_dates in the JSON body, as JSON text: {"completion_to_til_days": 30}.
designs_from_rowsstringOptionalAs designs_from_rows in the JSON body, as JSON text: true or false.
csvstringOptionalThe CSV (or tab-separated) file's text. Where you can, upload the file itself as multipart/form-data instead.
geojsonobjectOptionalA GeoJSON FeatureCollection, Feature, LineString or MultiLineString of well paths, each heel first. Coordinates in degrees are WGS 84 (RFC 7946); others need a crs member or crs, or are detected.
shapefilestringOptionalA zipped line shapefile (.shp, .dbf and .prj; .cpg and .shx optional) in base64: RFC 4648, padded, with no line breaks or data: prefix.
crsstring or integer or nullOptionalThe file's coordinate system as an EPSG code (EPSG:4267, epsg:4267 or 4267). A CSV takes EPSG:4326, EPSG:4269 (read as WGS 84) or EPSG:4267 (NAD27, shifted with NADCON).
For lines it overrides the file's own and detection, and is one of EPSG:2275, EPSG:2276, EPSG:2277, EPSG:2278, EPSG:2279, EPSG:2257, EPSG:2258, EPSG:2259, EPSG:32137, EPSG:32138, EPSG:32139, EPSG:32140, EPSG:32141, EPSG:32112, EPSG:32113, EPSG:32114, EPSG:6578, EPSG:6588, EPSG:3081, EPSG:3082, EPSG:3083, EPSG:5070, EPSG:3857, EPSG:26913, EPSG:26914, EPSG:32613, EPSG:32614, EPSG:4326, EPSG:4269, EPSG:32037, EPSG:32038, EPSG:32039, EPSG:32040, EPSG:32041, EPSG:32012, EPSG:32013, EPSG:32014, EPSG:26713, EPSG:26714, EPSG:4267.
unitsstringOptionalDefault
"imperial"The file's unit system: imperial ft, bbl/ft, lb/ft, or metric m, m3/m, t/m, with frac rate in bbl/min, or m3/min in metric; a unit in a column's header wins. Any other value is a 400 on units.
"imperial""metric"columnsobjectOptionalColumns to read a role from instead of the one found by name: the exact column name, else in any case. A column the file lacks is a 400 with details.fields.
ShowHide 31 child fields
namestring or nullOptionalThe column of each well's name, kept in rows, and in wells with well_names: true.
formationstring or nullOptionalOf its target formation.
tvd_ftstring or nullOptionalOf its TVD: ft, else as units or its header says.
drill_datestring or nullOptionalOf its drill date, only with til_from_dates.
completion_datestring or nullOptionalOf its completion date, only with til_from_dates.
til_datestring or nullOptionalOf its TIL date.
lateral_length_ftstring or nullOptionalOf its stated lateral length, checked against the drawn one: ft, else as units or its header says.
shl_latstring or nullOptionalCSV only: of the heel's latitude (or the surface hole's); the surface hole's when the heel is read too.
shl_lngstring or nullOptionalCSV only: of the heel's longitude (or the surface hole's); the surface hole's when the heel is read too.
heel_latstring or nullOptionalCSV only: of the heel's latitude, read apart from shl when the file has a surface hole too; else shl reads it.
heel_lngstring or nullOptionalCSV only: of the heel's longitude, read apart from shl when the file has a surface hole too; else shl reads it.
bhl_latstring or nullOptionalCSV only: of the bottom hole's (toe's) latitude.
Show all 31 fields
bhl_lngstring or nullOptionalCSV only: of the bottom hole's (toe's) longitude.
fluid_bbl_per_ftstring or nullOptionalOf its fluid per lateral length: bbl/ft, else as units or its header says.
proppant_lb_per_ftstring or nullOptionalOf its proppant per lateral length: lb/ft, else as units or its header says.
stage_length_ftstring or nullOptionalOf its stage length: ft, else as units or its header says.
clusters_per_stagestring or nullOptionalOf its clusters per stage.
frac_rate_bbl_per_minstring or nullOptionalOf its frac rate: bbl/min, else as units or its header says.
scenariostring or nullOptionalOf its scenario name.
padstring or nullOptionalOf its pad.
eur_yearsstring or nullOptionalOf its years to EUR.
oil_min_bstring or nullOptionalOf its oil b_min.
oil_max_bstring or nullOptionalOf its oil b_max.
oil_terminal_declinestring or nullOptionalOf its oil terminal decline.
gas_min_bstring or nullOptionalOf its gas b_min.
gas_max_bstring or nullOptionalOf its gas b_max.
gas_terminal_declinestring or nullOptionalOf its gas terminal decline.
water_min_bstring or nullOptionalOf its water b_min, only with eur_water: true.
water_max_bstring or nullOptionalOf its water b_max, only with eur_water: true.
water_terminal_declinestring or nullOptionalOf its water terminal decline, only with eur_water: true.
completion_namestring or nullOptionalOf its completion's name, only with designs_from_rows: true.
column_hintsobjectOptionalColumn names to try per role, as {"pad": ["Pad ID", "Lease"]}, for roles that columns and name matching leave unread: the first the file has that no role reads or finds.
A name the file lacks is skipped; an unknown role or a bad list is a 400 on column_hints.<role>. Dropped: position roles in a line file, water roles without eur_water (with a warning naming the columns they find), date roles without til_from_dates, completion_name without designs_from_rows.
formationsobjectOptionalup to 100 keys
The file's formation names (any case) mapped to formations in GET /formations, as {"WFMP A": "WOLFCAMP A"}: unknown_formations says which to map. A formation this model set lacks is skipped with a warning naming it.
formationstring or nullOptionalThe formation of rows whose formation is blank, or of every row when the file has no formation column (any case; GET /formations lists them).
eur_waterbooleanOptionalDefault
falseRead the water_min_b, water_max_b and water_terminal_decline columns: the wells carry
decline.water, so post them with"eur_water": true. Absent, those columns aren't read and a warning names them, since a file posted as it comes would be a 400.well_namesbooleanOptionalDefault
falseWrite each kept well's trimmed name on
wells[].name, for POST /forecasts, POST /plans and POST /inventories/write: other routes that take wells answer 400 on a name. A blank one is left off, and one over 60 characters once trimmed is left off with one issue on its row, keeping the well.til_from_datesobjectOptionalFill a missing TIL date from completion, else drill dates; an empty object uses 42 days after each.
ShowHide 2 child fields
drill_to_completion_daysintegerOptionalDefault
42≥ 0, ≤ 365Days from the drill date to completion.
completion_to_til_daysintegerOptionalDefault
42≥ 0, ≤ 365Days from the completion date to TIL.
designs_from_rowsbooleanOptionalDefault
falseRead a row that repeats a well with a completion the well lacks as that well under another design: the answer adds designs and each row's design when some well has rows of two completions, else is the answer without it. See Several rows per well.
Responses
200 OK
The wells, and every row in file order.
countintegerRequired≥ 0
Wells read: the length of wells.
formatstringRequiredHow the file was read.
"csv""xlsx""geojson""shapefile"crsobjectRequiredThe coordinate system the file was read in, and how sure that is.
ShowHide 6 child fields
codestringRequiredThe 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).
namestringRequiredIts name, as NAD83 / Texas Central (ftUS).
sourcestringRequiredrequest: 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 nullRequirednadcon_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 objectsRequiredWith detection: the other systems that fit, in preference order, under 1 ft apart listed once.
ShowHide 3 child fields in each item
codestring or nullRequiredIts EPSG code; null for an international-foot variant, which crs can't name.
namestringRequiredIts name.
offset_ftintegerRequired≥ 1
The farthest a sampled vertex lands from where it is read now, ft.
columnsobjectRequiredThe column each role was read from, or null when the file has none.
ShowHide 31 child fields
namestring or nullRequiredThe column names came from, or null.
formationstring or nullRequiredFormations'.
tvd_ftstring or nullRequiredTVDs'.
til_datestring or nullRequiredTIL dates'.
lateral_length_ftstring or nullRequiredStated lateral lengths'.
shl_latstring or nullRequiredA CSV's shl latitudes'; null for lines.
shl_lngstring or nullRequiredA CSV's shl longitudes'; null for lines.
bhl_latstring or nullRequiredA CSV's bhl latitudes'; null for lines.
bhl_lngstring or nullRequiredA CSV's bhl longitudes'; null for lines.
drill_datestringOptionalDrill dates; only with til_from_dates, when the file has the column.
completion_datestringOptionalCompletion dates; only with til_from_dates, when the file has the column.
heel_latstringOptionalA CSV's heel latitudes'; only when the heel is read apart from shl.
Show all 31 fields
heel_lngstringOptionalA CSV's heel longitudes'; only when the heel is read apart from shl.
fluid_bbl_per_ftstringOptionalFluid per ft's; only when the file has the column.
proppant_lb_per_ftstringOptionalProppant per ft's; only when the file has the column.
stage_length_ftstringOptionalStage lengths'; only when the file has the column.
clusters_per_stagestringOptionalClusters per stage; only when the file has the column.
frac_rate_bbl_per_minstringOptionalFrac rates'; only when the file has the column.
scenariostringOptionalInventory names'; only when the file has the column.
padstringOptionalPad names'; only when the file has the column.
eur_yearsstringOptionalYears to EUR'; only when the file has the column.
oil_min_bstringOptionalOil b_min's; only when the file has the column.
oil_max_bstringOptionalOil b_max's; only when the file has the column.
oil_terminal_declinestringOptionalOil terminal declines'; only when the file has the column.
gas_min_bstringOptionalGas b_min's; only when the file has the column.
gas_max_bstringOptionalGas b_max's; only when the file has the column.
gas_terminal_declinestringOptionalGas terminal declines'; only when the file has the column.
water_min_bstringOptionalWater b_min's; only with eur_water: true, when the file has the column.
water_max_bstringOptionalWater b_max's; only with eur_water: true, when the file has the column.
water_terminal_declinestringOptionalWater terminal declines'; only with eur_water: true, when the file has the column.
completion_namestringOptionalCompletion names'; only in an answer with designs, when the file has the column.
fieldsarray of stringsRequiredThe file's columns (a CSV's header, or the lines' attributes), in file order.
wellsarray of objectsRequiredThe 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]RequiredSurface hole location, [lng, lat].
bhl[number, number]RequiredBottom 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 nullOptionalTarget 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 nullOptionalWhere the lateral starts, [lng, lat], when not at
shl, the surface hole; absent or null, it starts atshl.shlmust 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
shlandbhlas the set'ssubsurface_samplingsays, and structure tops, landing, TVD estimates, the KB elevation and the model's surface hole inputs stay atshl.typed_lateralobject or nullOptionalA lateral length typed for the well, as an inventory file gives it:
length_ft, and theheel(the well's heel, else itsshl) andbhlit was typed for.The model gets
length_ftasnovi_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, withlateral_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]RequiredWhere the lateral started when the length was typed: the well's heel, else its shl, [lng, lat].
bhl[number, number]RequiredThe bottom hole the length was typed for, [lng, lat].
lateral_outsidestring or nullOptionalIgnored; 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 nullOptionalIgnored: the lateral runs from heel, else shl, to bhl, unless
typed_lateralapplies. Accepted so POST /layouts/fill wells can be sent as they are.til_datestring or nullOptionalFormat
dateTIL (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 nullOptionalIgnored, as is bench: accepted so POST /layouts/fill wells can be sent as they are.
Show all 22 fields
benchinteger or nullOptionalIgnored.
padnumber or string or nullOptionalThe 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=padand thepad=filter, and doesn't echo it on wells; other requests read it only withpads. It is checked (a 400 on a bad value) only withpads; withoutpads, a value that isn't a pad is ignored.scenariostringOptional1 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
scenariossets 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
padsor its layout (the bench or formation entry, then overall), its entry inscenarios(formation entry, then overall), the design'sformationsentry 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
resolvedto every well'sinputsin 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
padsor its layout (the bench or formation entry, then overall), its entry inscenarios(formation entry, then overall), the design'sformationsentry 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
resolvedto every well'sinputsin 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.declineobjectOptionalEUR settings for this well; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.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.
oilobjectOptionalOil'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.
gasobjectOptionalGas's own settings over these.
Same fields as StreamDeclineSettings.
waterobjectOptionalWater'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 nullOptionalup 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 theirwellcolumn, 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: sendaries.well_key: idto keep them apart.
rowsarray of objectsRequiredEvery 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 nullRequiredIts 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 nullRequiredFeet from the heel, else shl, to bhl, rounded; null without a usable position.
in_datasetboolean or nullRequiredTrue when an end lies in GET /dataset's bbox; null without a usable position.
issuesarray of stringsRequiredWhy 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 nullOptionalWhere 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 objectsRequiredFormation names that matched nothing, most rows first: map them in formations.
ShowHide 2 child fields in each item
valuestringRequiredA formation name in the file.
rowsintegerRequired≥ 1
Rows naming it.
warningsarray of stringsRequiredWhat 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.
sheetstringOptionalThe sheet read; only with include ["sheets"], for a workbook.
sheetsarray of stringsOptionalEvery sheet in workbook order, chartsheets included, so a position is the index sheet takes; only with include ["sheets"], for a workbook.
unitsobjectOptionalUnits 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
systemstringRequiredA shapefile's UNITS system when it has one, else the request's, imperial when absent.
"imperial""metric"columnsobjectRequiredOnly roles whose column the file has.
ShowHide 6 child fields
tvd_ftobjectOptionalThe unit read for this column.
ShowHide 2 child fields
unitstringRequiredThe unit read.
fromstringRequiredWhere the unit came from: file is a shapefile's UNITS attribute.
"header""file""request""default"
lateral_length_ftobjectOptionalThe unit read for this column.
ShowHide 2 child fields
unitstringRequiredThe unit read.
fromstringRequiredWhere the unit came from: file is a shapefile's UNITS attribute.
"header""file""request""default"
fluid_bbl_per_ftobjectOptionalThe unit read for this column.
ShowHide 2 child fields
unitstringRequiredThe unit read.
fromstringRequiredWhere the unit came from: file is a shapefile's UNITS attribute.
"header""file""request""default"
proppant_lb_per_ftobjectOptionalThe unit read for this column.
ShowHide 2 child fields
unitstringRequiredThe unit read.
fromstringRequiredWhere the unit came from: file is a shapefile's UNITS attribute.
"header""file""request""default"
stage_length_ftobjectOptionalThe unit read for this column.
ShowHide 2 child fields
unitstringRequiredThe unit read.
fromstringRequiredWhere the unit came from: file is a shapefile's UNITS attribute.
"header""file""request""default"
frac_rate_bbl_per_minobjectOptionalThe unit read for this column.
ShowHide 2 child fields
unitstringRequiredThe unit read.
fromstringRequiredWhere the unit came from: file is a shapefile's UNITS attribute.
"header""file""request""default"
designsarray of objectsOptionalOnly 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 nullOptionalup 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 objectsOptionalPer-formation overrides, each formation at most once.
ShowHide 6 child fields in each item
formationstringRequiredFormation (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
| Status | When |
|---|---|
| 413 | The request body is over 64 MB. |
Shared errors400401403500503What they mean