Skip to content
Developers
Get an API token

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

GET/wells/{key}/subsurface

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. include=inferred fills gaps from offset wells.

Send a Novi API token as a bearer token on every request. Authentication
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_minus null), 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 in unassigned.
  • 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_minus is 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

  • keystringRequired

    Wellbore 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

  • includestringOptional

    inferred fills null values from offset wells by the four rules above and adds offset_wells, unassigned, summary and params. Absent: grid samples only.

    "inferred"
  • 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.

Responses

200 OK

The column, the landing and, with include=inferred, the inference.

  • wellbore_keystringRequired

    The well.

  • formationstring or nullRequired

    The well's own formation (its landing zone).

  • datumobjectRequired

    The 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
    • datumstringRequired

      kb: 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 nullRequired

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

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

    • subseabooleanOptional

      Present, 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 objectsRequired

    Rock-column order, shallowest first; formations with no place in the column after.

    ShowHide 9 child fields in each item
    • formationstringRequired

      Formation.

    • labelstringRequired

      Display name.

    • top_ftobjectRequired

      Structure top, on the datum's axis.

      ShowHide 11 child fields
      • valuenumber or nullRequired

        The value, null when there is none.

      • statestringRequired

        mapped: interpolated from the set's grids; inferred: from the include=inferred rules; none: no value, with a reason.

        "mapped""inferred""none"
      • grid_distance_minumberOptional

        The grid's distance from the well, mi: the mean over the points the set reads (its subsurface_sampling in GET /model-sets), each 0 inside it (GET /subsurface/sample's _novi_dist, in miles).

      • rulestringOptional

        closure (rule 1) or offsets (rule 2).

        "closure""offsets"
      • gradestringOptional

        Rule 4's grade.

        "high""medium"
      • offsetsintegerOptional

        Offset wells behind it.

      • farthest_minumberOptional

        The farthest of them, mi.

      • plus_minusnumber or nullOptional

        The offsets' weighted standard deviation, in the value's unit, scaled with a gross rule 3 fit; null for a closure, with a reason.

      • anchorstringOptional

        An inferred top's anchor: the formation above whose mapped top it is measured from.

      • scalenumberOptional

        Rule 3's factor, on each inferred value in a window it fit: a gross scaled by it, a top moved to the base above.

      • reasonstringOptional

        Why it is none (after "Not inferred:", why the rules left it none), or for a closure why plus_minus is null.

    • base_ftobjectRequired

      Top 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_ftobjectRequired

      Gross thickness, ft.

      Same fields as SubsurfaceValue.

    • net_ftobjectRequired

      Net thickness, ft.

      Same fields as SubsurfaceValue.

    • bvi_avgobjectRequired

      BVI average, a fraction.

      Same fields as SubsurfaceValue.

    • bvi_netobjectRequired

      BVI net, a fraction.

      Same fields as SubsurfaceValue.

    • otherarray of objectsRequired

      The formation's other grids (porosity, saturation and the like), by rock property.

      ShowHide 13 child fields in each item
      • rock_propertystringRequired

        The grid's rock property.

      • feature_namestringRequired

        The grid, as GET /subsurface names it.

      • valuenumber or nullRequired

        The value, null when there is none.

      • statestringRequired

        mapped: interpolated from the set's grids; inferred: from the include=inferred rules; none: no value, with a reason.

        "mapped""inferred""none"
      • grid_distance_minumberOptional

        The grid's distance from the well, mi: the mean over the points the set reads (its subsurface_sampling in GET /model-sets), each 0 inside it (GET /subsurface/sample's _novi_dist, in miles).

      • rulestringOptional

        closure (rule 1) or offsets (rule 2).

        "closure""offsets"
      • gradestringOptional

        Rule 4's grade.

        "high""medium"
      • offsetsintegerOptional

        Offset wells behind it.

      • farthest_minumberOptional

        The farthest of them, mi.

      • plus_minusnumber or nullOptional

        The offsets' weighted standard deviation, in the value's unit, scaled with a gross rule 3 fit; null for a closure, with a reason.

      • anchorstringOptional

        An inferred top's anchor: the formation above whose mapped top it is measured from.

      • scalenumberOptional

        Rule 3's factor, on each inferred value in a window it fit: a gross scaled by it, a top moved to the base above.

      • reasonstringOptional

        Why it is none (after "Not inferred:", why the rules left it none), or for a closure why plus_minus is null.

  • well_widearray of objectsRequired

    Grids whose formation is all: well-wide properties, not a formation.

    Same fields as WellSubsurfaceProperty.

  • landingobjectRequired

    Where the well lands in its formation.

    ShowHide 5 child fields
    • formationstring or nullRequired

      The well's formation.

    • depth_ftnumber or nullRequired

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

      header: its header TVD; estimate: the guarded estimate for a placeholder header; survey: its survey stations.

      "header""estimate""survey"
    • sourcestring or nullRequired

      How the depth was found, in words.

    • reasonstringOptional

      Why there is no depth.

  • offset_wellsarray of objectsOptional

    With include=inferred: every offset well an inferred value used, nearest first.

    ShowHide 5 child fields in each item
    • wellbore_keystringRequired

      The offset well.

    • well_namestring or nullRequired

      Its name.

    • distance_minumberRequired

      Midpoint to midpoint, mi.

    • same_padbooleanRequired

      On this well's pad (spacing pad id).

    • usedarray of objectsRequired

      The values it gave, by formation.

      ShowHide 3 child fields in each item
      • formationstringRequired

        Formation.

      • fieldstringRequired

        top_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"
      • valuenumberRequired

        What it gave.

  • unassignedarray of objectsOptional

    With 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
    • kindstringRequired

      gap: the base is above the next top; overlap: the base runs past it.

      "gap""overlap"
    • abovestringRequired

      The formation whose base it is.

    • belowstringRequired

      The next formation, whose top it is.

    • top_ftnumberRequired

      Interval top, on the datum's axis.

    • base_ftnumberRequired

      Interval base, on the datum's axis.

    • thickness_ftnumberRequired

      Interval thickness, ft, positive.

  • summaryobjectOptional

    With include=inferred: counts.

    ShowHide 4 child fields
    • inferredintegerRequired

      Values inferred.

    • refusedintegerRequired

      Values tried and left none.

    • offset_wellsintegerRequired

      Offset wells used.

    • farthest_minumber or nullRequired

      The farthest one used, mi.

  • paramsobjectOptional

    With include=inferred: the fixed rule parameters.

    ShowHide 8 child fields
    • radius_minumberRequired

      Offsets within this distance.

    • max_offsetsintegerRequired

      At most this many per value.

    • min_offsetsintegerRequired

      At least this many per value.

    • weightsstringRequired

      Offset weights.

      "inverse_distance_squared"
    • fit_withinnumberRequired

      Rule 3 scales a stack within this fraction of its gap.

    • highobjectRequired

      Grade high.

      ShowHide 3 child fields
      • min_offsetsintegerRequired

        At least this many offsets.

      • within_minumberRequired

        Every one within this, mi.

      • max_cvnumberRequired

        CV under this.

    • mediumobjectRequired

      Grade medium.

      ShowHide 3 child fields
      • min_offsetsintegerRequired

        Offsets.

      • within_minumberRequired

        mi.

      • max_cvnumberRequired

        CV under this.

    • fault_blocksstringRequired

      Offsets are not limited by fault block.

Conditional requests 304 Unchanged since the ETag in If-None-Match.

Errors

StatusWhen
404

No such well, grid, plan or route.

Shared errors400401403500503What they mean