Skip to content
Developers
Get an API token

Fill an area with wells

Parallel wells across a polygon: lines spacing_ft apart at azimuth_deg, clipped to it.

Fill an area with wells

POST/layouts/fill

Parallel wells across a polygon: lines spacing_ft apart at azimuth_deg, clipped to it. Wells are drilled toward the azimuth, so 0 puts surface holes at the south end. Send the wells to POST /plans to forecast them together.

Send a Novi API token as a bearer token on every request. Authentication
Wells per line

With lateral_length_ft, each line's chord holds as many wells of that length as fit end to end.

  • Without it, one well per chord, edge to edge, dropping chords under 95% of the longest. A kept chord over 30,000 ft (between its rounded ends) becomes the fewest equal wells of at most 30,000 ft, toe to heel; the 95% rule still compares whole chords.
  • Chords under 1,000 ft are skipped.
  • With setback_ft (a lease-line setback), every point of every lateral is at least that far from every side, concave areas included.
Even side gaps

The lines start centered across the width (less the setback each side), then move together, by at most half a spacing, so the outermost wells sit as far from the outline on the left as on the right.

  • A gap runs across the azimuth, from an outermost well to the outline's edges beside it within 45° of the azimuth; holes and standoff laterals don't count.
  • The lines stop when the gaps are within 1 ft, or as close as up to 3 more fills get them; a move that leaves them more than 1 ft apart must narrow the difference by at least 1 ft.
  • A move counts only if every bench keeps its count of wells and 99% of its lateral footage, and every lateral stays 100 to 50,000 ft long.
  • Each extra fill runs only within the work limit (see Work limit), so the largest fills keep their centered lines.
Units

Send area instead of polygon to fill a unit as POST /areas reads it (its geometry) or as POST /units/summary takes it. Each part of a MultiPolygon is filled on its own, and each well carries part, its index. Holes are left out: a line's chords stop at a hole's edge, each piece kept by the length rule. A hole that isn't inside its outline is a 400; holes are checked in order up to a fixed amount of checking per request, and past it a hole is taken as sent. POST /forecasts and POST /plans ignore a well's part and bench.

Benches

benches (1 to 10) fills several benches at once, each with its own spacing_ft or wells_per_section, offset_ft and formation. Wells come part by part, then bench by bench; each carries bench, its index, and formation when its bench (or the request) names one.

Standoff

standoff_ft keeps every lateral that far from the existing laterals in its bench's formation that POST /wells/search finds with the same area, match: lateral, buffer_ft = standoff_ft and that formation (the echo's standoff_wells). Chords are cut around them, each piece kept by the length rule. It needs a formation for every bench (the request's formation without benches).

Pads

wells_per_pad groups the wells into pads of that many: per part, by tier (a well's place along its line, heel first), then across the azimuth left to right looking along it, benches together. Each well carries pad, and the echo's pads counts them.

Evening out

Each part evens out its side gaps on its own, every bench's lines moved alike; the gaps are those of the part's outermost wells, of any bench. A part with a non-zero bench offset_ft isn't evened out, and in a plan's layouts one on any layout's bench keeps every layout of the plan centered, so a stagger set across layouts holds.

Work limit

A fill that needs more work than one request may take (about a second) is a 400 "too complex" with details.max_work and details.work. Work is each part's lines times its ring edges (counted twice with setback_end_ft) plus the bench's standoff laterals, summed over parts and benches, at most 1,000,000 (for a plan's layouts, in all).

Evening out never makes a fill refused: it runs only while the work stays within the limit (for layouts, what their own fills leave, layout by layout in order), so a fill near the limit keeps its centered lines. The same request always fares the same: simplify the outline, widen the spacing, or send fewer benches or a smaller standoff_ft.

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

The area and the layout.

Send exactly one of: area or polygon.

Send exactly one of: spacing_ft or benches.

  • polygonarray of [number, number]sOptional

    3 to 500 items

    Area corners, in order (closing point optional). Edges that cross are a 400.

  • azimuth_degnumberOptional

    Default 0≥ -360, ≤ 360

    Direction wells are drilled, degrees clockwise from north.

  • spacing_ftnumberOptional

    ≥ 100, ≤ 10000

    Distance between wells, ft.

  • lateral_length_ftnumber or nullOptional

    ≥ 1000, ≤ 30000

    Lateral length, ft; null or absent runs each well edge to edge.

  • setback_ftnumber or nullOptional

    Default 0≥ 0, ≤ 2640

    Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).

  • areaobjectOptional

    Instead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is).

    ShowHide 2 variants

    One of

    • A polygon object

      A polygon.

      • typeanyRequired

        Always "Polygon"

        One part.

      • coordinatesarray of arraysRequired

        at least 1 itemsItems at least 3 items

        The outer ring, then its holes.

    • A multipolygon object

      A multipolygon.

      • typeanyRequired

        Always "MultiPolygon"

        Several parts, taken together.

      • coordinatesarray of arraysRequired

        at least 1 itemsItems at least 1 items

        The parts.

  • setback_end_ftnumber or nullOptional

    ≥ 0, ≤ 2640

    Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.

  • min_lateral_ftnumber or nullOptional

    ≥ 1000, ≤ 30000

    Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.

    A kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.

  • standoff_ftnumber or nullOptional

    ≥ 0, ≤ 5280

    Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.

  • wells_per_padinteger or nullOptional

    ≥ 1, ≤ 50

    Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.

    A fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's wells with pads. POST /plans keeps pad keys: with layout, the 1-based pad number as text; with layouts, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echo pads) as a plan scenario's wells in POST /economics.

  • lateral_checkbooleanOptional

    Default false

    Mark each well whose lateral is outside the model's training range, as a forecast's checks would flag it. Show the mark beside any lateral or volume you quote for a marked well.

    The model is the first served stream's (oil, else gas, else water) and the range its novi_lateral_length p01 to p99 in ft; a well is marked past it by more than 5% of that range, its lateral measured between its returned ends. Only on POST /layouts/fill: a forecast's or plan's wells carry checks.

  • benchesarray of objectsOptional

    1 to 10 items

    Instead of spacing_ft: benches filled together, each with its own spacing, offset and formation.

    ShowHide 4 child fields in each item

    Send exactly one of: spacing_ft or wells_per_section.

    • spacing_ftnumberOptional

      ≥ 100, ≤ 10000

      Distance between the bench's wells, ft. Not with wells_per_section.

    • wells_per_sectionnumberOptional

      ≥ 0.528, ≤ 52.8

      Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).

    • offset_ftnumber or nullOptional

      Default 0≥ -10000, ≤ 10000

      Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.

      Lines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.

    • formationstring or nullOptional

      The bench's formation (case-insensitive; GET /formations lists them): its wells carry it, and standoff_ft stands off its laterals. Default the request's formation.

  • formationstring or nullOptional

    The wells' formation (case-insensitive; GET /formations lists them), which each well then carries; standoff_ft needs it without benches.

