/shorttermforecastdeclines#

This endpoint returns short-term forecasts of oil and gas production declines for individual well APIs. It extends the functionality of the short-term forecast by projecting the “well-level” forecast up to ten years into the future from the current date.

Warning

A throttling mechanism with a rate limit of 30 requests per minute has been implemented for this endpoint. This is temporary and may be adjusted in the future.

Endpoint#

POST

https://hyperion.api.synmax.com/v3/shorttermforecastdeclines

Usage#

Python#

short_term_forecast_declines(aggregate_by=[None], api=[None], county=[None], end_date=None, first_production_month_end=None, first_production_month_start=None, modeled=None, operator=[None], production_month=[None], region=[None], start_date=None, state_code=[None], sub_region=[None], state_reported=None)#

Returns a prediction of gas production decline (gas_monthly) for the selected month (start_date).

Object returned is a pandas DataFrame.

⮞ Setup the client.

from synmax.hyperion import HyperionApiClient, ApiPayload
access_token = 'your access token goes here'
client = HyperionApiClient(access_token=access_token)

For a more detailed guide on setting up the Hyperion client, please see the Quickstart page.

⮞ Use parameters to narrow down your request.

payload = ApiPayload(start_date='2021-05-01', end_date='2022-06-25', sub_region=['S LA', 'West - TX'])

Tip

Narrow down your request to receive a faster response. Using no parameters will fetch the entire dataset which may take a very long time.

⮞ Call the function.

result_df = client.short_term_forecast_declines(payload)

⮞ Print the results or save them for later.

# Print the entire response as a string.
print(result_df.to_string())

# Create a CSV file from the output.
result_df.to_csv('output.csv')

# Print the number of items per column.
print(result_df.count())

For more information on outputting to different formats, please see the pandas DataFrame documentation.

Parameters#

Query#

Parameter

Type

Description

Example

aggregate_by

string array

Aggregate data by a list of parameters.

["date", "region"]

api

integer array

Filter for specific well API numbers that are currently online.

[4200347857, 4200347858]

county

string array

Limit search by a list of counties.

["Beauregard", "Coleman", "Colorado"]

end_date

string

Limit search to an end date. Date formatting - [“YYYY-MM-DD”]

"2022-07-15"

first_production_month_end

string

End of the date range for selecting wells that began producing in the specified month (Format: ‘YYYY-MM-01’).

“2023-03-01”

first_production_month_start

string

Start of the date range for selecting wells that began producing in the specified month (Format: ‘YYYY-MM-01’).

“2023-11-01”

modeled

boolean

Indicates whether the production numbers are based on our forecast model (True) or from pipescrapes (False).

True, False

operator

string array

Limit search to a list of well operators.

["ALLEN BROTHERS", "BP"]

production_month

integer array

Filter for specific production months of selected wells. Represents one or more months since the well started producing. Starts from 1 and increases by 1 for each subsequent month of production.

[1,2,3]

region

string array

Limit search by a list of regions (clusters of multiple major producing basins).

["GULF", "WEST"]

start_date

string

Limit search to a start date. Date formatting - [“YYYY-MM-DD”]

"2022-06-01"

state_code

string array

Limit search by a list of state codes.

["LA", "CO"]

sub_region

string array

Limit search by a list of subregions (clusters of several counties forming a major producing basin).

["S LA", "West - TX"]

state_reported

boolean

Indicates if the well has production measurement(s) from state data sources (True) or if the entire well production was forecasted (False).

True, False

Aggregation#

Aggregation provides an overview of overall productions levels for a particular operator or across a given region during a given timeframe.

Data is always implicitly aggregated by date. This means all other column data are grouped by date.

Supported parameters: county, date, first_production_month, modeled, operator, production_month, region, state_code, sub_region, state_reported

Response#

Parameter

Type

Description

Example

api

integer

An API is a unique, permanent, numeric identifier assigned to each well drilled.

1701121257

county_name

string

Name of the county where the well is located.

“ADAMS”

date

string

Forecasted month (unsynced). Date formatting - [“YYYY-MM-DD”]

“2022-11-01”

first_production_month

string

Start of date range for selecting wells that started producing in the specific month. Format: Format: “YYYY-MM-01”

“2009-10-01”

forecast_run_date

string

Date of nearest forecast (unsynced). Date formatting - [“YYYY-MM-DD”]

“2022-06-01”

gas_daily

float

Average rate of gas production declined expressed per day (in BCF/day).

23.842

gas_monthly

float

Amount of gas production declined over one month (in MCF, or 1 thousand cubic feet).

0.0

modeled

boolean

Indicates whether the production numbers are from the forecast model (True) or from pipescrapes (False).

True, False

oil_daily

float

The amount of oil production declined in a single day (in BBLS, or barrels).

112.9570761

oil_monthly

float

The amount of oil production declined over one month (in BBLS, or barrels).

86.0

operator_name

string

Operator of the well.

“PIE OPERATING, LLC”

production_month

integer

Specific production months of specific wells. Starts from 1 and increases by 1 for each subsequent month.

4

region

string

Aggregation of multiple major producing basins.

“GULF”

state_ab

string

Abbreviation of the state.

“LA”

state_reported

boolean

Indicates if the well has production measurement(s) from state data sources (True) or if the entire well production was forecasted (False).

True, False

sub_region

string

Aggregation of several counties, typically representing a major producing basin.

“S LA”

page_size

integer

Number of items returned in a single page

1000

start

integer

Starting index for the data returned in this request. An index of 0 means that the current data begins from the first item in the complete dataset.

0

total_count

integer

Total number of items in the dataset. This is important for calculating how many pages of data exist.

38258749

Responses#

Normal Output#

api

county_name

date

first_production_month

forecast_run_date

gas_daily

gas_monthly

modeled

oil_daily

oil_monthly

operator_name

production_month

region

state_ab

state_reported

sub_region

500105242

Adams

2023-01-01

2009-10-01

2024-11-04

0

0

False

2.774193548387097

86

INVESTMENT EQUIPMENT LLC

31

west

co

True

Colorado wo SJ

500105242

Adams

2023-02-01

2009-10-01

2024-11-04

0

0

False

3.0714285714285716

86

INVESTMENT EQUIPMENT LLC

32

west

co

True

Colorado wo SJ

500105242

Adams

2023-03-01

2009-10-01

2024-11-04

0

0

False

2.903225806451613

90

INVESTMENT EQUIPMENT LLC

33

west

co

True

Colorado wo SJ

500105242

Adams

2023-05-01

2009-10-01

2024-11-04

0

0

False

2.3548387096774195

73

INVESTMENT EQUIPMENT LLC

34

west

co

True

Colorado wo SJ

500105242

Adams

2023-06-01

2009-10-01

2024-11-04

0

0

False

2.7

81

INVESTMENT EQUIPMENT LLC

35

west

co

True

Colorado wo SJ

500105242

Adams

2023-07-01

2009-10-01

2024-11-04

0

0

False

2.870967741935484

89

INVESTMENT EQUIPMENT LLC

36

west

co

True

Colorado wo SJ

Note

Output data will return as “null” when input data is invalid or does not exist.

Aggregated Output#

Aggregated by…

payload = {
   'aggregate_by': 'county'
}

county_name

date

gas_daily

gas_monthly

oil_daily

oil_monthly

WILLIAMSON

2023-01-01

0.0

0.0

21.580645161290324

669.0

WICHITA

2023-01-01

551.8064516129032

17106.0

3203.2258064516127

99300.0

CARTER

2023-01-01

159062.87096774194

4930949.0

9288.354838709678

287939.0

BEAVER

2023-01-01

305907.33600387094

9483127.416119998

1476.032258064516

45757.0

OCHILTREE

2023-01-01

63438.51612903226

1966594.0

7855.774193548387

243529.0

ALLEN

2023-01-01

1620.967741935484

50250.0

392.48387096774195

12167.0

ORANGE

2023-01-01

6894.967741935484

213744.0

1195.0

37045.0

CLEARFIELD

2023-01-01

23307.707096774197

722538.92

null

null

Tip

To better explore using the aggregation functionality interactively, consider using our Excel Add-in. By familiarizing yourself with the available options, you can more efficiently query and process the data for your specific needs. To learn how to use the SynMax Excel Add-in, please refer to our Excel Add-in Documentation.