Summarize a unit's wells, grids and completions
What a unit holds, in one request: its area, the existing wells inside and around it by formation, operator and year, each formation's grid ranges, and completion medians.
Summarize a unit's wells, grids and completions
/units/summaryWhat a unit holds, in one request: its area, the existing wells inside and around it by formation, operator and year, each formation's grid ranges, and completion medians. Use it before filling a unit.
Scope
Send area or polygon, not both. A well is in the unit when its lateral midpoint (the point GET /wells' bbox filters on) is inside the area, on its edge or within buffer_ft of it. With match: lateral, any part of its lateral counts, which picks up wells that cross the unit's edge.
- Holes are left out and a MultiPolygon's parts count together.
buffer_ftis measured to the nearest edge, a hole's included, on a flat earth about the well. - Rings need at least 3 corners and some area, and at most 200,000 vertices in all, as many as POST /areas reads (400 with
details.maxanddetails.count).areaandpolygonsay which other rings are a 400. - A scope that needs more work than one request may take (about a second) is a 400 "too complex" with
details.max_work, and the same scope always fares the same: simplify the outline, split it or send a smallerbuffer_ft. - Errors are 400 with
details.field.
The answer
A median leaves out wells without that value, and is null when none has it.
area: measured as POST /areas measures it, so the two agree.wells: those in scope,insidethe area and in thebuffer, by formation, by operator (the top 10 by wells, then an Other row) and by first-production year.formations: every formation, top to bottom, with its wells in scope and each subsurface grid's min, median and max over the cells (GET /subsurface/grids/{feature_name}'s lattice points) whose centres fall inside the area, not the buffer.- Over 2,500 cells in the area's bbox, the first inside each square of a 50 × 50 lattice over the bbox is used, and
sampledis true. gridsis null for a formation without grids or with no cell inside. For an area smaller than a cell, sample a well path with GET /subsurface/sample.
- Over 2,500 cells in the area's bbox, the first inside each square of a 50 × 50 lattice over the bbox is used, and
completions: by formation, the median fluid (bbl/ft, to 0.1) and proppant (lb/ft, to 1) of the in-scope wells with both, or empty. The per-well values are those GET /completions/defaults takes medians of, without its 180-day online window, so these cover the unit's wells of every vintage.
Only some formations
formation (a name, names separated by commas, or an array) keeps only those formations' wells, formations and completions.
Before you fill it
The wells inside are the unit's existing wells, but forecasts and plans space each new well against every existing well within the spacing radius (GET /dataset spacing.search_radius_ft), inside the unit or not: send buffer_ft to see those around it. List the wells with POST /wells/search (same scope). Fill the unit with POST /layouts/fill (the same area, every part filled and holes left out, or an area's fill.polygon; and long_axis_azimuth_deg), or as a layout in POST /plans.
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 scope, and optionally formations.
Send exactly one of: area or polygon.
areaobjectOptionalThe unit as a GeoJSON Polygon or MultiPolygon in WGS 84, with only type and coordinates: an area's geometry from POST /areas. Rings may wind either way and need not repeat their first point; holes are left out. Not with polygon. A hole that isn't inside its outline is a 400 on that ring. Holes are checked in order up to a fixed amount of checking per request; past it a hole is taken as sent.
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.
polygonarray of [number, number]sOptional3 to 200001 items
The unit as one ring of corners, in order (closing point optional): an area's fill.polygon, or what POST /layouts/fill takes. Not with area. Edges that cross are a 400, tested on rings of up to 500 corners.
buffer_ftnumberOptionalDefault
0≥ 0, ≤ 5280Also take wells within this many feet of the area (0 takes only those inside).
matchstringOptionalDefault
"midpoint"midpoint: a well is in by its lateral midpoint; lateral: also by any part of its lateral, heel (else surface hole) to bottom hole.
"midpoint""lateral"formationstring or arrayOptionalup to 50 itemsItems up to 100 characters
Only these formations' wells, formations and completions: a name, names separated by commas, or an array of names, case-insensitive.
Responses
200 OK
The unit.
areaobjectRequiredThe area, measured as POST /areas measures it.
ShowHide 4 child fields
acresnumberRequiredArea, acres, holes taken out.
long_axis_azimuth_degintegerRequired≥ -90, ≤ 90
The bearing of the largest part's longest edge, degrees from north, -90 to 90, as POST /areas reports it.
bboxarray of numbersRequired4 items
[west, south, east, north] of the outer rings.
in_datasetbooleanRequiredTrue when the bbox meets the dataset's (GET /dataset bbox).
wellsobjectRequiredThe wells in scope (inside and buffer together, unless counted apart).
ShowHide 5 child fields
insideintegerRequired≥ 0
Wells in scope inside the area.
bufferintegerRequired≥ 0
Wells in scope outside the area, within buffer_ft.
by_formationarray of objectsRequiredBy formation, top to bottom; wells without one last.
ShowHide 10 child fields in each item
formationstring or nullRequiredFormation, or null for wells without one.
wellsintegerRequired≥ 1
Wells in scope: inside and within buffer_ft.
insideintegerRequired≥ 0
Of them, those inside the area (not in the buffer).
median_lateral_ftinteger or nullRequiredMedian lateral length, ft.
median_tvd_ftinteger or nullRequiredMedian TVD, ft.
median_cum_boe_12integer or nullRequiredMedian first 12 months of production, BOE.
total_cum_boe_12integer or nullRequiredTheir first 12 months of production added up, BOE.
median_cum_boe_12_per_1000_ftinteger or nullRequiredMedian of each well's 12-month BOE per 1,000 ft of lateral, BOE.
first_prod_earlieststring or nullRequiredFormat
dateEarliest first production.
first_prod_lateststring or nullRequiredFormat
dateLatest first production.
by_operatorarray of objectsRequiredThe 10 operators with the most wells (ties by name), then Other.
ShowHide 3 child fields in each item
operatorstring or nullRequiredOperator, Other on the last row when there are more, or null for wells without one.
wellsintegerRequired≥ 1
Wells in scope.
othersintegerOptional≥ 1
On the Other row only: how many operators it sums.
by_first_yeararray of objectsRequiredBy year, oldest first; wells without one last.
ShowHide 2 child fields in each item
yearinteger or nullRequiredYear of first production, or null.
wellsintegerRequired≥ 1
Wells in scope.
formationsarray of objectsRequiredEvery formation, top to bottom (only the asked ones with formation).
ShowHide 6 child fields in each item
formationstringRequiredFormation.
labelstringRequiredDisplay name.
wellsintegerRequired≥ 0
Wells in scope landed in it: inside and within buffer_ft.
insideintegerRequired≥ 0
Of them, those inside the area (not in the buffer).
has_gridsbooleanRequiredTrue when it has subsurface grids.
gridsobject or nullRequiredBy rock property (novi_structuraldepth, novi_thickness_avg, ...): the grid over the cells inside the area, or null when it has none there. Null without grids or with no cell inside.
ShowHide 7 child fields in each value
feature_namestringRequiredThe grid, as GET /subsurface/grids/{feature_name} names it.
unitstring or nullRequiredft, fraction, or null when unknown.
cellsintegerRequired≥ 1
Grid cells inside the area with a value, after any sampling.
sampledbooleanRequiredTrue when a coarser lattice was used (more cells than the cap lie in the area's bbox).
minnumberRequiredSmallest value, 5 significant digits.
mediannumberRequiredMedian value.
maxnumberRequiredLargest value.
completionsarray of objectsRequiredBy formation, top to bottom; empty when no in-scope well has completions.
ShowHide 4 child fields in each item
formationstring or nullRequiredFormation, or null.
fluid_bbl_per_ftnumberRequiredMedian fluid, bbl/ft, to 0.1.
proppant_lb_per_ftnumberRequiredMedian proppant, lb/ft, to 1.
wellsintegerRequired≥ 1
In-scope wells with both.
warningsarray of stringsRequiredWhat to check: nothing inside, the area off the dataset, the grids unavailable.
Errors
| Status | When |
|---|---|
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean