/shorttermforecasthistory

This endpoint returns historic versions of the /shorttermforecast on a well level.

Note

• Forecasts are updated every 3 days.

• Historical versions at the well level are available on this endpoint for the past two quarters.

• All historic versions going back until 2021-01-15 are available in sub-region aggregated format at /stfaggregatedhistory.

• Incomplete state data is accounted for. That is, if state data is incomplete for a month prior to the start_date, we fill in the missing data before each forecast run.

• A historical production forecast is meant to replicate a forecast model on a specified historical date using the data that was available on or before that date.

Endpoint

POST	https://hyperion.api.synmax.com/v3/shorttermforecasthistory

Usage

Python

client.short_term_forecast_history(payload=ApiPayload(aggregate_by=[None], county=[None], end_date=None, forecast_run_date=None, start_date=None))

Returns monthly gas production backcasts for the selected date (start_date) organized by well API number.

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_history(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
api	string array	Well API numbers passed as strings.	["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"
forecast_run_date	string	Date of nearest forecast. Date formatting - [“YYYY-MM-DD”]	"2022-06-01"
start_date	string	Limit search to a start date. Date formatting - [“YYYY-MM-DD”]	"2022-06-01"

Note

forecast_run_date is a required field. If no forecast_run_date is specified, the latest version of the STF History data is pulled.

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
date	string	Date selected for forecast (unsynced). Date formatting - [“YYYY-MM-DD”]	“2022-11-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 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	operator_name	region	state_ab	sub_region
1701129920	BEAUREGARD	2022-05-01	2023-01-10	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-05-01	2023-02-26	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-06-01	2022-12-14	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-06-01	2022-12-16	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-06-01	2022-12-19	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-06-01	2022-12-22	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-06-01	2022-12-25	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-06-01	2022-12-29	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-06-01	2022-12-31	0.0	0.0	ALLEN BROTHERS	gulf	LA	S LA
1701129920	BEAUREGARD	2022-06-01	2023-01-03	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
PANOLA	2022-11-01	2022-12-19	2093778.1971174804	62813345.91352441
CASS	2022-11-01	2023-03-08	13898.50369577208	416955.1108731624
HARRISON	2022-11-01	2023-02-11	1051148.5643621958	31534456.930865876
UPSHUR	2022-11-01	2022-10-08	86481.1786163545	2594435.358490635
SMITH	2022-11-01	2023-04-06	60584.03802174857	1817521.1406524573
WEBSTER	2022-11-01	2023-04-21	52330.362426362546	1569910.8727908763
WOOD	2022-11-01	2023-01-28	124189.12321234349	3725673.6963703046
BOWIE	2022-11-01	2022-10-02	38.76068645402476	1162.8205936207428
SMITH	2022-11-01	2023-04-18	56062.22579401442	1681866.7738204326
NACOGDOCHES	2022-11-01	2023-04-21	322186.92204913456	9665607.661474036

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.