/shorttermforecasthistory

This endpoint returns monthly gas production backcasts for well APIs.

Row Limit

Currently limited to one million rows per request. This endpoint will throw an error when you exceed one millions rows for a single request. To avoid this error simply apply additional filters to your request.

Backcasts are historical production forecasts. A backcast in this context may be described as:

• A historical production forecast meant to replicate a forecast model on a specified historical date.

• A forecast that only uses data that was available on or before the specified date. For example, if a backcast is from November 11, 2021, it will only use data which was available up until November 11, 2021.

Backcasts give an accurate representation of how our forecast performed on that day.

Note

• This endpoint returns six months’ data in total (two prior months, the specified month, and three subsequent months) for each API.

• Backcast data are not available prior to 2021-1-15. For a date with no forecast data available, the closest forecast_run_date is returned.

• Forecasts are updated every 3 days.

• Incomplete state data is accounted for. For example, if state data is incomplete for a month prior to the start_date, we fill in the missing data before each forecasting.

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/shorttermforecasthistory

Usage

Python

short_term_forecast_history(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.