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
/layouts/fillParallel 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.
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_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.
Request body
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]sOptional3 to 500 items
Area corners, in order (closing point optional). Edges that cross are a 400.
azimuth_degnumberOptionalDefault
0≥ -360, ≤ 360Direction 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 nullOptionalDefault
0≥ 0, ≤ 2640Feet 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).
areaobjectOptionalInstead 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.
typeanyRequiredAlways
"Polygon"One part.
coordinatesarray of arraysRequiredat least 1 itemsItems at least 3 items
The outer ring, then its holes.
A multipolygon object
A multipolygon.
typeanyRequiredAlways
"MultiPolygon"Several parts, taken together.
coordinatesarray of arraysRequiredat 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
wellswithpads. POST /plans keeps pad keys: withlayout, the 1-based pad number as text; withlayouts, 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 echopads) as a plan scenario'swellsin POST /economics.lateral_checkbooleanOptionalDefault
falseMark 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 objectsOptional1 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_ftorwells_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 nullOptionalDefault
0≥ -10000, ≤ 10000Shifts 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 nullOptionalThe 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 nullOptionalThe 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.
countintegerRequiredWells.
azimuth_degnumberRequiredAzimuth used.
lateral_length_ftnumber or nullRequiredLength used, or null for edge to edge.
wellsarray of objectsRequiredWells, 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]RequiredA point as [longitude, latitude] in WGS 84 degrees.
bhl[number, number]RequiredA point as [longitude, latitude] in WGS 84 degrees.
lateral_length_ftintegerRequiredLateral length, ft.
formationstringOptionalIts 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 nullOptionalAbove or below the training lateral range past its margin, else null; present only with lateral_check and an available range.
"above""below"
spacing_ftnumberOptionalSpacing used; left out with benches.
setback_ftnumberOptionalSetback used, ft; only when the request sent one.
setback_end_ftnumberOptionalEnd setback used, ft; only when sent.
min_lateral_ftnumberOptionalShortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out.
standoff_ftnumberOptionalStandoff 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_padintegerOptionalWells per pad; only when sent.
wells_per_sectionnumberOptionalWith benches: their wells_per_section added up, the unit's total.
Show all 16 fields
lateral_checkobjectOptionalWith 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_numandreasonread that model where they say oil.ShowHide 2 variants
One of
The range object
The range.
availablebooleanRequiredAlways
trueThe range was found.
model_numstringRequiredThe served oil model whose training range was used.
featurestringRequiredAlways
"novi_lateral_length"The model input checked.
low_ftnumberRequiredIts training 1st percentile, ft, as GET /models gives it.
high_ftnumberRequiredIts training 99th percentile, ft, as GET /models gives it.
margin_ftnumberRequired5% 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.
availablebooleanRequiredAlways
falseNo range, so no well carries lateral_outside.
reasonstringRequiredWhy: 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 objectsOptionalWith benches: each bench as filled.
ShowHide 5 child fields in each item
spacing_ftnumberRequiredSpacing used, ft.
wells_per_sectionnumberRequired5,280 ft / spacing_ft, or as sent.
offset_ftnumberRequiredOffset used, ft.
formationstring or nullRequiredThe bench's formation, or null when none was sent.
countintegerRequired≥ 0
Wells in the bench.
formationstringOptionalThe request's formation, as GET /formations names it; only when sent.
Errors
| Status | When |
|---|---|
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean