/rigs#

This endpoint provides users with rig location specific to a wellpad and its operating dates.

Warning

A throttling mechanism with a rate limit of 300 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/rigs

Usage#

Python#

rigs(aggregate_by=[None], county=[None], end_date=None, operator=[None], region=[None], rig_class=None, start_date=None, state_code=[None], sub_region=[None])#

Returns rig locations by wellpad and 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.rigs(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"]`
end_date	string	Limit search to an end date. Date formatting - [“YYYY-MM-DD”]	`"2022-07-15"`
operator	string array	Limit search to a list of well operators.	`["ALLEN BROTHERS", "BP"]`
region	string array	Limit search by a list of regions (clusters of multiple major producing basins).	`["GULF", "WEST"]`
rig_class	string	Limit search to either oil or gas wells based on the GOR definition from the EIA.	`"gas"`
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
county	string	County in the state where the well is located.	“BEAUREGARD”
date	string	Date on which a rig is operating. Date formatting - [“YYYY-MM-DD”]	“2022-06-01”
lat	string	The latitude of the location, in decimal degrees; follows the WGS 84/EPSG:4326 coordinate system.	“32.2483475”
long	string	The longitude of the location, in decimal degrees; follows the WGS 84/EPSG:4326 coordinate system.	“-93.39548666666667”
operator_name	string	Operator of the well.	“PIE OPERATING, LLC”
region	string	Aggregation of multiple major producing basins.	“GULF”
rig_class	string	Classifies wells as either oil or gas wells based on the GOR definition from the EIA.	“gas”
sub_region	string	Aggregation of several counties, typically representing a major producing basin.	“S LA”
wellpad_id	string	Identifier of the wellpad.	“27248”

Note

Wellpads located in Canada are tracked and identified by a prefix ‘C’ in the wellpad id.

Responses#

Normal Output#

county	date	lat	long	operator_name	region	rig_class	state_ab	sub_region	wellpad_id
WELD	2022-09-05	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-06	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-07	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-08	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-09	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-10	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-11	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-12	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-13	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204
WELD	2022-09-14	40.3262406875	-104.413096875	EDGE ENERGY LLC	west	oil	CO	Colorado wo SJ	1204

Note

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

Aggregated Output#

Aggregated by…

payload = {
   'aggregate_by': 'county'
}

county	date	rigs_count
WELD	9/14/2020	2
RED RIVER	9/14/2020	1
UPTON	9/15/2020	5
WARD	9/15/2020	5
MIDLAND	9/15/2020	14
PANOLA	9/15/2020	1
WINKLER	9/15/2020	4
PECOS	9/15/2020	2
REEVES	9/15/2020	6

payload = {
   'aggregate_by': 'date'
}

date	rigs_count
2022-11-01	850
2022-11-02	849
2022-11-03	844
2022-11-04	853
2022-11-05	848
2022-11-06	852
2022-11-07	847
2022-11-08	848
2022-11-09	847
2022-11-10	858

payload = {
   'aggregate_by': 'operator'
}

date	operator_name	rigs_count
2022-11-01	DISCOVERY OIL AND GAS	1
2022-11-01	SHOR OPERATING LLC	1
2022-11-01	WARWICK-ARTEMIS LLC	1
2022-11-01	DIAMONDBACK ENERGY	18
2022-11-01	PRI OPERATING LLC	4
2022-11-01	PERMIAN RESOURCES	9
2022-11-01	RESONANCE EXPLORATION (NORTH DAKOTA) LLC	1
2022-11-01	ELEVATION RESOURCES LLC	1
2022-11-01	CHAPARRAL ENERGY LLC	1
2022-11-01	BLACKBEARD OPERATING LLC	3

payload = {
   'aggregate_by': 'region'
}

date	region	rigs_count
2022-11-01	west	159
2022-11-01	gulf	499
2022-11-01	midwest	127
2022-11-01	northeast	65
2022-11-02	midwest	125
2022-11-02	west	160
2022-11-02	gulf	501
2022-11-02	northeast	63
2022-11-03	northeast	63
2022-11-03	gulf	503

payload = {
   'aggregate_by': 'state_code'
}

date	rigs_count	state_ab
2022-11-01	21	WY
2022-11-01	25	CO
2022-11-01	18	WV
2022-11-01	20	OH
2022-11-01	439	TX
2022-11-01	60	LA
2022-11-01	27	PA
2022-11-01	44	ND
2022-11-01	113	NM
2022-11-01	83	OK

payload = {
   'aggregate_by': 'sub_region'
}

date	rigs_count	sub_region
2022-11-01	16	NE PA
2022-11-01	9	North - TX
2022-11-01	18	WV
2022-11-01	20	OH
2022-11-01	22	Central - TX
2022-11-01	44	North Dakota
2022-11-01	1	N LA
2022-11-01	2	SanJuan-CO
2022-11-01	32	Haynesville - TX
2022-11-01	23	Colorado wo SJ

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.

/regions

/shorttermforecast