Fill many areas with wells
Lays wells of one lateral length over many areas in one call, laying areas that touch as one piece of land.
Fill many areas with wells
/areas/fillLays wells of one lateral length over many areas in one call, laying areas that touch as one piece of land. Nothing is stored: send the wells to POST /plans, each with a formation, to forecast them.
Areas
Send areas, lateral_length_ft, and spacing_ft or benches. azimuth_deg, setback_ft, setback_end_ft, wells_per_pad and formation work as in POST /layouts/fill.
Pieces of land
The areas not skipped are grouped part by part, and each group is laid on one grid. Two parts join when their edges run opposite ways within 1 ft of each other along an unbroken 100 ft, however each side's corners fall, or when they overlap. A shared corner, or points touching here and there, don't join. A MultiPolygon's parts may fall in different groups.
- Two parts overlap when an edge of one crosses an edge of the other, their edges run the same way along such a stretch, or a corner of one lies inside the other (when every corner lies on the other's edges, an edge's midpoint).
- In a group, a well runs across the lines between areas but never through a hole or outside the group, and land two areas cover is laid once.
setback_ftandsetback_end_fthold from the group's outer edges and holes only, not from edges its parts share. An edge inside an overlap isn't shared, so it still holds them.
Length
Along each line, an unbroken stretch of L ft, less its setbacks, holds k = floor(L / lateral_length_ft) wells of lateral_length_ft, toe to heel and centred, and none when k is 0. When the land left, L less k lengths, is at least min_lateral_ft, it takes k + 1 wells of L / (k + 1) instead. An L within a millionth of a foot of a whole number of lengths takes that many full wells.
- With 2-mile laterals and no setbacks, three one-mile sections take one 2-mile well, centred; two 5,200 ft sections one of 10,400 ft; four, two of 10,400 ft.
- With one-mile laterals and the default
min_lateral_ft, a one-mile section less 330 ft end setbacks still takes one well, of 4,620 ft. - A well that measures over
lateral_length_ftis shortened about its middle. - Lengths and setbacks are laid on a flat grid about the group's first corner, so far from it a well can measure a little short and pass a little closer to an edge: about 30 miles from it at about 32° N, a 5,280 ft well measured 24 ft short and a 330 ft setback 328.95 ft.
Azimuth
azimuth_deg sets every group's. Without it, each group runs along its largest part's longest outer edge or square to it, whichever way the group's outer corners span more feet; within 1 ft, along the edge. groups[].azimuth_deg gives each.
Order
Groups come in the order of their first part (areas in request order, then parts). Wells come group by group, then bench by bench, then line by line across the azimuth, heel to toe; pads number on across groups. Side gaps aren't evened out. The same request always answers the same bytes.
Skipped areas
Each is listed once in skipped, in request order, and counted in areas.skipped:
outside_dataset: its box misses GET /datasetbbox, as POST /areas'in_dataset: falsesays.degenerate: a ring POST /layouts/fill'sareawould refuse: under 3 corners, a corner that isn't [lng, lat], no area, or a hole that isn't inside its outline.too_small: its group lays no well, or no well runs through it.over_limit: its group would pass the well limit or the fill work, or its holes need more checking than the request has left to show they lie inside their outlines.
Limits
- At most 5,000 areas, 200,000 vertices in all, and
max_wellswells: the lesser of GET /datasetlimits.plan_wellsand 10,000. - At most 35,000,000 of fill work. Per bench, each line a group lays costs its ring edges plus its setback edges (twice with
setback_end_ft), plus 16 for each of those whose setback reaches the line; each part a laid well runs through costs 25. - Groups are laid in order with what is left, and a group past a limit is skipped whole while later groups still run. One whose lines times edges pass the work left counts no work; one that passes either limit while it is laid counts the work it did.
Errors
A body over 10 MB is a 413. Other errors are 400 with details.field:
- a missing or out-of-range number;
spacing_ftwithbenches, or neither;areasempty, over 5,000 entries, or over 200,000 vertices in all (details.maxanddetails.count);- an
areathat isn't a Polygon or MultiPolygon; - a repeated
id("areas[i].id repeats areas[j].id"); - areas too complex to group within one request's work (
details.max_work).
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 areas, the lateral length and the layout.
Send exactly one of: spacing_ft or benches.
areasarray of objectsRequired1 to 5000 items
The areas: at most 200,000 vertices in all.
ShowHide 2 child fields in each item
areaobjectRequiredThe area as a GeoJSON Polygon or MultiPolygon in WGS 84 with only type and coordinates: an area's geometry from POST /areas, or your own. A ring POST /layouts/fill's area would refuse skips the area as degenerate.
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.
idinteger or nullOptional≥ 0, ≤ 2147483647
Echoed in the answer; each once. Absent or null, the entry's index.
lateral_length_ftnumberRequired≥ 1000, ≤ 30000
The length each well aims for, ft (5,280 is a mile). Required.
min_lateral_ftnumber or nullOptional≥ 1000, ≤ 30000
The shortest well, ft, at most lateral_length_ft: a stretch takes as many wells of lateral_length_ft as fit, centred, or one more, all equal, when the land they leave is at least this long. Absent or null, 85% of lateral_length_ft to the foot, at least 1,000.
azimuth_degnumber or nullOptional≥ -360, ≤ 360
Every group's direction, degrees clockwise from north (wells drilled toward it). Absent or null, each group's long axis.
spacing_ftnumberOptional≥ 100, ≤ 10000
Distance between wells, ft.
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. Default the request's formation.
setback_ftnumber or nullOptional≥ 0, ≤ 2640
Feet the wells keep from each group's outer edges and holes, not from the lines between its areas, as POST /layouts/fill keeps them from an area's.
setback_end_ftnumber or nullOptional≥ 0, ≤ 2640
Feet each well's heel and toe keep from each group's outer edges and holes, as POST /layouts/fill keeps them from an area's.
wells_per_padinteger or nullOptional≥ 1, ≤ 50
Groups each group's wells into pads of this many, as POST /layouts/fill does; pads number on across groups, so each is unique in the answer.
formationstring or nullOptionalThe wells' formation (case-insensitive; GET /formations lists them), which each well then carries.
Responses
200 OK
The wells, group by group, and what was skipped.
countintegerRequired≥ 0
Wells.
lateral_length_ftnumberRequiredLength used, ft.
min_lateral_ftnumberRequiredShortest well used, ft: as sent, or the default.
azimuth_degnumber or nullRequiredThe request's azimuth_deg, or null when each group ran along its own (groups[].azimuth_deg).
joinobjectRequiredThe distances that join parts into one piece of land.
ShowHide 2 child fields
within_ftnumberRequiredEdges and stretches this close count as touching, ft.
min_shared_ftnumberRequiredThe least shared stretch that joins two parts, ft.
max_wellsintegerRequired≥ 1
The most wells the answer holds: the lesser of GET /dataset limits.plan_wells and 10,000.
areasobjectRequiredWhat became of the areas: sent is used plus the skipped counts.
ShowHide 3 child fields
sentintegerRequired≥ 1
Areas sent.
usedintegerRequired≥ 0
Areas some well runs through.
skippedobjectRequiredSkipped areas by reason.
ShowHide 4 child fields
outside_datasetintegerRequired≥ 0
Areas skipped as outside_dataset.
degenerateintegerRequired≥ 0
Areas skipped as degenerate.
too_smallintegerRequired≥ 0
Areas skipped as too_small.
over_limitintegerRequired≥ 0
Areas skipped as over_limit.
groupsarray of objectsRequiredThe groups that laid wells, in order; wells[].group indexes it.
ShowHide 4 child fields in each item
areasarray of integersRequiredItems ≥ 0
The group's areas' ids, in request order; a MultiPolygon whose parts fall in several groups is in each.
azimuth_degnumberRequiredThe group's azimuth, degrees: the request's azimuth_deg as sent, else measured on the group's flat grid to 0.001. Sent back as azimuth_deg, it lays the same wells.
firstintegerRequired≥ 0
Its first well's index in wells.
countintegerRequired≥ 1
Its wells.
skippedarray of objectsRequiredEach skipped area once, in request order.
ShowHide 3 child fields in each item
idintegerRequired≥ 0
The area's id.
reasonstringRequiredoutside_dataset: its box misses the dataset's; degenerate: a ring a fill refuses; too_small: no well runs through it; over_limit: its group would pass the well limit or the fill work, or its holes need more checking than one request has left.
"outside_dataset""degenerate""too_small""over_limit"detailstringOptionaldegenerate: the fault; over_limit: the limit.
wellsarray of objectsRequiredWells, group by group, 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.
groupintegerRequired≥ 0
Its group's index in groups.
areasarray of integersRequiredItems ≥ 0
The areas it runs through, heel to toe.
formationstringOptionalIts bench's formation, else the request's; only when one is known.
benchintegerOptional≥ 0
With benches: its bench's index.
padintegerOptional≥ 0
With wells_per_pad: its pad, from 0, unique across groups.
spacing_ftnumberOptionalSpacing used; left out with benches.
setback_ftnumberOptionalSetback used, ft; only when sent.
Show all 18 fields
setback_end_ftnumberOptionalEnd setback used, ft; only when sent.
wells_per_padintegerOptionalWells per pad; only when sent.
padsintegerOptional≥ 0
With wells_per_pad: the pads, across groups.
wells_per_sectionnumberOptionalWith benches: their wells_per_section added up.
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