Skip to content
Developers
Get an API token

List the PDP wells near drawn wells

GET /plans/{id}/pdp-wells for drawn wells that aren't in a plan yet, such as a gun barrel's drawn pad before a plan runs: existing wells near them, parallel to them and producing by their first TIL date, nearest first, by the same rule.

List the PDP wells near drawn wells

POST/pdp-wells

GET /plans/{id}/pdp-wells for drawn wells that aren't in a plan yet, such as a gun barrel's drawn pad before a plan runs: existing wells near them, parallel to them and producing by their first TIL date, nearest first, by the same rule.

Send a Novi API token as a bearer token on every request. Authentication
The body

wells as POST /gun-barrels takes them (drawn, as POST /forecasts takes them, without fluid_bbl_per_ft, proppant_lb_per_ft, decline or name), up to 500, and the GET's options: azimuth_deg, center, along, limit, reach, cross and include. cross is two points, [[lngA, latA], [lngB, latB]]; the sent wells only date the wells it picks, and a point out of range is a 400 naming cross[0] or cross[1]. include: ["left_out"] is the GET's include=left_out.

The rule

The rule, scope and every field are GET /plans/{id}/pdp-wells' (its description has them in full), with the sent wells as the scope. A well's TIL date is its own til_date, else today (UTC), as POST /forecasts places an undated well. There is no request-wide date, so send one date on every well; scope.til_date is the earliest. scope.indexes are the wells' positions in wells, 0 to n-1.

A done plan's wells sent in plan order, each with its shl, heel, bhl and TIL date, answer the same body as GET /plans/{id}/pdp-wells on that plan when those dates are on or after the dataset's as_of.

Errors

A TIL date before the dataset's as_of is a 400. Wells spread past GET /wells' 100 mi radius are a 400 naming wells: send fewer, closer wells, as one pad's.

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

Up to 500 drawn wells, each with an optional til_date, and the options.

  • wellsarray of objectsRequired

    1 to 500 items

    Drawn wells, as POST /gun-barrels takes them: fluid_bbl_per_ft, proppant_lb_per_ft, decline or name is a 400. Each well's til_date dates it; a well without one comes online today (UTC).

    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.

  • azimuth_degnumberOptional

    ≥ -360, ≤ 360

    The section line's azimuth, as GET /plans/{id}/pdp-wells takes it: degrees clockwise from north, -360 to 360, brought into [0, 360). Absent: the wells' mean heel-to-toe direction to 0.1°.

  • center[number, number]Optional

    The section line's center, as GET /plans/{id}/pdp-wells takes center: it moves no candidate. Absent: the wells' mean midpoint, to 1e-7°.

  • alongstringOptional

    section: keep only wells whose lateral overlaps the wells' heel-to-toe range along the section line, as GET /plans/{id}/pdp-wells does. Absent: no such cut.

    "section"
  • limitintegerOptional

    Default 50≥ 1, ≤ 50

    The most wells to return, nearest first: 1 to 50. matched still counts them all.

  • reachstringOptional

    laterals: candidates are the wells with any part of their lateral within margin_mi of any sent well's lateral, as GET /plans/{id}/pdp-wells takes reach. Absent: the circle around the midpoints.

    "laterals"
  • crossarray of [number, number]sOptional

    2 items

    A line A-B drawn across the laterals, [A, B]: the wells whose laterals cross A-B, as GET /plans/{id}/pdp-wells takes cross; the sent wells only date them. Not with azimuth_deg, center, along or reach. Absent: the circle around the midpoints.

  • includearray of stringsOptional

    up to 1 itemsunique items

    Optional: left_out adds left_out, as GET /plans/{id}/pdp-wells' include=left_out.

    "left_out"

Responses

200 OK

The scope and the PDP wells.

  • scopeobjectRequired

    What the rule measured from. center is the section line's center: center as sent, else the mean of the scope wells' lateral midpoints to 1e-7°, as POST /gun-barrels gives it; with cross, the mean of A and B to 1e-7°.

    radius_mi, and each distance_ft without reach, are measured from that mean, unrounded; with reach=laterals, distance_ft is the gap to the nearest scope well's lateral.

    ShowHide 11 child fields
    • indexesarray of integersRequired

      Items ≥ 0

      The plan wells measured from, ascending: wells as sent, else every well. POST /pdp-wells: every sent well's position in wells, 0 to n-1.

    • center[number, number]Required

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

    • radius_minumberRequired

      > 0

      How far from the scope wells' mean midpoint candidates were looked for, mi (not from a sent center): the farthest scope well midpoint plus margin_mi, rounded to 0.01. With reach=laterals it is still given, but picks no well. With cross: from the mean of A and B, half A-B plus 25,000 ft, rounded to 0.01.

    • azimuth_degnumberRequired

      ≥ 0, < 360

      The section line's azimuth, degrees clockwise from north in [0, 360): azimuth_deg as sent (brought into that range), else the scope wells' mean heel-to-toe direction to 0.1, as POST /gun-barrels gives it for them. With cross: square to A-B, A-B's bearing less 90, to 0.1.

    • til_datestringRequired

      Format date

      The earliest TIL date of the scope wells: kept wells first produced on or before it.

    • margin_minumberRequired

      Always 0.5

      The margin added to the radius, mi; with reach=laterals, also how far from any scope well's lateral a kept lateral may lie.

    • parallel_degnumberRequired

      Always 15

      How far a kept lateral may turn from the line, either way along it, degrees.

    • crossarray of [number, number]sOptional

      2 items

      With cross: A and B, as sent.

    • reachstringOptional

      With reach=laterals: laterals.

      "laterals"
    • alongstringOptional

      With along=section: section.

      "section"
    • along_range_ftarray of integersOptional

      2 items

      With along=section: [from, to], the scope wells' heel-to-toe range on the line; a kept lateral overlaps it.

  • matchedintegerRequired

    ≥ 0

    Wells that passed every cut, before limit.

  • wellsarray of objectsRequired

    up to 50 items

    The nearest limit of them, nearest first, ties by wellbore key.

    ShowHide 7 child fields in each item
    • wellbore_keystringRequired

      Wellbore key, as GET /wells lists it.

    • well_namestring or nullRequired

      Well name.

    • operatorstring or nullRequired

      Operator.

    • formationstring or nullRequired

      Landing formation.

    • first_prodstringRequired

      Format date

      First production, YYYY-MM-DD: on or before scope.til_date.

    • lateral_length_ftnumber or nullRequired

      Lateral length, ft, as GET /wells lateral_length: to normalise its production per 1,000 ft.

    • distance_ftintegerRequired

      ≥ 0

      From the scope wells' mean midpoint (unrounded; scope.center without a sent center) to its lateral midpoint, ft, as GET /wells near measures it, rounded. With reach=laterals: the gap from its lateral to the nearest scope well's lateral, ft, rounded. With cross: from the mean of A and B (unrounded) to its lateral midpoint, ft, rounded.

  • left_outobjectOptional

    With include=left_out: the wells the TIL date and limit leave out.

    ShowHide 2 child fields
    • til_dateintegerRequired

      ≥ 0

      Wells that passed every other cut but first produced after scope.til_date or have no first production.

    • limitintegerRequired

      ≥ 0

      Wells past limit: matched less the wells returned.

Errors

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean