Skip to content
Developers
Get an API token

List wells

Existing wells for a map: every matching well as parallel arrays (format=columns, the default), or a page of GeoJSON Points at each lateral's midpoint (format=geojson).

List wells

GET/wells

Existing wells for a map: every matching well as parallel arrays (format=columns, the default), or a page of GeoJSON Points at each lateral's midpoint (format=geojson).

Send a Novi API token as a bearer token on every request. Authentication
Formats

format=columns includes names, operators and first year: about 0.6 MB gzipped for the whole basin. Both formats page with limit and cursor. fields keeps only the fields you name, and adds header fields and derived ones: per-ft completions, and 12-month BOE, oil and gas per 1,000 ft of lateral.

Filters

Filters combine. To find wells by name, key or operator without downloading the basin, send q or operator with format=geojson and a small limit. near keeps the wells within radius_mi, nearest first, each with its distance_mi. county and operators match exact names, keys wellbore keys; sort and order order the wells. GET /wells/facets counts wells by value, for pickers and range sliders.

Ranges

<field>_min and <field>_max are inclusive and compare the value as a response shows it, rounded; a well without the value never matches. Numbers are digits with an optional decimal, as 9000.5; dates are YYYY-MM-DD. A _min above its _max is a 400; a range on a field without one is ignored, as any unknown parameter is.

Applied

applied echoes how the server read sort, order, county, operators, the ranges and columns paging; absent when none is sent.

Parameters

Query parameters

  • formatstringOptional

    Default "columns"

    Response layout.

    "columns""geojson"
  • 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).

  • nearstringOptional

    Only wells within radius_mi of this point, nearest first, each with its distance_mi: lng,lat in WGS 84 degrees, longitude first as in bbox.

    Distance is great-circle miles to each lateral's midpoint; distance_mi rounds it to 0.01 (a column with format=columns, a property with format=geojson). Ties at the exact distance go by wellbore key, so cursor pages are stable. 400 unless it is two numbers within -180 to 180 and -90 to 90. Without it, wells come in wellbore key order.

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

  • limitintegerOptional

    Default 100≥ 1, ≤ 10000

    Page size: with format=geojson, 1 to 1,000 wells (default 100); with format=columns, 1 to 10,000 (100 when only cursor is sent), and the response adds next_cursor. Without limit or cursor, format=columns returns every matching well.

  • cursorstringOptional

    Page to read: next_cursor from the previous page, in either format.

  • fieldsstringOptional

    Only these fields, comma-separated; absent or empty, every field. wellbore_key is always kept, and the response keeps its own key order.

    Allowed: the columns or properties listed below, and distance_mi with near.

    Columns, with format=columns: wellbore_key, well_name, operator, formation, mid_lon, mid_lat, shl_lon, shl_lat, heel_lon, heel_lat, bhl_lon, bhl_lat, cum_boe_12, first_year. Properties, with format=geojson: wellbore_key, well_name, operator, formation, first_prod, lateral_length, tvd_td, cum_boe_12, shl_lon, shl_lat, heel_lon, heel_lat, bhl_lon, bhl_lat. distance_mi without near is a 400.

    Either format also takes basin, subbasin, state, county, lateral_length, tvd_td, lat, lon, first_prod, last_prod, cum_oil_12, cum_gas_12, cum_boe_12, cum_oil_life, cum_gas_life, cum_boe_life, total_proppant, total_fluid, stage_count, frac_date, til_date, first_year, 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.

    These are GET /wells/{key}'s header fields, first_year, per-ft completions, and 12-month BOE, oil (bbl) and gas (mcf) per 1,000 ft of lateral, after the default fields in that order.

    Coordinates are rounded to 5 decimals, volumes to whole units, per-ft values to 0.1, and dates are YYYY-MM-DD. lat and lon are the header's point; the map uses mid_lon and mid_lat.

    For example well_name,formation,cum_boe_12. count and format, or a feature's type, id and geometry and the page's next_cursor, are always there.

    Names are top-level only (no dots), case-sensitive and never empty; one not allowed here is a 400 with the allowed names in details.allowed.

  • sortstringOptional

    Order the wells by this field: any name fields takes except the coordinates, or distance_mi with near; an unknown name is a 400 with details.allowed.

    Wells without a value come last either way; ties go by wellbore key, so cursor pages are stable. With near, sort replaces the distance order and the radius still filters.

    "wellbore_key""well_name""operator""formation""cum_boe_12""first_year""first_prod""lateral_length""tvd_td""basin""subbasin""state""county""last_prod""cum_oil_12""cum_gas_12""cum_oil_life""cum_gas_life""cum_boe_life""total_proppant"
    10 more values"total_fluid""stage_count""frac_date""til_date""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""distance_mi"
  • orderstringOptional

    Default "desc"

    With sort (ignored without it): desc, largest or latest first, or asc.

    "asc""desc"
Show all 58 parameters
  • countystringOptional

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

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

  • 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 known list, such as a forecast's analogs, in one call.

    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, so read the response for which wells came back.

  • 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

