List the PDP wells near a plan or pad
Existing wells near a done plan's wells, parallel to them and producing by the plan's first TIL date, nearest first, by the gun barrel's PDP selection rule, so every client compares a plan with the same wells.
List the PDP wells near a plan or pad
/plans/{id}/pdp-wellsExisting wells near a done plan's wells, parallel to them and producing by the plan's first TIL date, nearest first, by the gun barrel's PDP selection rule, so every client compares a plan with the same wells.
The rule
scope echoes it, with each figure's rounding (PdpScope). A well's lateral runs from its heel, else its surface hole, to its bottom hole.
- Scope: the plan wells in
wells(a pad's, say), else every plan well. - Circle: centered on the mean of the scope wells' lateral midpoints, its radius the farthest of them plus 0.5 mi (
margin_mi), at most GET /wells' 100 mi. - Candidates: the wells GET /wells
nearfinds in that circle, each at its lateral midpoint, that have a lateral. - Kept: a candidate whose lateral runs within 15° (
parallel_deg) of the section line, either way along it, and that first produced on or beforetil_date, the scope wells' earliest TIL date; a well without a first production date isn't kept. - A scope well with no TIL date at any layer comes online on the plan's creation day (UTC), as
by_dateplaces it. - The section line runs at
azimuth_deg, else the scope wells' mean heel-to-toe direction to 0.1°, throughcenter, else their mean midpoint, as POST /gun-barrels takes and givesline.
Results
matched counts every well that passed (after the section cut, with along); wells holds the nearest limit (ties by wellbore key), whose keys go straight to POST /wells/production, with lateral_length_ft to normalise production per 1,000 ft. No drawing limit applies: not the gun barrel's 1,000 nearest candidates, its well cap or its TVD filter. include=left_out adds left_out: under til_date the wells that passed every other cut but first produced after til_date or never, and under limit those past limit.
A pad
Send the pad's azimuth and center as azimuth_deg and center: the gun barrel draws a pad on its own line, so a pad laid at an azimuth off the 0.1° grid can keep a different set on the wells' line.
Section cut
along=section keeps only the wells whose lateral overlaps the scope wells' heel-to-toe range on the section line (along_range_ft), each end placed as POST /gun-barrels' heel_along_ft and toe_along_ft.
Lateral reach
With reach=laterals, the candidates are the wells with any part of their lateral (at GET /wells' 5-decimal ends) within margin_mi of any scope well's lateral, so a long-lateral pad finds the offsets beside its ends that the circle misses. The parallel, TIL, along and limit rules stay, and the list runs nearest by distance_ft (ties by wellbore key). Scope wells whose laterals span wider or taller than the circle's diameter plus two 50,000 ft laterals and margin_mi (as across the antimeridian) are a 400 naming wells.
A line across
With cross, a line A-B drawn across the laterals, a candidate is kept, as the web's Section A-B keeps it, when its lateral (at GET /wells' 5-decimal ends) crosses A-B within half A-B of its midpoint, with its ends on either side (one may lie on it), runs within parallel_deg of the section line, square to A-B, and first produced on or before til_date. The candidates are the wells GET /wells near the mean of A and B finds within half A-B plus 25,000 ft, a superset of the web's search, and distance_ft is from that mean. til_date is still the scope wells': send the plan wells the line crosses as wells to date it by them.
Caching
The answer carries an ETag; send it as If-None-Match for a 304.
Errors
- 400 naming
wells: a scope whose radius would pass 100 mi; send fewer, closer wells. - 400 naming the other parameter:
crossbesideazimuth_deg,center,alongorreach. - 400 naming
cross: A and B under 1 ft apart, or a radius past 100 mi. - 409: a running or failed plan, as GET /plans/{id}/wells/{index} answers.
Parameters
Path parameters
idstringRequiredFormat
uuidPlan id from POST /plans.
Query parameters
wellsstringOptionalPlan well indexes to measure from, comma-separated, as a pad's wells: up to 500, in any order, a repeat counted once. Absent: every well of the plan. An index past the plan's last is a 400 naming wells.
limitintegerOptionalDefault
50≥ 1, ≤ 50The most wells to return, nearest first: 1 to 50, POST /wells/production's limit.
matchedstill counts them all.azimuth_degnumberOptional≥ -360, ≤ 360
The section line's azimuth, to measure parallel against and, with
along=section, to cut along: degrees clockwise from north, as POST /gun-barrels takesline.azimuth_deg(-360 to 360, brought into [0, 360); any number, as 164.96 or 1e-7). Send a pad's azimuth, with itscenter, whenwellsis a pad. Absent: the scope wells' mean heel-to-toe direction to 0.1°.centerstringOptionalThe section line's center,
lng,latin WGS 84 degrees, as POST /gun-barrels takesline.center: withalong=section, the heel-to-toe range and each lateral's ends are measured along the line from it. Send a pad's center, with itsazimuth_deg, whenwellsis a pad. It moves no candidate: the radius is measured from the wells' mean midpoint. Absent: that mean, to 1e-7°.alongstringOptionalsection: keep only wells whose lateral overlaps the scope wells' heel-to-toe range along the section line, as the gun barrel draws its section;scopethen names that range inalong_range_ft. Absent: no such cut, and noalongfields."section"reachstringOptionallaterals: candidates are the wells with any part of their lateral withinmargin_miof any scope well's lateral, not those with a midpoint in the circle; nearest lateral first,distance_ftthe gap to it, andscope.reachechoes it. Absent: the circle."laterals"crossstringOptionalA line A-B drawn across the laterals:
lngA,latA,lngB,latB, four numbers in WGS 84 degrees, A then B, as-101.91,31.9,-101.89,31.9.Keeps the wells whose laterals cross A-B and run within
parallel_degof square to A-B, producing bytil_date, as the web's Section A-B picks them.crosssets the section line and the candidates, soazimuth_deg,center,alongorreachbeside it is a 400. Absent: the scope wells' circle.includestringOptionalleft_out: addsleft_out, how many wells the TIL date andlimitleave out. Any other value is a 400 with details.field include. Absent: noleft_out."left_out"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.
Responses
200 OK
The scope and the PDP wells.
scopeobjectRequiredWhat 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 integersRequiredItems ≥ 0
The plan wells measured from, ascending:
wellsas sent, else every well. POST /pdp-wells: every sent well's position inwells, 0 to n-1.center[number, number]RequiredA 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_datestringRequiredFormat
dateThe earliest TIL date of the scope wells: kept wells first produced on or before it.
margin_minumberRequiredAlways
0.5The margin added to the radius, mi; with reach=laterals, also how far from any scope well's lateral a kept lateral may lie.
parallel_degnumberRequiredAlways
15How far a kept lateral may turn from the line, either way along it, degrees.
crossarray of [number, number]sOptional2 items
With cross: A and B, as sent.
reachstringOptionalWith reach=laterals: laterals.
"laterals"alongstringOptionalWith along=section: section.
"section"along_range_ftarray of integersOptional2 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 objectsRequiredup to 50 items
The nearest
limitof them, nearest first, ties by wellbore key.ShowHide 7 child fields in each item
wellbore_keystringRequiredWellbore key, as GET /wells lists it.
well_namestring or nullRequiredWell name.
operatorstring or nullRequiredOperator.
formationstring or nullRequiredLanding formation.
first_prodstringRequiredFormat
dateFirst production, YYYY-MM-DD: on or before scope.til_date.
lateral_length_ftnumber or nullRequiredLateral 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
nearmeasures 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_outobjectOptionalWith 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.
304 Unchanged since the ETag in If-None-Match.Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | The request conflicts with the state of the plan or resource it names, and |
Shared errors400401403500503What they mean