/stfaggregatedhistory#

This endpoint returns historic versions of the ShortTermForecasts on a sub-region aggregated level. The sub-region aggregated data is more tractable for higher level analysis in comparison to the more detailed and much larger well-level ShortTermForecastHistory dataset.

Note

  • This endpoint offers sub-region aggregated versions of all historical SynMax ShortTermForecasts going back in three days increments until 2021-01-15

  • Each version of the ShortTermForecast can be uniquely identified by the forecast_run_date.

  • Incomplete state data is accounted for in our forecasts. 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/stfaggregatedhistory

Usage#

Python#

short_term_forecast_aggregated_history(forecast_run_date=None, sub_region=[None], start_date=None, end_date=None)#

Returns historic versions of the ShortTermForecasts on a sub-region aggregated level.

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_aggregated_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

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"

sub_region

string array

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

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

This API does not use predefined filter aggregation values. Instead, you can specify filters using the parameters below:

{
  "end_date": "2024-11-05",
  "forecast_run_date": "2024-11-05",
  "pagination": {
    "page_size": 0,
    "start": 0,
    "total_count": 0
  },
  "start_date": "2024-11-05",
  "sub_region": [
    "Central - TX"
  ]
}

Response#

Parameter

Type

Description

Example

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

oil_daily

float

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

112.9570761

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

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#

date

forecast_run_date

gas_daily

oil_daily

sub_region

2023-01-01

2024-08-25

2.872823725

0.1201064193548387

Central - TX

2023-01-01

2024-08-27

2.872823725

0.1201064193548387

Central - TX

2023-01-01

2024-08-30

5.74564745

0.1201064193548387

Central - TX

2023-01-01

2024-09-02

2.872823725

0.1201064193548387

Central - TX

2023-01-01

2024-09-05

2.872823725

0.1201064193548387

Central - TX

2023-01-01

2024-09-09

2.872823725

0.1201064193548387

Central - TX

2023-01-01

2024-09-09

2.872823725

0.1201064193548387

Central - TX

Note

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

Filtering Output#

Filtering by…

{
   "end_date": "2024-11-05"
}

date

forecast_run_date

gas_daily

oil_daily

sub_region

2024-06-01

2024-07-04

5.60554929

0.0245461

Haynesville - TX

2024-06-01

2024-07-07

5.605290339

0.024545366666666665

Haynesville - TX

2024-06-01

2024-07-10

5.609807544

0.024551733333333332

Haynesville - TX

2024-06-01

2024-07-13

5.607349803

0.024738625100072586

Haynesville - TX

2024-06-01

2024-07-16

5.607349803

0.024738625100072607

Haynesville - TX

2024-06-01

2024-07-19

5.607349803

0.024738625100072586

Haynesville - TX

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.