Matching wells.

  • formatstringRequired

    Always "columns"

    Layout.

  • countintegerRequired

    Wells.

  • columnsobjectRequired

    Parallel arrays, one entry per well. With fields, only the asked properties are present.

    ShowHide 41 child fields
    • wellbore_keyarray of stringsRequired

      Wellbore keys.

    • well_namearray of stringsOptional

      Well names.

    • operatorarray of stringsOptional

      Current operators.

    • formationarray of stringsOptional

      Formations.

    • mid_lonarray of numbersOptional

      Lateral midpoint longitude.

    • mid_latarray of numbersOptional

      Lateral midpoint latitude.

    • shl_lonarray of numbersOptional

      Surface hole longitude.

    • shl_latarray of numbersOptional

      Surface hole latitude.

    • heel_lonarray of numbersOptional

      Heel longitude (null when not reported).

    • heel_latarray of numbersOptional

      Heel latitude.

    • bhl_lonarray of numbersOptional

      Bottom hole longitude.

    • bhl_latarray of numbersOptional

      Bottom hole latitude.

    Show all 41 fields
    • cum_boe_12array of numbersOptional

      First 12 months of production, BOE (gas at 6 mcf per bbl).

    • first_yeararray of integersOptional

      Year of first production.

    • distance_miarray of numbersOptional

      With near only: great-circle miles from near to the lateral midpoint, rounded to 0.01; the wells come nearest first.

    • area_distance_ftarray of integersOptional

      Items ≥ 0

      POST /wells/search only: 0 inside the area or on its edge, else feet from it, rounded and at least 1.

    • basinarray of stringsOptional

      Basin. Only when named in fields.

    • subbasinarray of stringsOptional

      Sub-basin. Only when named in fields.

    • statearray of stringsOptional

      State. Only when named in fields.

    • countyarray of stringsOptional

      County. Only when named in fields.

    • lateral_lengtharray of numbersOptional

      Lateral length, ft. Only when named in fields.

    • tvd_tdarray of numbersOptional

      TVD, ft. Only when named in fields.

    • latarray of numbersOptional

      The header's latitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lat. Only when named in fields.

    • lonarray of numbersOptional

      The header's longitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lon. Only when named in fields.

    • first_prodarray of stringsOptional

      First production, YYYY-MM-DD. Only when named in fields.

    • last_prodarray of stringsOptional

      Last production, YYYY-MM-DD. Only when named in fields.

    • cum_oil_12array of numbersOptional

      First 12 months oil, whole bbl. Only when named in fields.

    • cum_gas_12array of numbersOptional

      First 12 months gas, whole mcf. Only when named in fields.

    • cum_oil_lifearray of numbersOptional

      Cumulative oil, whole bbl. Only when named in fields.

    • cum_gas_lifearray of numbersOptional

      Cumulative gas, whole mcf. Only when named in fields.

    • cum_boe_lifearray of numbersOptional

      Cumulative BOE, whole. Only when named in fields.

    • total_proppantarray of integersOptional

      Proppant, lb. Only when named in fields.

    • total_fluidarray of integersOptional

      Fluid, bbl. Only when named in fields.

    • stage_countarray of integersOptional

      Frac stages. Only when named in fields.

    • frac_datearray of stringsOptional

      Frac date, YYYY-MM-DD. Only when named in fields.

    • til_datearray of stringsOptional

      Turn-in-line date, YYYY-MM-DD. Only when named in fields.

    • fluid_bbl_per_ftarray of numbersOptional

      Completion fluid per lateral ft, bbl/ft to 0.1: the header's novi_calc_fluid_per_length, the per-well value GET /completions/defaults and POST /units/summary take medians of. Only when named in fields.

    • proppant_lb_per_ftarray of numbersOptional

      Proppant per lateral ft, lb/ft to 0.1: the header's novi_calc_proppant_per_length, as fluid_bbl_per_ft. Only when named in fields.

    • cum_boe_12_per_1000_ftarray of numbersOptional

      First 12 months of BOE per 1,000 ft of lateral (cum_boe_12 / lateral_length × 1,000, as POST /units/summary computes it), whole BOE. Only when named in fields.

    • cum_oil_12_per_1000_ftarray of numbersOptional

      First 12 months of oil per 1,000 ft of lateral (cum_oil_12 / lateral_length × 1,000), whole bbl; null without a 12-month oil volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields.

    • cum_gas_12_per_1000_ftarray of numbersOptional

      First 12 months of gas per 1,000 ft of lateral (cum_gas_12 / lateral_length × 1,000), whole mcf; null without a 12-month gas volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields.

  • next_cursorstring or nullOptional

    With limit or cursor: cursor for the next page, null on the last; count is still every matching well.

  • appliedobjectOptional

    How the server read sort, order, county, operators, the _min and _max ranges and, when format=columns is paged, limit and cursor, as {"lateral_length_min": 9000, "sort": "cum_boe_12", "order": "desc"}. Absent when none of them was sent.

    ShowHide 2 variants in each value

    Any of

    • number, string or boolean number, string or boolean or null

    • array of strings array of strings

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

Errors

Shared errors400401403500503What they mean