Get a well's subsurface column
A well's subsurface column: each formation's top, base, gross and net thickness and BVI at this well, in rock-column order, with the well's landing on the same axis.
Get a well's subsurface column
/wells/{key}/subsurfaceA well's subsurface column: each formation's top, base, gross and net thickness and BVI at this well, in rock-column order, with the well's landing on the same axis. include=inferred fills gaps from offset wells.
The column
Every formation the model set grids, shallowest first, in the rock column POST /gun-barrels draws its horizons in, a depth pack's TVD-only grids included. Formations on one surface keep GET /formations order; formations with no place in the column, the well's own among them when no grid names it, follow in GET /formations order. A structure grid named novi_structuraldepth or novi_structural_depth is the top, the first when a formation has both. Grids whose formation is all (fault distances, a CO2 band and the like) are in well_wide; a formation's grids beyond the five are in its other.
Values
Each value's state is mapped, inferred or none, and every null carries a reason. Mapped values are interpolated where the set reads its grids, as GET /subsurface/sample reads them, not picked on this well's logs. Depths are on the datum axis: ft relative to sea level, negative below it (the opposite sign to a gun barrel's TVDss), or, where the depth pack declares KB TVD structure grids, ft below KB, positive down.
Landing
landing is the well's own formation's landing: its depth below its formation's top at the bottom hole, placed under the column's top.
- It comes from the header TVD (POST /gun-barrels' estimate for a placeholder header, a multiple of 500 ft) less the KB elevation at the surface hole, the TVDss POST /gun-barrels gives with
datum: "subsea". A pack whose wells are subsea takes the TVD as it is. - With survey stations in the depth pack, it follows POST /gun-barrels' order: survey, placeholder estimate, zone move, deeper-end read.
- It is null, with a
reason, without a depth pack that has ground elevation or subsea wells, where the pack has no ground elevation, or, with no survey to place it, without a header TVD or at a placeholder header with no estimate.
Inferred values
include=inferred fills nulls from offset wells by the first rule that applies, and adds offset_wells, unassigned, a summary and the fixed params. Mapped values never change.
- Rule 1, closure: a gross thickness is this formation's mapped top to the next formation's mapped top below it (
rule: closure, grade high,plus_minusnull), only while every formation the set grids has a place in the column; otherwise the reason names the one that hasn't. - Rule 2, offsets: wells whose midpoint lies within 1.5 mi of this well's, same pad first, then nearest: the first 8 with the value mapped, at least 3, weighted by inverse distance squared.
- Under rule 2, a top is its
anchor's mapped top (the nearest formation above with one) plus the offsets' weighted mean distance below it. Gross and BVI are weighted means; net is their weighted net-to-gross times this well's gross. - Rule 3, fit: between two mapped tops, the inferred gross thicknesses, scaled by one factor (
scale), fill the gap, each inferred top at the base above it. It fits when the thicknesses come within 15% of the gap and the factor within 15% of 1; else each mismatch is inunassigned. - Rule 4, grade: high with at least 5 offsets, every one within 1 mi, and a coefficient of variation (CV) under 10%; medium with a CV under 25%. Otherwise the value stays none, with a reason after "Not inferred:" naming the count or the CV.
- A top's CV is taken on its distance below the anchor. An inferred net takes the lower grade of its net-to-gross and gross.
plus_minusis the offsets' weighted standard deviation, scaled with a fitted gross. Offsets aren't limited by fault block.
Display only
No forecast, plan or model input reads these values.
Parameters
Path parameters
keystringRequiredWellbore key, as SB329-01414. GET /wells/facets, /wells/search, /wells/typecurve and /wells/production are paths, not wells: keys are API numbers or SBnnn-nnnnn, so no well is shadowed.
Query parameters
includestringOptionalinferredfills null values from offset wells by the four rules above and adds offset_wells, unassigned, summary and params. Absent: grid samples only."inferred"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.
Responses
200 OK
The column, the landing and, with include=inferred, the inference.
wellbore_keystringRequiredThe well.
formationstring or nullRequiredThe well's own formation (its landing zone).
datumobjectRequiredThe datum of every depth in this answer. subsea true: ft relative to sea level, negative below it, as the structure grids hold them (not a gun barrel's positive-down TVDss). Absent subsea (a depth pack that declares KB TVD structure grids): ft below the wells' KB, positive down. kb_offset_ft and elevation_source are the depth pack's, null without one.
ShowHide 4 child fields
datumstringRequiredkb: tops and TVDs are ft below the kelly bushing, the datum of the set's header TVDs. subsea true overrides it: every depth in that answer is ft below sea level, whatever datum says.
"kb"kb_offset_ftnumber or nullRequiredThe KB height above ground, ft, added to the ground elevation; when the set's structure grids already are KB TVDs, as the pack declares it (null if it declares none); null when the set's well TVDs already are ft below sea level.
elevation_sourcestring or nullRequiredWhere the ground elevation comes from (as USGS 3DEP bare earth); null when the set's structure grids already are KB TVDs or its well TVDs already are ft below sea level.
subseabooleanOptionalPresent, and true, when the answer's depths are ft below sea level (TVDss); absent, they are in
datum. Label depths by subsea === true, not by datum, which stays kb in a subsea answer.Present on a POST /gun-barrels answer to datum subsea for a pack with ground elevation. Also on every POST /tvd-estimates and POST /gun-barrels answer for a pack whose wells' TVDs already are subsea, with or without datum subsea: tops are the grid's own subsea depth and every TVD (header, estimated or sent) stays as it is.
formationsarray of objectsRequiredRock-column order, shallowest first; formations with no place in the column after.
ShowHide 9 child fields in each item
formationstringRequiredFormation.
labelstringRequiredDisplay name.
top_ftobjectRequiredStructure top, on the datum's axis.
ShowHide 11 child fields
valuenumber or nullRequiredThe value, null when there is none.
statestringRequiredmapped: interpolated from the set's grids; inferred: from the include=inferred rules; none: no value, with a reason.
"mapped""inferred""none"grid_distance_minumberOptionalThe grid's distance from the well, mi: the mean over the points the set reads (its
subsurface_samplingin GET /model-sets), each 0 inside it (GET /subsurface/sample's _novi_dist, in miles).rulestringOptionalclosure (rule 1) or offsets (rule 2).
"closure""offsets"gradestringOptionalRule 4's grade.
"high""medium"offsetsintegerOptionalOffset wells behind it.
farthest_minumberOptionalThe farthest of them, mi.
plus_minusnumber or nullOptionalThe offsets' weighted standard deviation, in the value's unit, scaled with a gross rule 3 fit; null for a closure, with a reason.
anchorstringOptionalAn inferred top's anchor: the formation above whose mapped top it is measured from.
scalenumberOptionalRule 3's factor, on each inferred value in a window it fit: a gross scaled by it, a top moved to the base above.
reasonstringOptionalWhy it is none (after "Not inferred:", why the rules left it none), or for a closure why plus_minus is null.
base_ftobjectRequiredTop less gross thickness (plus, on a KB datum): mapped when both are, inferred (with the lower grade) when either is, none with a reason otherwise.
Same fields as SubsurfaceValue.
gross_ftobjectRequiredGross thickness, ft.
Same fields as SubsurfaceValue.
net_ftobjectRequiredNet thickness, ft.
Same fields as SubsurfaceValue.
bvi_avgobjectRequiredBVI average, a fraction.
Same fields as SubsurfaceValue.
bvi_netobjectRequiredBVI net, a fraction.
Same fields as SubsurfaceValue.
otherarray of objectsRequiredThe formation's other grids (porosity, saturation and the like), by rock property.
ShowHide 13 child fields in each item
rock_propertystringRequiredThe grid's rock property.
feature_namestringRequiredThe grid, as GET /subsurface names it.
valuenumber or nullRequiredThe value, null when there is none.
statestringRequiredmapped: interpolated from the set's grids; inferred: from the include=inferred rules; none: no value, with a reason.
"mapped""inferred""none"grid_distance_minumberOptionalThe grid's distance from the well, mi: the mean over the points the set reads (its
subsurface_samplingin GET /model-sets), each 0 inside it (GET /subsurface/sample's _novi_dist, in miles).rulestringOptionalclosure (rule 1) or offsets (rule 2).
"closure""offsets"gradestringOptionalRule 4's grade.
"high""medium"offsetsintegerOptionalOffset wells behind it.
farthest_minumberOptionalThe farthest of them, mi.
plus_minusnumber or nullOptionalThe offsets' weighted standard deviation, in the value's unit, scaled with a gross rule 3 fit; null for a closure, with a reason.
anchorstringOptionalAn inferred top's anchor: the formation above whose mapped top it is measured from.
scalenumberOptionalRule 3's factor, on each inferred value in a window it fit: a gross scaled by it, a top moved to the base above.
reasonstringOptionalWhy it is none (after "Not inferred:", why the rules left it none), or for a closure why plus_minus is null.
well_widearray of objectsRequiredGrids whose formation is all: well-wide properties, not a formation.
Same fields as WellSubsurfaceProperty.
landingobjectRequiredWhere the well lands in its formation.
ShowHide 5 child fields
formationstring or nullRequiredThe well's formation.
depth_ftnumber or nullRequiredThe landing on the datum's axis, placed by its depth below its formation's top at the bottom hole (with survey stations in the set's depth pack: by POST /gun-barrels' survey or deeper-end landing); null with a reason.
tvd_fromstring or nullRequiredheader: its header TVD; estimate: the guarded estimate for a placeholder header; survey: its survey stations.
"header""estimate""survey"sourcestring or nullRequiredHow the depth was found, in words.
reasonstringOptionalWhy there is no depth.
offset_wellsarray of objectsOptionalWith include=inferred: every offset well an inferred value used, nearest first.
ShowHide 5 child fields in each item
wellbore_keystringRequiredThe offset well.
well_namestring or nullRequiredIts name.
distance_minumberRequiredMidpoint to midpoint, mi.
same_padbooleanRequiredOn this well's pad (spacing pad id).
usedarray of objectsRequiredThe values it gave, by formation.
ShowHide 3 child fields in each item
formationstringRequiredFormation.
fieldstringRequiredtop_below_anchor_ft: its top's distance below the anchor's top; net_to_gross: its net over gross; else its value of that field.
"top_below_anchor_ft""gross_ft""net_to_gross""bvi_avg""bvi_net"valuenumberRequiredWhat it gave.
unassignedarray of objectsOptionalWith include=inferred: every place where a base and the next top don't meet and one of them is inferred, as rule 3 left it.
ShowHide 6 child fields in each item
kindstringRequiredgap: the base is above the next top; overlap: the base runs past it.
"gap""overlap"abovestringRequiredThe formation whose base it is.
belowstringRequiredThe next formation, whose top it is.
top_ftnumberRequiredInterval top, on the datum's axis.
base_ftnumberRequiredInterval base, on the datum's axis.
thickness_ftnumberRequiredInterval thickness, ft, positive.
summaryobjectOptionalWith include=inferred: counts.
ShowHide 4 child fields
inferredintegerRequiredValues inferred.
refusedintegerRequiredValues tried and left none.
offset_wellsintegerRequiredOffset wells used.
farthest_minumber or nullRequiredThe farthest one used, mi.
paramsobjectOptionalWith include=inferred: the fixed rule parameters.
ShowHide 8 child fields
radius_minumberRequiredOffsets within this distance.
max_offsetsintegerRequiredAt most this many per value.
min_offsetsintegerRequiredAt least this many per value.
weightsstringRequiredOffset weights.
"inverse_distance_squared"fit_withinnumberRequiredRule 3 scales a stack within this fraction of its gap.
highobjectRequiredGrade high.
ShowHide 3 child fields
min_offsetsintegerRequiredAt least this many offsets.
within_minumberRequiredEvery one within this, mi.
max_cvnumberRequiredCV under this.
mediumobjectRequiredGrade medium.
ShowHide 3 child fields
min_offsetsintegerRequiredOffsets.
within_minumberRequiredmi.
max_cvnumberRequiredCV under this.
fault_blocksstringRequiredOffsets are not limited by fault block.
304 Unchanged since the ETag in If-None-Match.Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
Shared errors400401403500503What they mean