Download a plan's wells as an inventory file
Write the sent wells as an inventory file, CSV (default), GeoJSON or a zipped shapefile, that POST /inventories/read reads back.
Download a plan's wells as an inventory file
/inventories/writeWrite the sent wells as an inventory file, CSV (default), GeoJSON or a zipped shapefile, that POST /inventories/read reads back. Formation names are checked against the selected dataset; nothing is stored.
Formats
One of three:
- CSV: UTF-8 without a BOM, comma-separated, quoted where needed, LF line ends and a final newline. A text cell starting with =, +, -, @, a tab or a carriage return (after any apostrophes) gets a leading apostrophe against spreadsheet formulas; the read takes it off.
- GeoJSON: a WGS 84 FeatureCollection of two-point LineStrings with no crs member; properties hold the other columns, numbers as numbers, blanks as null.
- Shapefile: a zip of a PolyLine .shp, .shx, dBASE III .dbf, WGS 84 .prj and UTF-8 .cpg. Numeric attributes are fixed-decimal, at most 19 characters and 15 decimals, so a value with more decimals is rounded.
Columns
In GET /inventories/columns catalog order, only those some well has.
- CSV and GeoJSON headers use the chosen units (metric: m, m3/m, t/m and m3/min). Shapefile attributes take the catalog's field names, plus UNITS, always in ft, bbl/ft, lb/ft and bbl/min.
- Heelpoint is heel, else shl; Bottom Hole is bhl. CSV Top Hole columns appear only when some well has heel, holding shl for those wells and blank for the others. Lines run from heel (else shl) to bhl.
- The stated lateral is typed_lateral.length_ft only while the model would take it: its ends match heel (else shl) and bhl exactly, and it is within 5% of their measured length or within 100 to 50,000 ft.
- landing_below_top_ft, landing_fraction, lateral_length_ft, lateral_outside, part and bench aren't written. Names and scenarios are trimmed, formation takes the dataset's canonical name, and pads are text.
- A well's flat decline settings (decline.b_min, b_max, terminal_decline) fill each stream's unset columns; water's only when the well sets decline.water or the request sends eur_water: true.
Reading it back
POST /inventories/read of the CSV with well_names: true (and eur_water: true when a well sets decline.water or the write sent it) returns the wells as written: the fields above, decline settings per stream, stage length, clusters per stage and frac rate (a null reads back absent), and a metric file's values to the read's 1e-6 rounding. GeoJSON and shapefile read back likewise, a shapefile's numbers to its 15 decimals, except that a line holds no separate surface hole: shl is its start and heel is absent. A shapefile's UNITS is always ft, whatever its units says. A well with neither end in GET /dataset's bbox is written, and the read leaves it out.
Refused (400)
Each names the field it is on.
- Fewer than 1 or more than GET /dataset limits.plan_wells wells (on wells, with details.max and details.count above the cap).
- An invalid well or pad, or a well without formation, which the read would leave out.
- A stream whose b_min isn't below its b_max, an unset one counting as 0.5 or 2.5.
- A shapefile whose fixed decimals would round a value to one the read drops (on that field or decline.<stream>, suggesting CSV or GeoJSON):
- a tvd_ft, fluid_bbl_per_ft, proppant_lb_per_ft, stage_length_ft, clusters_per_stage or frac_rate_bbl_per_min not over 0 and under its maximum, or a b_min not below its b_max.
- Two wells with the same Heelpoint and Bottom Hole (and Top Hole, in a CSV) to 1e-6°, the same name or none and the same scenario or none, which the read would take as one (on the second's name, with details.wells giving both indexes).
- A shapefile whose .shp, .shx or .dbf would pass 32 MB, or all of them 64 MB, the most the read takes (on format; write CSV or GeoJSON).
- An invalid format, units or name, or unknown body fields.
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
application/json
wellsarray of objectsRequiredat least 1 items
The checked wells to write, at most GET /dataset limits.plan_wells. Values use ft, bbl/ft and lb/ft regardless of output units.
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.
formatstringOptionalDefault
"csv"The file format.
"csv""geojson""shapefile"unitsstringOptionalDefault
"imperial"The output units: imperial ft, bbl/ft, lb/ft or metric m, m3/m, t/m.
"imperial""metric"namestringOptionalDefault
"inventory"1 to 100 charactersThe filename stem, 1 to 100 characters once trimmed; characters outside [A-Za-z0-9 ._-] become underscores.
eur_waterbooleanOptionalDefault
falseAlso write each well's flat decline settings into the water columns, so they read back as decline.water with POST /inventories/read eur_water: true. Default false, as on the read.
Responses
200 OK
The inventory file.
Returns text/csv or application/zip.
object
Errors
| Status | When |
|---|---|
| 413 | The request body is over 64 MB. |
Shared errors400401403500503What they mean