Skip to content
Developers
Get an API token

Count wells by value

Counts of wells by value, for pickers and range sliders, without downloading wells.

Count wells by value

GET/wells/facets

Counts 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.

Send a Novi API token as a bearer token on every request. Authentication
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

  • facetsstringRequired

    The fields to count, comma-separated, each once, at most 6: text operator, formation, county, subbasin, state, basin; numeric 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.

  • containsstringOptional

    up 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.

  • limitintegerOptional

    Default 10≥ 1, ≤ 100

    Values per text facet; others sums the rest.

  • binsintegerOptional

    Default 20≥ 1, ≤ 100

    With 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.

  • formationstringOptional

    Only these formations: one name or a comma-separated list, case-insensitive, as WOLFCAMP A,WOLFCAMP B.

  • bboxstringOptional

    Only wells whose lateral midpoint is inside west,south,east,north (degrees), as -102.05,31.9,-101.85,32.05.

  • qstringOptional

    up to 100 characters

    Only wells whose name or wellbore key contains this text, ignoring case: woodard trust matches WOODARD TRUST 32-44 2WB. Leading and trailing spaces are ignored; up to 100 characters (400 past it).

  • operatorstringOptional

    up to 100 characters

    Only wells whose operator contains this text, ignoring case; up to 100 characters (400 past it).

  • operatorsarray of stringsOptional

    up 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, with details.max and details.count). operator stays a substring match. GET /wells/facets lists the names.

  • countystringOptional

    Only wells in these counties: exact names, case-insensitive, comma-separated, at most 50.

  • nearstringOptional

    Only wells within radius_mi of this point: lng,lat in WGS 84 degrees, longitude first as in bbox, 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_minumberOptional

    Default 5> 0, ≤ 100

    With 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_minnumberOptional

    Only wells whose lateral_length is at least this, in ft.

  • lateral_length_maxnumberOptional

    Only wells whose lateral_length is at most this, in ft.

  • tvd_td_minnumberOptional

    Only wells whose tvd_td is at least this, in ft.

  • tvd_td_maxnumberOptional

    Only wells whose tvd_td is at most this, in ft.

  • cum_oil_12_minnumberOptional

    Only wells whose cum_oil_12 is at least this, in bbl.

  • cum_oil_12_maxnumberOptional

    Only wells whose cum_oil_12 is at most this, in bbl.

  • cum_gas_12_minnumberOptional

    Only wells whose cum_gas_12 is at least this, in mcf.

  • cum_gas_12_maxnumberOptional

    Only wells whose cum_gas_12 is at most this, in mcf.

  • cum_boe_12_minnumberOptional

    Only wells whose cum_boe_12 is at least this, in BOE.

  • cum_boe_12_maxnumberOptional

    Only wells whose cum_boe_12 is at most this, in BOE.

  • cum_oil_life_minnumberOptional

    Only wells whose cum_oil_life is at least this, in bbl.

  • cum_oil_life_maxnumberOptional

    Only wells whose cum_oil_life is at most this, in bbl.

  • cum_gas_life_minnumberOptional

    Only wells whose cum_gas_life is at least this, in mcf.

  • cum_gas_life_maxnumberOptional

    Only wells whose cum_gas_life is at most this, in mcf.

  • cum_boe_life_minnumberOptional

    Only wells whose cum_boe_life is at least this, in BOE.

  • cum_boe_life_maxnumberOptional

    Only wells whose cum_boe_life is at most this, in BOE.

  • total_proppant_minnumberOptional

    Only wells whose total_proppant is at least this, in lb.

  • total_proppant_maxnumberOptional

    Only wells whose total_proppant is at most this, in lb.

  • total_fluid_minnumberOptional

    Only wells whose total_fluid is at least this, in bbl.

  • total_fluid_maxnumberOptional

    Only wells whose total_fluid is at most this, in bbl.

  • stage_count_minnumberOptional

    Only wells whose stage_count is at least this, in stages.

  • stage_count_maxnumberOptional

    Only wells whose stage_count is at most this, in stages.

  • first_year_minnumberOptional

    Only wells whose first_year is at least this, in years.

  • first_year_maxnumberOptional

    Only wells whose first_year is at most this, in years.

  • fluid_bbl_per_ft_minnumberOptional

    Only wells whose fluid_bbl_per_ft is at least this, in bbl/ft.

  • fluid_bbl_per_ft_maxnumberOptional

    Only wells whose fluid_bbl_per_ft is at most this, in bbl/ft.

  • proppant_lb_per_ft_minnumberOptional

    Only wells whose proppant_lb_per_ft is at least this, in lb/ft.

  • proppant_lb_per_ft_maxnumberOptional

    Only wells whose proppant_lb_per_ft is at most this, in lb/ft.

  • cum_boe_12_per_1000_ft_minnumberOptional

    Only wells whose cum_boe_12_per_1000_ft is at least this, in BOE per 1,000 ft of lateral.

  • cum_boe_12_per_1000_ft_maxnumberOptional

    Only wells whose cum_boe_12_per_1000_ft is at most this, in BOE per 1,000 ft of lateral.

  • cum_oil_12_per_1000_ft_minnumberOptional

    Only wells whose cum_oil_12_per_1000_ft is at least this, in bbl per 1,000 ft of lateral.

  • cum_oil_12_per_1000_ft_maxnumberOptional

    Only wells whose cum_oil_12_per_1000_ft is at most this, in bbl per 1,000 ft of lateral.

  • cum_gas_12_per_1000_ft_minnumberOptional

    Only wells whose cum_gas_12_per_1000_ft is at least this, in mcf per 1,000 ft of lateral.

  • cum_gas_12_per_1000_ft_maxnumberOptional

    Only wells whose cum_gas_12_per_1000_ft is at most this, in mcf per 1,000 ft of lateral.

  • first_prod_minstringOptional

    Format date

    Only wells whose first_prod is on or after this day, YYYY-MM-DD.

  • first_prod_maxstringOptional

    Format date

    Only wells whose first_prod is on or before this day, YYYY-MM-DD.

  • last_prod_minstringOptional

    Format date

    Only wells whose last_prod is on or after this day, YYYY-MM-DD.

  • last_prod_maxstringOptional

    Format date

    Only wells whose last_prod is on or before this day, YYYY-MM-DD.

  • frac_date_minstringOptional

    Format date

    Only wells whose frac_date is on or after this day, YYYY-MM-DD.

  • frac_date_maxstringOptional

    Format date

    Only wells whose frac_date is on or before this day, YYYY-MM-DD.

  • til_date_minstringOptional

    Format date

    Only wells whose til_date is on or after this day, YYYY-MM-DD.

  • til_date_maxstringOptional

    Format date

    Only wells whose til_date is on or before this day, YYYY-MM-DD.

  • keysstringOptional

    Only these wells: wellbore keys, exact, comma-separated, such as SB329-01414,SB329-01415.

    A repeated keys adds its list, and a repeat counts once. At most 50 keys (400 naming keys past it, with details.max and details.count). An empty keys= 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_setstringOptional

    pattern ^[a-z0-9][a-z0-9-]{0,62}$

    The model set to answer from, an id from GET /model-sets. Absent: the set GET /model-sets names as default, the base dataset unless the server answers from a published set.

    • model_set=default reaches 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 once default is 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's plan.id, or a comparison's a.plan and b.plan, also under source.comparison) reaches it without model_set.
    • An explicit model_set wins; 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.

  • facetsobjectRequired

    Each 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.

      • typeanyRequired

        Always "text"

        A text field.

      • distinctintegerRequired

        ≥ 0

        Values matching contains, or every value without it.

      • missingintegerRequired

        ≥ 0

        Wells counted without a value.

      • valuesarray of objectsRequired

        Up 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
        • valuestringRequired

          The value, as stored.

        • wellsintegerRequired

          ≥ 1

          Wells with it.

      • othersobject or nullRequired

        The 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.

      • typeanyRequired

        Always "number"

        A numeric field.

      • unitstringRequired

        Unit 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 nullRequired

        Smallest value; null when none has one.

      • maxnumber or nullRequired

        Largest value; null when none has one.

      • quantilesobjectRequired

        Quantiles across wells, type 7, to 0.1; not P-level bands.

        ShowHide 3 child fields
        • q10number or nullRequired

          10th-percentile well, the low end.

        • q50number or nullRequired

          Median well.

        • q90number or nullRequired

          90th-percentile well, the high end.

      • histogramobjectRequired

        Bins 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 numbersRequired

          Bin 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 integersRequired

          Items ≥ 0

          Wells per bin; they add up to wells.

Conditional requests 304 Unchanged since the ETag in If-None-Match.

Errors

Shared errors400401403500503What they mean