Responses

200 OK

The wells, left to right looking along the azimuth: west to east for an azimuth strictly between -90 and 90 or past 270 either way, the default 0 included.

  • countintegerRequired

    Wells.

  • azimuth_degnumberRequired

    Azimuth used.

  • lateral_length_ftnumber or nullRequired

    Length used, or null for edge to edge.

  • wellsarray of objectsRequired

    Wells, left to right looking along the azimuth (west to east for an azimuth strictly between -90 and 90 or past 270 either way, the default 0 included); with area or benches, part by part, then bench by bench.

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

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

    • bhl[number, number]Required

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

    • lateral_length_ftintegerRequired

      Lateral length, ft.

    • formationstringOptional

      Its bench's formation, else the request's; only when one is known.

    • partintegerOptional

      ≥ 0

      With area: the index of its part in the MultiPolygon, 0 in a Polygon.

    • benchintegerOptional

      ≥ 0

      With benches: its bench's index.

    • padintegerOptional

      ≥ 0

      With wells_per_pad: its pad, from 0.

    • lateral_outsidestring or nullOptional

      Above or below the training lateral range past its margin, else null; present only with lateral_check and an available range.

      "above""below"
  • spacing_ftnumberOptional

    Spacing used; left out with benches.

  • setback_ftnumberOptional

    Setback used, ft; only when the request sent one.

  • setback_end_ftnumberOptional

    End setback used, ft; only when sent.

  • min_lateral_ftnumberOptional

    Shortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out.

  • standoff_ftnumberOptional

    Standoff used, ft; only when sent.

  • standoff_wellsintegerOptional

    ≥ 0

    With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.

  • wells_per_padintegerOptional

    Wells per pad; only when sent.

  • wells_per_sectionnumberOptional

    With benches: their wells_per_section added up, the unit's total.

Show all 16 fields
  • lateral_checkobjectOptional

    With lateral_check: true: the range the wells were marked against, or why there is none. Show the mark beside any lateral or volume you quote for a marked well. The model is the model set's first served stream's (oil, else gas, else water), so model_num and reason read that model where they say oil.

    ShowHide 2 variants

    One of

    • The range object

      The range.

      • availablebooleanRequired

        Always true

        The range was found.

      • model_numstringRequired

        The served oil model whose training range was used.

      • featurestringRequired

        Always "novi_lateral_length"

        The model input checked.

      • low_ftnumberRequired

        Its training 1st percentile, ft, as GET /models gives it.

      • high_ftnumberRequired

        Its training 99th percentile, ft, as GET /models gives it.

      • margin_ftnumberRequired

        5% of high_ft minus low_ft: a well is marked only when its lateral is more than this below low_ft or above high_ft.

      • outsideintegerRequired

        ≥ 0

        Wells marked above or below.

    • No range object

      No range.

      • availablebooleanRequired

        Always false

        No range, so no well carries lateral_outside.

      • reasonstringRequired

        Why: no oil model, no training statistics for it, or no novi_lateral_length range in them.

  • padsintegerOptional

    ≥ 0

    With wells_per_pad: the pads.

  • benchesarray of objectsOptional

    With benches: each bench as filled.

    ShowHide 5 child fields in each item
    • spacing_ftnumberRequired

      Spacing used, ft.

    • wells_per_sectionnumberRequired

      5,280 ft / spacing_ft, or as sent.

    • offset_ftnumberRequired

      Offset used, ft.

    • formationstring or nullRequired

      The bench's formation, or null when none was sent.

    • countintegerRequired

      ≥ 0

      Wells in the bench.

  • formationstringOptional

    The request's formation, as GET /formations names it; only when sent.

Errors

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean