/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], aggregation_type=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"]
aggregation_type	string	Specifies the type of aggregation applied to data in the request.	"average", "count", "sum"
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…

countydateoperatorregionstate_codesub_regionfirst_production_monthmodeledproduction_monthstate_reported

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

Aggregated type…

averagecountsum

payload = {
   'aggregation_type': 'average',
   'aggregate_by': 'county',
}

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		2024-11-08	0	0	False	2.774193548387097	86	INVESTMENT EQUIPMENT LLC	31	west	co	True	Colorado wo SJ
500105242	Adams	2023-02-01		2024-11-08	0	0	False	3.0714285714285716	86	INVESTMENT EQUIPMENT LLC	32	west	co	True	Colorado wo SJ
500105242	Adams	2023-03-01		2024-11-08	0	0	False	2.903225806451613	90	INVESTMENT EQUIPMENT LLC	33	west	co	True	Colorado wo SJ
500105242	Adams	2023-05-01		2024-11-08	0	0	False	2.3548387096774195	73	INVESTMENT EQUIPMENT LLC	34	west	co	True	Colorado wo SJ
500105242	Adams	2023-06-01		2024-11-08	0	0	False	2.7	81	INVESTMENT EQUIPMENT LLC	35	west	co	True	Colorado wo SJ

Note

If you don’t define an aggregation_type in the query, aggregation data will come as a sum. If you define aggregation_type to be average, it returns the average values instead of the sum. If aggregation_type is count, there won’t be oil/gas daily/monthly columns in the response; instead, you will have a new “num_records” column.

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.