Learn about the PetroVisor REST API and access the up-to-date documentation
The REST API provides read and write functionality for both the PetroVisor web app and the desktop app. The API endpoints are organized by the various data models used throughout the apps.
Aside from a few configuration endpoints for health checks, the PetroVisor API offers secure access to read and write data using authentication (signing in via OAuth2) and authorization (via permissions managed by PetroVisor administrators).
Details of the API endpoints and data models are documented in the Swagger links below and are always up-to-date.
PetroVisor Web API (US1)
PetroVisor Web API (EU1)
PetroVisor REST API is available in various languages.
C# REST API
To explore the full potential of .NET environment, one can refer to dedicated `Nuget` package found in the link below. It contains the full support for the above API endpoints listed in the Swagger links. The comprehensive documentation is available in the README section of the `Nuget` package description.
Python REST API
For all those Data Scientists and Python enthusiast we are happy to let you know that we have the dedicated Python package available as well.
The GitHub repository can be found by the following link:
Installation from PyPI
`petrovisor` package can be installed via `pip`
python -m pip install petrovisor
package can be futher import as follows:
import petrovisor as pv
Authorization
If one uses Jupyter notebook or running Python script from console for authorization the user is required to specify the `workspace` and `discovery_url`.
The `username` and `password` credentials can be entered either using the login dialog
workspace
workspace = 'Workspace Name'
url
discovery_url = r'https://identity.us1.petrovisor.com' # US
discovery_url = r'https://identity.eu1.petrovisor.com' # EU
PetroVisor API
pv_api = pv.PetroVisor(workspace = workspace,
discovery_url = discovery_url)
or by specifying `username` and `password` arguments directly
pv_api = pv.PetroVisor(workspace = workspace,
discovery_url = discovery_url,
username = username,
password = password)
After successful authorization the credentials key can be obtained
credentials_key = pv_api.Key
and can be used during next authorization session instead of `username` and `password`
pv_api = pv.PetroVisor(workspace = workspace,
discovery_url = discovery_url,
key = key)
Another option for authorizing is by using `api_endpoint` and `access_token` directly. This is useful when Python API is used in the Web Activities; e.g. through Azure Functions. In this case there is no need to specify the `discovery_url`
pv_api = pv.PetroVisor(workspace = workspace,
api = api_endpoint,
token = access_token)
Examples: Get, Post, Put, Delete requests
Basic API requests such as `get`, `post`, `put`, and `delete` consist of main URL/route part, as well as optional `data` and `query` string arguments. `data` and `query` arguments can presented by built-in `Python` dictionary.
Please refer to the Swagger documentation for the exact requirements for each request.
Make a `put` request
name = 'Well'
pv_api.put(f'Entities/{name}', data = {
'Name': name,
'EntityTypeName': 'Well',
'Alias': 'Well Alias',
'IsOpportunity': False,
})
Make a `post` request
old_name = 'Well'
new_name = 'New Well'
pv_api.post(f'Entities/Rename', query = {
'OldName': old_name,
'NewName': new_name,
})
Make a `get` request
name = 'New Well'
pv_api.get(f'Entities/{name}')
Make a `delete` request
name = 'New Well'
pv_api.delete(f'Entities/{name}')
Examples: Logs
To add the logs to the existing `PetroVisor` workspace `add_log_entry` method can be used, with `message` as a first argument and other optional arguments such as: `workflow`, `category`, `username`, `severity`, etc.
pv_api.add_log_entry('Hello PetroVisor!',
username = 'PetroVisor User')
Similarly, the logs for the PetroVisor `workflow` can be added using `add_workflow_log_entry` method.
pv_api.add_workflow_log_entry('Runing Python workflow, please wait ...!',
workflow = 'Python Workflow')
Examples: PetroVisor Items
Get the list of known PetroVisor item types
pv_api.get_item_types()
Get names of all `Entities` existing in the current `workspace`
pv_api.get_item_names('Entity')
Add new PetroVisor `item` or edit existing
name = 'Well Name'
pv_api.add_item('Entity', {
'Name': name,
'EntityTypeName': 'Well Name',
'Alias': 'Well ALias',
'IsOpportunity': False
})
Get existing PetroVisor `item`
name = 'Well Name'
pv_api.get_item('Entity',name)
Delete exisintg PetroVisor `item`
name = 'Well Name'
pv_api.delete_item('Entity',name)
Examples: Entities, Signals
Get all `Entities` existing in the current `workspace`
pv_api.get_entities()
Get all `Entity` names of specified type
pv_api.get_entity_names(entity_type = 'Well')
Get all `Signals` existing in the current `workspace`
pv_api.get_signals()
Get all `Signals` of specified type.
PetroVisor stores `static`, `time dependent`, `depth dependent`, `string`, `string time dependent` and `pvt` signals.
pv_api.get_signal_names(signal_type = 'time dependent')
Get `Entity` names which have specified `Signals` data
pv_api.get_entity_names(signal = 'cumulative oil production')
Get all `Signals` which are stored on the specified `Entity`
pv_api.get_signal_names(entity = 'Well Name')
Get `Signal` storage unit
pv_api.get_signal_unit('cumulative oil production')
Get units in which specified `Signal` can be measured
pv_api.get_signal_unit_names('cumulative oil production')
Examples: Workspace Values
Save `static` data
entity_name = 'Well Name'
signal_name = 'perforation top x'
signal_unit = 'm3'
pv_api.save_data('static', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
'Data': 435433.27,
}])
Save `time dependent` data
entity_name = 'Well Name'
signal_name = 'oil production rate'
signal_unit = 'm3/d'
pv_api.save_data('time', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
'Data': [
{'Date':'2023-02-13', 'Value': 436},
{'Date':'2023-02-14', 'Value': 453},
{'Date':'2023-02-15', 'Value': 635},
]}])
Save `depth dependent` data
entity_name = 'Well Name'
signal_name = 'gamma ray'
signal_unit = 'gAPI'
pv_api.save_data('depth', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
'Data': [
{'Depth': 2010, 'Value': 72.542},
{'Depth': 2011, 'Value': 73.499},
{'Depth': 2012, 'Value': 79.927},
]}])
Load `static` data
pv_api.load_data('static', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
}])
Load `time dependent` data
pv_api.load_data('time', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
}],
start = '2023-02-13',
end = '2022-08-15',
step = 'daily',
)
Load `depth dependent` data
pv_api.load_data('depth', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
}],
start = 2010,
end = 2012,
step = 'meter',
)
Delete `static` data
pv_api.delete_data('static', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
}])
Delete `time dependent` data
pv_api.delete_data('time', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
}],
start = '2023-02-13',
end = '2022-08-15',
)
Delete `depth dependent` data
pv_api.delete_data('depth', [{
'Entity': entity_name,
'Signal': signal_name,
'Unit': signal_unit,
}],
start = 2010,
end = 2012,
)
Examples: P# Scripts
With P# script engineers can process data in an easy and friendly way. Here are some helpful examples of processing P# scripts from Python.
Get P# script table names
psharp_script_name = 'P# script name'
pv_api.get_psharp_script_table_names(psharp_script_name)
Execute P# script for specified table and get `pandas` DataFrame as a result.
Resulting table will contain columns such as `Entity`, `Date`, `Depth`, `Signal Name [unit name]`
table_name = 'P# script table name'
df = pv_api.load_psharp_table(psharp_script_name, table = table_name)
Execute P# script with all tables and get a dictionary with table name as a `key` and `pandas` DataFrame as `value`
d = pv_api.load_psharp_table(psharp_script_name)
# result: d = {'table_1': df1, 'table_2': df2}
Save data from `DataFrame` to corresponsing signals.
The `DataFrame` should contain `Entity` column, and `Date`, `Depth` columns depdending on the type of signals present in the `DataFrame`.
The signal columns should have format `Signal Name [unit name]`.
pv_api.save_table_data(df)
Another examples
Check other examples in the examples
and the directory of the Python package repository.