/productionbywell

This endpoint returns monthly oil and gas production figures for a specific well.

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.

Endpoint

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

Usage

Python

production_by_well(aggregate_by=[None], api=[None], county=[None], end_date=None, operator=[None], production_month=[None], region=[None], start_date=None, state_code=[None], sub_region=[None])

Returns well-level oil and gas production (monthly).

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.production_by_well(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	str arr	Aggregate data by a list of parameters.	["date", "region"]
api	str arr	Well API numbers passed as strings.	["4200347857", "4200347858"]
county	str arr	Limit search by a list of counties.	["Beauregard", "Coleman", "Colorado"]
end_date	str [“YYYY-MM-DD”]	Limit search to an end date.	"2022-07-15"
operator	str arr	Limit search to a list of well operators.	["ALLEN BROTHERS", "BP"]
production_month	int arr	Represents one or more months since the well started producing. Starts from 1 and increases by 1 for each subsequent month of production.	[1,2,3]
region	str arr	Limit search by a list of regions (clusters of multiple major producing basins).	["GULF", "WEST"]
start_date	str [“YYYY-MM-DD”]	Limit search to a start date.	"2022-06-01"
state_code	str arr	Limit search by a list of state codes.	["LA", "CO"]
sub_region	str arr	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
api	int	An API is a unique, permanent, numeric identifier assigned to each well drilled.	1701121257
county	str	County in the state where the well is located.	“BEAUREGARD”
date	str [“YYYY-MM-DD”]	Unsynced date on which oil and gas production starts.	“2022-06-01”
field_name	str	The name of a specific oil and gas field - as designated by the appropriate state agency.	“Caddo Pine Island”
formation	str	Definition of the geological makeup (formation) at a specific well.	“oil shale formation”
gas_daily	float	Average rate of gas production expressed per day (in MCF/day).	23.842
gas_monthly	int	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	int	The amount of oil produced over one month (in BBLS, or barrels).	5650
operator_name	str	Operator of the well.	“PIE OPERATING, LLC”
production_month	int	Month of gas or oil production. Starts from 1 and increases by 1 for each subsequent month of production.	4
range	str	Ranges are columns of townships set side-by-side. Range numbers start at the meridian that passes through the point of origin of each system and runs east to west.	“16W”
region	str	Aggregation of multiple major producing basins.	“GULF”
section	int	A section is a further subdivision of a township, represented by a numerical value between 1 and 36. Each section is about 1 square mile.	“34”
state_ab	str	Abbreviation of the state.	“LA”
sub_region	str	Aggregation of several counties, typically representing a major producing basin.	“S LA”
township	str	Townships are divisions of a county, shaped as squares with 6 miles to a side. Township squares are gridded and numbered according to their position north or south of the baseline.	“21N”
water_daily	float	The amount of water extracted from the well during a single day (in BBLs, or barrels).	23.296827
water_monthly	int	The amount of water extracted from the well during a one-month production period (in BBLs, or barrels).	947
well_name	str	The name assigned to a well at a specific site.	“SL 2259”
well_no	str	The number assigned to a well at a specific site.	“058”

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	field_name	formation	gas_daily	gas_monthly	oil_daily	oil_monthly	operator_name	production_month	range	region	section	state_ab	sub_region	township	water_daily	water_monthly	well_name	well_no
0	Jefferson Davis	1977-01-01	Wildcat-So La Lk Charles Dist		46.0	1444.0	33.0	1035		1	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-02-01	Wildcat-So La Lk Charles Dist		51.0	1436.0	30.0	845		2	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-03-01	Wildcat-So La Lk Charles Dist		47.0	1462.0	30.0	946		3	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-04-01	Wildcat-So La Lk Charles Dist		51.0	1551.0	28.0	852		4	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-05-01	Wildcat-So La Lk Charles Dist		40.0	1269.0	28.0	877		5	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-06-01	Wildcat-So La Lk Charles Dist		42.0	1283.0	33.0	1001		6	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-07-01	Wildcat-So La Lk Charles Dist		49.0	1545.0	28.0	893		7	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-08-01	Wildcat-So La Lk Charles Dist		54.0	1684.0	28.0	895		8	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-09-01	Wildcat-So La Lk Charles Dist		55.0	1679.0	26.0	785		9	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005
0	Jefferson Davis	1977-10-01	Wildcat-So La Lk Charles Dist		55.0	1729.0	25.0	804		10	03W	gulf	014	LA	S LA	11S			SPARGE POINT	005

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	gas_daily	gas_monthly	oil_daily	oil_monthly	water_daily	water_monthly
Pearl River	2022-11-01	193.0	5845.0	20.0	640.0	73.0	2258.0
Washington	2022-11-01	149175.0	4483662.0	10942.0	341105.0	44856.0	1347704.0
Assumption	2022-11-01			45.0	1404.0
Trumbull	2022-11-01	881.0	26494.0	5.0	208.0	12.0	425.0
Colorado	2022-11-01	28956.0	870222.0	1003.0	32194.0
Winkler	2022-11-01	125418.0	3794474.0	48642.0	1499846.0
Brazoria	2022-11-01	18978.0	572447.0	7342.0	240132.0
Ritchie	2022-11-01	427765.0	12836233.0	1019.0	33412.0	8662.0	263262.0
Bottineau	2022-11-01	450.0	16220.0	3632.0	115712.0	66393.0	1998257.0
SELDOVIA	2022-11-01	15126.0	454043.0	2358.0	70811.0	614.0	18661.0

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.