Skip to content
Developers
Get an API token

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

GET/plans/{id}/pdp-wells

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.

Send a Novi API token as a bearer token on every request. Authentication
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 near finds 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 before til_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_date places it.
  • The section line runs at azimuth_deg, else the scope wells' mean heel-to-toe direction to 0.1°, through center, else their mean midpoint, as POST /gun-barrels takes and gives line.
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: cross beside azimuth_deg, center, along or reach.
  • 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

Query parameters

  • wellsstringOptional

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

  • limitintegerOptional

    Default 50≥ 1, ≤ 50

    The most wells to return, nearest first: 1 to 50, POST /wells/production's limit. matched still 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 takes line.azimuth_deg (-360 to 360, brought into [0, 360); any number, as 164.96 or 1e-7). Send a pad's azimuth, with its center, when wells is a pad. Absent: the scope wells' mean heel-to-toe direction to 0.1°.

  • centerstringOptional

    The section line's center, lng,lat in WGS 84 degrees, as POST /gun-barrels takes line.center: with along=section, the heel-to-toe range and each lateral's ends are measured along the line from it. Send a pad's center, with its azimuth_deg, when wells is a pad. It moves no candidate: the radius is measured from the wells' mean midpoint. Absent: that mean, to 1e-7°.

  • alongstringOptional

    section: keep only wells whose lateral overlaps the scope wells' heel-to-toe range along the section line, as the gun barrel draws its section; scope then names that range in along_range_ft. Absent: no such cut, and no along fields.

    "section"
  • reachstringOptional

    laterals: candidates are the wells with any part of their lateral within margin_mi of any scope well's lateral, not those with a midpoint in the circle; nearest lateral first, distance_ft the gap to it, and scope.reach echoes it. Absent: the circle.

    "laterals"
  • crossstringOptional

    A 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_deg of square to A-B, producing by til_date, as the web's Section A-B picks them. cross sets the section line and the candidates, so azimuth_deg, center, along or reach beside it is a 400. Absent: the scope wells' circle.

  • includestringOptional

    left_out: adds left_out, how many wells the TIL date and limit leave out. Any other value is a 400 with details.field include. Absent: no left_out.

    "left_out"
  • 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

The scope and the PDP wells.

  • scopeobjectRequired

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

      Items ≥ 0

      The plan wells measured from, ascending: wells as sent, else every well. POST /pdp-wells: every sent well's position in wells, 0 to n-1.

    • center[number, number]Required

      A 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_datestringRequired

      Format date

      The earliest TIL date of the scope wells: kept wells first produced on or before it.

    • margin_minumberRequired

      Always 0.5

      The margin added to the radius, mi; with reach=laterals, also how far from any scope well's lateral a kept lateral may lie.

    • parallel_degnumberRequired

      Always 15

      How far a kept lateral may turn from the line, either way along it, degrees.

    • crossarray of [number, number]sOptional

      2 items

      With cross: A and B, as sent.

    • reachstringOptional

      With reach=laterals: laterals.

      "laterals"
    • alongstringOptional

      With along=section: section.

      "section"
    • along_range_ftarray of integersOptional

      2 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 objectsRequired

    up to 50 items

    The nearest limit of them, nearest first, ties by wellbore key.

    ShowHide 7 child fields in each item
    • wellbore_keystringRequired

      Wellbore key, as GET /wells lists it.

    • well_namestring or nullRequired

      Well name.

    • operatorstring or nullRequired

      Operator.

    • formationstring or nullRequired

      Landing formation.

    • first_prodstringRequired

      Format date

      First production, YYYY-MM-DD: on or before scope.til_date.

    • lateral_length_ftnumber or nullRequired

      Lateral 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 near measures 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_outobjectOptional

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

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

Errors

StatusWhen
404

No such well, grid, plan or route.

409

The request conflicts with the state of the plan or resource it names, and message says how: for example a plan still running or failed, a stale If-Match, an Idempotency-Key reused with another body, or a server without a state store.

Shared errors400401403500503What they mean