Skip to content
Developers
Get an API token

Place wells in a gun barrel

A gun barrel (cross-section) of drawn and existing wells, with every formation's structure top across it.

Place wells in a gun barrel

POST/gun-barrels

A gun barrel (cross-section) of drawn and existing wells, with every formation's structure top across it. Each well is placed at its lateral's midpoint, across and along one section line.

Send a Novi API token as a bearer token on every request. Authentication
What you send

wells (drawn), keys (existing) or both, up to 200 in all. Keep a gun barrel to one pad or unit: wells far apart or at an angle still project at their midpoints. For a plan's wells, read them with GET /plans/{id}?include=wells and send their ends with tvd_ft from estimates.

The line

Without line, the section runs square to the laterals (each heel to toe, flipped to agree with the first) through center, the mean of their midpoints, at their mean direction. across_ft is + right looking along azimuth_deg, as a spacing neighbor's signedxy for a well drilled that way. For parallel wells, the difference of two across_ft is their horizontal spacing and of two tvd_ft their vertical offset, + deeper (as signedtvd).

Well TVDs

tvd_source says in words where each tvd_ft came from; include: ["tvd_from"] adds it as a code.

  • A drawn well's is the TVD a forecast would use: tvd_ft as sent, else its formation top + landing_below_top_ft or landing_fraction of its thickness, else POST /tvd-estimates' estimate.
  • An existing well's is its header tvd_td, or POST /tvd-estimates' estimate at its ends for a header that is a multiple of 500 ft (a placeholder, except in a set whose depth pack says its wells are subsea).
  • In a set labelled from its own structure grids (formation_labels in GET /model-sets) with a depth pack, an existing well whose header lies outside its formation is drawn a foot inside its nearer top or base.
Survey stations

In a set whose depth pack carries them, an existing well's TVD is found in this order: its survey, the placeholder estimate, the move inside its formation, then the deeper-end read. These only draw wells: forecasts and POST /tvd-estimates still read header TVDs.

  • Survey: where its formation's grid reaches 3 or more of its lateral stations, top_ft plus the median of each station's TVD less the top there, whatever its header.
  • Deeper end: in a set where 95% of surveyed wells' header TVDs are within 5 ft of their deepest station, top_ft plus its header tvd_td less the top at its deeper end.
  • Both need ground elevation at the surface hole, unless the pack declares KB TVD structure grids; without it, the well is drawn as in a set without surveys.
Horizons

Every formation with a structure grid, a depth pack's TVD-only grids included, top to bottom in the rock column, ranked from the grids as landing_fraction ranks its base, not in GET /formations order. Formations on one surface, and after them those with no place in the column (no grid value at any sample point), follow GET /formations order. When the column can't be built (no subsurface model), all come in GET /formations order, and the next call tries again. top_ft is the well's own formation's top, averaged at its surface and bottom holes; it and the horizon tops are in the set's TVD datum (see top_ft).

KB along the line

