Count wells by value
Counts of wells by value, for pickers and range sliders, without downloading wells.
Count wells by value
/wells/facetsCounts of wells by value, for pickers and range sliders, without downloading wells. Name up to 6 fields in facets, which lists the text and numeric ones.
Text fields
Values with well counts, most wells first; limit caps them and others sums the rest. contains keeps the values containing some text, word starts first: type-ahead for operators.
Numeric fields
Unit, min, max, and q10, q50 and q90 (type 7, to 0.1: quantiles of wells, not P-level bands), with a histogram of bins equal-width bars. Edges are rounded as shown, covering min and max; a bar counts the wells within its shown edges, the last closed. On the whole-number fields (first_year, stage_count) a bar is a whole number of values wide: with span = max − min + 1 values, each is ceil(span / bins) wide, at most bins bars, one per value when the range fits, with edges halfway between values (2018.5), so a _min and _max from any two edges select exactly those bars. A non-finite value counts as missing.
Filters
Every GET /wells filter narrows the count; the top-level wells is the count with all of them. A facet ignores its own exact filter (operators, formation, county, or its _min and _max), so a picker keeps showing the values it could add.
Errors
400 with details.field: no facets, an unknown one (with details.allowed), more than 6, contains without a text facet, bins without a numeric one, or a GET /wells filter error.
Caching
Dataset-derived: cached, with an ETag.
Parameters
Query parameters
facetsstringRequiredThe fields to count, comma-separated, each once, at most 6: text
operator,formation,county,subbasin,state,basin; numericfirst_year,lateral_length,tvd_td,cum_boe_12,cum_oil_12,cum_gas_12,cum_boe_life,stage_count,fluid_bbl_per_ft,proppant_lb_per_ft,cum_boe_12_per_1000_ft,cum_oil_12_per_1000_ft,cum_gas_12_per_1000_ft.containsstringOptionalup to 100 characters
With a text facet (400 without one): keep the values containing this text, ignoring case, those with a word starting with it first, then the rest, each most wells first, then by name; at most 100 characters.
limitintegerOptionalDefault
10≥ 1, ≤ 100Values per text facet;
otherssums the rest.binsintegerOptionalDefault
20≥ 1, ≤ 100With a numeric facet (400 without one): histogram bins; for a whole-number field (
first_year,stage_count) the most bars, since each is a whole number of values wide.formationstringOptionalOnly these formations: one name or a comma-separated list, case-insensitive, as
WOLFCAMP A,WOLFCAMP B.bboxstringOptionalOnly wells whose lateral midpoint is inside
west,south,east,north(degrees), as-102.05,31.9,-101.85,32.05.qstringOptionalup to 100 characters
Only wells whose name or wellbore key contains this text, ignoring case:
woodard trustmatches WOODARD TRUST 32-44 2WB. Leading and trailing spaces are ignored; up to 100 characters (400 past it).operatorstringOptionalup to 100 characters
Only wells whose operator contains this text, ignoring case; up to 100 characters (400 past it).
operatorsarray of stringsOptionalup to 50 itemsItems up to 100 characters
Only wells of these operators: exact names, case-insensitive. Repeat the parameter for each name (
operators=A&operators=B), since operator names can contain commas; at most 50, each at most 100 characters (400 past either, withdetails.maxanddetails.count).operatorstays a substring match. GET /wells/facets lists the names.countystringOptionalOnly wells in these counties: exact names, case-insensitive, comma-separated, at most 50.
nearstringOptionalOnly wells within
radius_miof this point:lng,latin WGS 84 degrees, longitude first as inbbox, measured in great-circle miles to each lateral's midpoint. Combines with every other filter; 400 when it isn't two numbers within -180 to 180 and -90 to 90. Facets count the wells it keeps; no well comes back.radius_minumberOptionalDefault
5> 0, ≤ 100With
near(400 without it): how far from it to look, in miles, a decimal greater than 0 and at most 100 written as digits (2 or 2.5); default 5.
Show all 56 parameters
lateral_length_minnumberOptionalOnly wells whose
lateral_lengthis at least this, in ft.lateral_length_maxnumberOptionalOnly wells whose
lateral_lengthis at most this, in ft.tvd_td_minnumberOptionalOnly wells whose
tvd_tdis at least this, in ft.tvd_td_maxnumberOptionalOnly wells whose
tvd_tdis at most this, in ft.cum_oil_12_minnumberOptionalOnly wells whose
cum_oil_12is at least this, in bbl.cum_oil_12_maxnumberOptionalOnly wells whose
cum_oil_12is at most this, in bbl.cum_gas_12_minnumberOptionalOnly wells whose
cum_gas_12is at least this, in mcf.cum_gas_12_maxnumberOptionalOnly wells whose
cum_gas_12is at most this, in mcf.cum_boe_12_minnumberOptionalOnly wells whose
cum_boe_12is at least this, in BOE.cum_boe_12_maxnumberOptionalOnly wells whose
cum_boe_12is at most this, in BOE.cum_oil_life_minnumberOptionalOnly wells whose
cum_oil_lifeis at least this, in bbl.cum_oil_life_maxnumberOptionalOnly wells whose
cum_oil_lifeis at most this, in bbl.cum_gas_life_minnumberOptionalOnly wells whose
cum_gas_lifeis at least this, in mcf.cum_gas_life_maxnumberOptionalOnly wells whose
cum_gas_lifeis at most this, in mcf.cum_boe_life_minnumberOptionalOnly wells whose
cum_boe_lifeis at least this, in BOE.cum_boe_life_maxnumberOptionalOnly wells whose
cum_boe_lifeis at most this, in BOE.total_proppant_minnumberOptionalOnly wells whose
total_proppantis at least this, in lb.total_proppant_maxnumberOptionalOnly wells whose
total_proppantis at most this, in lb.total_fluid_minnumberOptionalOnly wells whose
total_fluidis at least this, in bbl.total_fluid_maxnumberOptionalOnly wells whose
total_fluidis at most this, in bbl.stage_count_minnumberOptionalOnly wells whose
stage_countis at least this, in stages.stage_count_maxnumberOptionalOnly wells whose
stage_countis at most this, in stages.first_year_minnumberOptionalOnly wells whose
first_yearis at least this, in years.first_year_maxnumberOptionalOnly wells whose
first_yearis at most this, in years.fluid_bbl_per_ft_minnumberOptionalOnly wells whose
fluid_bbl_per_ftis at least this, in bbl/ft.fluid_bbl_per_ft_maxnumberOptionalOnly wells whose
fluid_bbl_per_ftis at most this, in bbl/ft.proppant_lb_per_ft_minnumberOptionalOnly wells whose
proppant_lb_per_ftis at least this, in lb/ft.proppant_lb_per_ft_maxnumberOptionalOnly wells whose
proppant_lb_per_ftis at most this, in lb/ft.cum_boe_12_per_1000_ft_minnumberOptionalOnly wells whose
cum_boe_12_per_1000_ftis at least this, in BOE per 1,000 ft of lateral.cum_boe_12_per_1000_ft_maxnumberOptionalOnly wells whose
cum_boe_12_per_1000_ftis at most this, in BOE per 1,000 ft of lateral.cum_oil_12_per_1000_ft_minnumberOptionalOnly wells whose
cum_oil_12_per_1000_ftis at least this, in bbl per 1,000 ft of lateral.cum_oil_12_per_1000_ft_maxnumberOptionalOnly wells whose
cum_oil_12_per_1000_ftis at most this, in bbl per 1,000 ft of lateral.cum_gas_12_per_1000_ft_minnumberOptionalOnly wells whose
cum_gas_12_per_1000_ftis at least this, in mcf per 1,000 ft of lateral.cum_gas_12_per_1000_ft_maxnumberOptionalOnly wells whose
cum_gas_12_per_1000_ftis at most this, in mcf per 1,000 ft of lateral.first_prod_minstringOptionalFormat
dateOnly wells whose
first_prodis on or after this day, YYYY-MM-DD.first_prod_maxstringOptionalFormat
dateOnly wells whose
first_prodis on or before this day, YYYY-MM-DD.last_prod_minstringOptionalFormat
dateOnly wells whose
last_prodis on or after this day, YYYY-MM-DD.last_prod_maxstringOptionalFormat
dateOnly wells whose
last_prodis on or before this day, YYYY-MM-DD.frac_date_minstringOptionalFormat
dateOnly wells whose
frac_dateis on or after this day, YYYY-MM-DD.frac_date_maxstringOptionalFormat
dateOnly wells whose
frac_dateis on or before this day, YYYY-MM-DD.til_date_minstringOptionalFormat
dateOnly wells whose
til_dateis on or after this day, YYYY-MM-DD.til_date_maxstringOptionalFormat
dateOnly wells whose
til_dateis on or before this day, YYYY-MM-DD.keysstringOptionalOnly these wells: wellbore keys, exact, comma-separated, such as
SB329-01414,SB329-01415.A repeated
keysadds its list, and a repeat counts once. At most 50 keys (400 namingkeyspast it, withdetails.maxanddetails.count). An emptykeys=means every well; a value with no key, such as,, is a 400. A key the dataset lacks matches nothing. Facets count the wells that match, not which keys did.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
Counts by facet, in the order asked.
wellsintegerRequired≥ 0
Wells matching every filter, each facet's own included: not disjunctive.
facetsobjectRequiredEach asked facet by its name, in the order asked; counted without its own exact filter.
Names:
operator,formation,county,subbasin,state,basin,first_year,lateral_length,tvd_td,cum_boe_12,cum_oil_12,cum_gas_12,cum_boe_life,stage_count,fluid_bbl_per_ft,proppant_lb_per_ft,cum_boe_12_per_1000_ft,cum_oil_12_per_1000_ft,cum_gas_12_per_1000_ft.ShowHide 2 variants in each value
One of
TextFacet object
A text facet: values and their well counts.
typeanyRequiredAlways
"text"A text field.
distinctintegerRequired≥ 0
Values matching contains, or every value without it.
missingintegerRequired≥ 0
Wells counted without a value.
valuesarray of objectsRequiredUp to limit values: with contains, those with a word starting with it first; then most wells first, then by name.
ShowHide 2 child fields in each item
valuestringRequiredThe value, as stored.
wellsintegerRequired≥ 1
Wells with it.
othersobject or nullRequiredThe values past limit, summed; null when none is left out.
ShowHide 2 child fields
valuesintegerRequired≥ 1
Values left out.
wellsintegerRequired≥ 1
Their wells.
NumberFacet object
A numeric facet: its spread across wells.
typeanyRequiredAlways
"number"A numeric field.
unitstringRequiredUnit of the values: ft, bbl, mcf, BOE, bbl/ft, lb/ft, BOE per 1,000 ft, stages or year.
wellsintegerRequired≥ 0
Wells counted with a value.
missingintegerRequired≥ 0
Wells counted without one.
minnumber or nullRequiredSmallest value; null when none has one.
maxnumber or nullRequiredLargest value; null when none has one.
quantilesobjectRequiredQuantiles across wells, type 7, to 0.1; not P-level bands.
ShowHide 3 child fields
q10number or nullRequired10th-percentile well, the low end.
q50number or nullRequiredMedian well.
q90number or nullRequired90th-percentile well, the high end.
histogramobjectRequiredBins of equal width from min to max, counted against the rounded edges shown (the outer two rounded outward), the last closed; a whole-number field's bins are a whole number of values wide and may be fewer than bins.
ShowHide 2 child fields
edgesarray of numbersRequiredBin edges, one more than counts, to 0.1 or finer where 0.1 would repeat an edge, strictly ascending except a single value's two equal edges; for a whole-number field, half steps between whole values; empty when no well has a value.
countsarray of integersRequiredItems ≥ 0
Wells per bin; they add up to wells.
304 Unchanged since the ETag in If-None-Match.Errors
Shared errors400401403500503What they mean