/wells#

Oil wells are created by drilling into an oil or gas reserve. They are mounted with a drilling device such as a pumpjack which allows extraction of oil from the reserve using a variety of different drilling methods.

This endpoint returns well-level data.

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

Usage#

Python#

wells(county=[None], end_date=None, operator=[None], region=[None], start_date=None, state_code=[None], sub_region=[None])#

Returns well-level data derived from all available sources organized by 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.wells(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
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"]`
sub_region	string array	Limit search by a list of subregions (clusters of several counties forming a major producing basin).	`["S LA", "West - TX"]`
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"]`

Response#

Parameter	Type	Description	Example
api	integer	An API is a unique, permanent, numeric identifier assigned to each well drilled.	1701121257
completion_date	string	Date on which the well was completed. Date formatting - [“YYYY-MM-DD”]	“2021-05-25”
county	string	County in the state where the well is located.	“BEAUREGARD”
horizontal_length	integer	The horizontal length of a well in feet.	13
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”
measured_depth	integer	The measured operating depth of a well in feet.	9791
operator_name	string	Operator of the well.	“PIE OPERATING, LLC”
permit_date	string	The date on which the well permit was authorized. Date formatting - [“YYYY-MM-DD”]	“2021-01-20”
production_first_date	string	(Unsynced) date on which the well was first productive after completion. Date formatting - [“YYYY-MM-DD”]	“2021-07-01”
region	string	Aggregation of multiple major producing basins.	“GULF”
spud_date	string	Spudding is the day the main drill bit enters the ground, which leads to the removal of rock, dirt, and sedimentary materials. Date formatting - [“YYYY-MM-DD”]	“2021-03-26”
state_ab	string	Abbreviation of the state.	“LA”
sub_region	string	Aggregation of several counties, typically representing a major producing basin.	“S LA”
total_vertical_depth	integer	The total vertical depth of an operating well in feet.	100
wellbore_type	string	The orientation of the well bore used to locate and extract oil and gas from a well. Valid types are ‘vertical’, ‘horizontal’, and ‘directional’.	“directional”
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.

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	lat	long	operator_name	permit_date	region	state_ab	sub_region
4200547	ANGELINA	32.283661	-94.124666			gulf	TX	Haynesville - TX
4202797	BELL	28.336888	-98.293722			gulf	TX	South - TX
4230056	POTTER	35.531632	-101.921898			gulf	TX	North - TX
4280506	COLEMAN	31.642744	-99.47047			gulf	TX	Central - TX
4280508	COLEMAN	31.642739	-99.469396			gulf	TX	Central - TX
4280511	COLEMAN	31.646126	-99.470153			gulf	TX	Central - TX
37724663	BUTLER	40.838666	-80.054944	REX ENERGY OPERATING CORP		northeast	PA	SW PA
42009432	ARCHER	33.746575	-98.680589			gulf	TX	Central - TX
42300000	WICHITA	33.974131	-98.916673			gulf	TX	Central - TX
100120000	AUTAUGA	32.406535	-86.565567		1956-03-22		AL

Note

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

/TILs

Pipeline Scrapes