With a pack that has an elevation grid, a horizon sample's KB elevation is taken at the mean along position of the placed wells' surface holes, so a well can sit off its horizon by up to the ground's change between its surface hole and that position. It is averaged at the section's two ends instead when:

  • the surface holes spread along the line by more than half of along_range_ft (wells drilled from both ends, each then off by about half the ground's change between the ends);
  • no placed well has a surface hole location; or
  • that line would leave any well's top_ft further from its own horizon than the two-end line does.

A well whose surface hole lies off its lateral also misses its horizon by up to the grid's change between its surface hole and the section's ends. Stacked wells under different ground can't share one KB line: each misses it by its own KB elevation's difference from the line's.

A sample with no ground elevation at its point (on the two-end line, at either end) is null, never bridged.

Subsea depths

datum: "subsea" answers in ft below sea level, to compare wells whatever their KB elevation (see datum). A subsea answer is for drawing: the tvd_ft you send stays KB, so send an edit as a landing (landing_below_top_ft from that answer's top_ft, or landing_fraction) or a KB tvd_ft from an answer without datum.

Errors

A well whose TVD can't be found, or an existing well without both ends, comes back with nulls and an error, not a 400. When no well has both ends, the answer is a 400 naming keys.

Parameters

Query parameters

  • model_setstringOptional

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

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

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

Request bodyRequired

application/json

Drawn wells, existing keys or both, 200 in all, and optionally the line to measure about and the extras to add.

Send at least one of: wells or keys.

  • wellsarray of objectsOptional

    1 to 200 items

    Drawn wells, as POST /forecasts takes them, without fluid_bbl_per_ft, proppant_lb_per_ft, decline or name: a gun barrel forecasts nothing, so they are a 400.

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

      Surface hole location, [lng, lat].

    • bhl[number, number]Required

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

    • formationstring or nullOptional

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

    • tvd_ftnumber or nullOptional

      > 0, < 40000

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

    • landing_below_top_ftnumber or nullOptional

      > -40000, < 40000

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

    • heel[number, number] or nullOptional

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

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

    • typed_lateralobject or nullOptional

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

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

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

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

      ShowHide 3 child fields
      • length_ftnumberRequired

        ≥ 0, ≤ 1000000

        The typed length, ft.

      • heel[number, number]Required

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

      • bhl[number, number]Required

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

    • lateral_outsidestring or nullOptional

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

      "above""below"
    • landing_fractionnumber or nullOptional

      ≥ 0, ≤ 1

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

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

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

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

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

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

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

    • lateral_length_ftnumber or nullOptional

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

    • til_datestring or nullOptional

      Format date

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

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

    • partinteger or nullOptional

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

    Show all 22 fields
    • benchinteger or nullOptional

      Ignored.

    • padnumber or string or nullOptional

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

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

    • scenariostringOptional

      1 to 60 characters

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

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

    • fluid_bbl_per_ftnumber or nullOptional

      > 0, < 1000

      This well's fluid in bbl per lateral ft.

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

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

    • proppant_lb_per_ftnumber or nullOptional

      > 0, < 20000

      This well's proppant in lb per lateral ft.

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

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

    • stage_length_ftnumber or nullOptional

      > 0, < 2000

      Stage length in ft.

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

    • clusters_per_stagenumber or nullOptional

      > 0, < 100

      Perforation clusters per stage; fractions are accepted.

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

    • frac_rate_bbl_per_minnumber or nullOptional

      > 0, < 500

      Frac pump rate in bbl per minute.

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

    • declineobjectOptional

      EUR settings for this well; needs eur on.

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

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

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

      ShowHide 7 child fields
      • eur_yearsintegerOptional

        ≥ 10, ≤ 50

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

      • terminal_declinenumberOptional

        ≥ 0.01, ≤ 0.2

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

      • b_minnumberOptional

        ≥ 0, ≤ 2.5

        Lowest hyperbolic b the fit may use; below b_max.

      • b_maxnumberOptional

        ≥ 0, ≤ 2.5

        Highest hyperbolic b the fit may use; above b_min.

      • oilobjectOptional

        Oil's own settings over these.

        ShowHide 3 child fields
        • terminal_declinenumberOptional

          ≥ 0.01, ≤ 0.2

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

        • b_minnumberOptional

          ≥ 0, ≤ 2.5

          Lowest hyperbolic b the fit may use; below b_max.

        • b_maxnumberOptional

          ≥ 0, ≤ 2.5

          Highest hyperbolic b the fit may use; above b_min.

      • gasobjectOptional

        Gas's own settings over these.

        Same fields as StreamDeclineSettings.

      • waterobjectOptional

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

        Same fields as StreamDeclineSettings.

    • namestring or nullOptional

      up to 60 characters

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

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

  • keysarray of stringsOptional

    1 to 200 itemsItems 1 to 200 characters

    Existing wells, as GET /wells lists them; a repeat is answered once but counts toward the limit.

  • lineobject or nullOptional

    Optional: the section line to measure about, instead of the one the laterals give. Send it to keep one line while the wells change (a pad's center and azimuth, so moving one row leaves the other rows' offsets as they were), or to cut a section along any line you draw, wells crossing it at an angle included. Absent or null, the line comes from the laterals.

    ShowHide 2 child fields
    • center[number, number]Required

      A point as [longitude, latitude] in WGS 84 degrees.

    • azimuth_degnumberRequired

      ≥ -360, ≤ 360

      Degrees clockwise from north, -360 to 360; the answer gives it in [0, 360). along_ft is + toward it, across_ft + to its right.

  • includearray of stringsOptional

    up to 2 itemsunique items

    Optional: extras per well. Send ends to draw each lateral heel to toe, tvd_from to branch on where each TVD came from.

    "ends""tvd_from"
  • datumstringOptional

    Optional: the depth datum to answer in. subsea: tvd_ft, top_ft and horizon tops in ft below sea level (TVDss), so wells compare across KB elevation; each field says how it is converted. kb or absent: the set's TVD datum.

    subsea needs a depth pack with ground elevation: a pack of KB TVD grids, or a set without a pack, answers as without it (no tvd_datum.subsea). A pack whose wells already are subsea answers subsea either way. The tvd_ft you send on wells stays KB.

    "kb""subsea"

Responses

200 OK

The line, the horizons and the wells, drawn wells first, in request order.

  • azimuth_degnumberRequired

    ≥ 0, < 360

    The line's direction, degrees clockwise from north, in [0, 360): the laterals' mean heel to toe, to 0.1, or line.azimuth_deg brought into that range (as sent when it already is).

  • center[number, number]Required

    A point as [longitude, latitude] in WGS 84 degrees.

  • along_range_ftarray of integersRequired

    2 items

    [from, to]: where the laterals start and end along the line, ft from center; horizons are averaged at these two.

  • sample_across_ftarray of integersRequired

    21 items

    21 offsets, evenly spaced from the leftmost lateral less a margin to the rightmost plus it (the larger of 660 ft and a tenth of the wells' spread across).

  • horizonsarray of objectsRequired

    Every formation with a structure grid (a depth pack's TVD-only ones included), top to bottom in the rock column that landing_fraction takes its base from; POST /gun-barrels says the order within one surface, outside the column, and when the column can't be built. Empty without grids.

    ShowHide 2 child fields in each item
    • formationstringRequired

      Formation, as GET /formations names it.

    • top_ftarray of integersRequired

      21 items

      Its structure top at each sample_across_ft offset.

  • wellsarray of objectsRequired

    The wells, drawn first, in request order.

    ShowHide 15 child fields in each item
    • kindstringRequired

      drawn (from wells) or existing (from keys).

      "drawn""existing"
    • formationstring or nullRequired

      Its formation.

    • across_ftinteger or nullRequired

      Its lateral midpoint's offset square to the line, ft, + right looking along azimuth_deg; null without both ends.

    • along_ftinteger or nullRequired

      Its lateral midpoint's offset along the line, ft, + in the direction of azimuth_deg; null without both ends.

    • tvd_ftnumber or nullRequired

      TVD, ft: as a forecast would use it (drawn) or the header's tvd_td (existing); null when there is none.

      • Existing: the estimate instead when tvd_td is a multiple of 500 ft; drawn by its survey stations, or by tvd_td at its deeper end, in a set whose depth pack carries them.
      • With datum subsea (tvd_datum.subsea true): that TVD less the KB elevation at its surface hole, ft below sea level, to the foot; null with an error where the pack has no ground elevation there or the well has no surface hole location.
    • tvd_sourcestring or nullRequired

      input, how it was placed or estimated, or header; null without tvd_ft.

    • top_ftinteger or nullRequired

      Its formation's structure top at the well, ft below the set's TVD datum (tvd_datum: its KB, so tvd_ft − top_ft is the landing; without it, the grid's subsea depth); null without a formation or grid there, or, with a depth pack in KB, no ground elevation at its surface hole. With datum subsea (tvd_datum.subsea true): the grid's own subsea depth, so tvd_ft − top_ft is still the landing.

    • indexintegerOptional

      ≥ 0

      Drawn: its index in wells.

    • wellbore_keystringOptional

      Existing: its wellbore key.

    • well_namestring or nullOptional

      Existing: its name.

    • first_prodstring or nullOptional

      Format date

      Existing: its first production, to order vintages.

    • heel_along_ftinteger or nullOptional

      With include ends: its lateral's heel on along_ft's axis, ft: a drawn well's heel, else its shl, an existing well's header heel, else its surface hole; null without both ends.

    Show all 15 fields
    • toe_along_ftinteger or nullOptional

      With include ends: its lateral's toe (bottom hole) on along_ft's axis, ft; less than heel_along_ft for a well drilled against azimuth_deg; null without both ends.

    • tvd_fromstring or nullOptional

      With include tvd_from: where tvd_ft came from, as a code; null without tvd_ft.

      • input: tvd_ft sent.
      • landing: the formation top + landing_below_top_ft sent, or landing_fraction of its thickness.
      • estimate: POST /tvd-estimates' estimate; on an existing well, one replacing a placeholder tvd_td, or a tvd_td outside its formation moved a foot inside it (sets labelled from their grids).
      • header: an existing well's tvd_td, read at its deeper end where the set's depth pack has survey stations and its header TVDs are their wells' deepest stations.
      • survey: an existing well drawn by its survey stations.
      "input""landing""estimate""header""survey"
    • errorstringOptional

      Why tvd_ft or the offsets are null.

  • tvd_datumobjectOptional

    Optional: the TVD datum the set's depth pack puts tops in, present only for a model set with a depth pack. Absent: tops are the structure grid's own subsea depth. POST /gun-barrels with datum subsea adds subsea: true when it answers below sea level, as every answer does for a pack whose wells are subsea.

    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.

Errors

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean