/shorttermforecast

This endpoint returns short-term, monthly gas production forecasts for well APIs.

Short-term forecasting achieves two primary functions:

• Removing gaps that exist in state data by predicting unreported gas production.

• Predicting future gas production up to three months from a given 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/shorttermforecast

Usage

Python

short_term_forecast(aggregate_by=[None], county=[None], end_date=None, operator=[None], region=[None], start_date=None, state_code=[None], sub_region=[None])

Returns a prediction of gas production (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(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"]
county	string array	Limit search by a list of counties.	["Beauregard", "Coleman", "Colorado"]
operator	string array	Limit search to a list of well operators.	["ALLEN BROTHERS", "BP"]
end_date	string	Limit search to an end date. Date formatting - [“YYYY-MM-DD”]	"2022-07-15"
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"]

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, operator, region, state_code, sub_region

Response

Parameter	Type	Description	Example
api	integer	An API is a unique, permanent, numeric identifier assigned to each well drilled.	1701121257
county	string	County in the state where the well is located.	“BEAUREGARD”
date	string	Forecasted month (unsynced). Date formatting - [“YYYY-MM-DD”]	“2022-11-01”
forecast_run_date	string	Date of forecast generation (unsynced). Date formatting - [“YYYY-MM-DD”]	“2022-11-01”
gas_daily	float	Average rate of gas production expressed per day (in BCF/day).	23.842
gas_monthly	integer	Amount of gas produced over one month (in MCF, or 1 thousand cubic feet).	980
oil_daily	float	The amount of oil produced in a single day (in BBLS, or barrels).	112.9570761
oil_monthly	integer	The amount of oil produced over one month (in BBLS, or barrels).	5650
operator_name	string	Operator of the well.	“PIE OPERATING, LLC”
region	string	Aggregation of multiple major producing basins.	“GULF”
state_ab	string	Abbreviation of the state.	“LA”
sub_region	string	Aggregation of several counties, typically representing a major producing basin.	“S LA”

Note

Unsynced data in the date column provide a date at the start of the month. However, the actual reported date is for the end of the month.

For example, if the reported date is “2022-1-10”, this means the data pertains to the month of January and was actually reported on “2022-01-31”.

This means that you should ideally interpret the reported date as representing the whole month and not just the specific date at the start of the month.

---

Responses

Normal Output

api	county	date	forecast_run_date	gas_daily	gas_monthly	oil_daily	oil_monthly	operator_name	region	state_ab	sub_region
1701129920	BEAUREGARD	2022-07-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-08-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-09-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-10-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-11-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-12-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2023-01-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2023-02-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2023-03-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2023-04-01	2023-06-04	0.0	0.0	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA

Note

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

Aggregated Output

Aggregated by…

countydateoperatorregionstate_codesub_region

payload = {
   'aggregate_by': 'county'
}

county	date	forecast_run_date	gas_daily	gas_monthly	oil_daily	oil_monthly
ANDREWS	2022-11-01	2023-06-08	115825.78436442738	3474773.5309328213	258773.0	7763217.0
LAMB	2022-11-01	2023-06-08	841.6508333333333	25249.524999999998	797.0	23921.0
KENT	2022-11-01	2023-06-08	3537.775755050505	106133.27265151514	15111.0	453352.0
CROSBY	2022-11-01	2023-06-08	1433.798099508703	43013.94298526109	0.0	18.0
CHEROKEE	2022-11-01	2023-06-08	48162.56358937687	1444876.9076813061	0.0	0.0
MCCULLOCH	2022-11-01	2023-06-08	77.42716666666666	2322.815	0.0	0.0
PECOS	2022-11-01	2023-06-08	78692.4548316397	2360773.644949191	368171.0	11045133.0
DAWSON	2022-11-01	2023-06-08	8120.412036552593	243612.3610965778	4775.0	143278.0
CULBERSON	2022-11-01	2023-06-08	71958.85077952017	2158765.5233856053	1185937.0	35578132.0
ANDERSON	2022-11-01	2023-06-08	4448.323221717171	133449.6966515151	0.0	0.0

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.