Developer Docs
API Quick Start Tutorials

Python Tutorial

Author(s): Clark Chen and Kyle Vessey, November 2022

Developer Prerequisites:

Data Schema: Please read the Data Schema Fundamentals document before using the API. Database CRUD operations are performed via the API and therefore it is important to think of each HTTP REST operation (POST/GET/DELETE) as SQL transaction (UPSERT/SELECT/DELETE)

Visualizing Data:

Data inserted or modified using this tutorial can be visualized using the web portal application(s) at https://app.onxecta.com. The portal contains a Model Quality tool where you can see what data is in the system, the validity of the data and when the data was last modified.

1 Create Project and Connect

1.1 Project Creation

Create New Project in VS Code

Create a new folder on your machine to begin building your project

Open the folder, and create a new Python file

Open Existing Project in VS Code

1.2 Install Xecta.Data.APIClient

Download latest Xecta.Data.API Client from PIP Package Manager

The Xecta Data API Client is hosted as a Python package in PyPi

To install the API Client, run the following command in your command prompt window:

Python
Python3


This will pull the compiled package from PyPi and install it on your machine.

Install and Configure SDK

To initialize and configure you project to include the SDK, follow this code sample

Python


Error Initializing Certificate and Key: When calling the xecta_api.authenticate method, you must pass in the environment URL, signed certificate (xecta-data-api.pem), and your private key (xecta-data-api.key)

If you get an error message stating: [SSL: CERTIFICATE_VERIFY_FAILED], try the following fix:

MacOS: Navigate to Macintosh HD > Applications > PythonX.X folder (where X is the version of Python you are using) > then double click on "Install Certificates.command" file

Install Certificates
Install Certificates


1.3 Pre-requisite - Dependent Python Libraries Installation

a) Required Python libraries - Pandas and Numpy

Python


b) Optional Python libraries - tqdm (For displaying progress bar of data processing)

Python


1.4 Import required Python Libraries and API Client

Python


2 Well Headers

2.1 Insert or Upsert a Well Header

a) Data Preparation - Import well header from source data (.xlsx data demonstrated in this tutorial)

Python


b) Create a function to convert field names in camel case to snake case

  • This function will be used for other source data as well
Python


c) Change field names and data type to be consistent with data schema

Python


d) Upsert wellheader data to API client

Python


Potential Error: Null values in non-nullable fields

Example: Null in field 'lat' will return error message when upserting

Document image


2.2 Get a Well Header Record

Python


2.3 Get All Well Header Records

Python


2.4 Delete a Well Header Record

Python


3 Daily Production

3.1 Insert or Upsert single Daily Production record

a) Create daily production input (Example data demonstrated)

Python


b) Upsert daily production to API client

Python


API response when upserted successfully



Document image


API response when error occurred (Example: uwi of upserted daily production doesn't exist in wellheader)



Document image


3.2 Insert a History of Daily Production (Multiple Records)

3.2.1 Daily Production Input Preparation

a) Import daily production from source data (.xlsx data demonstrated in this tutorial)

Python


b) Input data preparation - change field names and data type to be consistent with data schema

Python


3.2.2 Basic Method of upserting multiple records

Batch Processing:

In order to reduce the payload, it is recommended to upsert the daily production of each well in batches

Python

Python


Potential Error: API response will return 400 error code when uwi of daily production doesn't exist in database 

Document image


3.3 Get a Daily Production History

Python


3.4 Remove a Daily Production Record

Python


If daily production has been successfully deleted, API response will return number of records which was just deleted.

(In this example 658 records were deleted)

Document image




If uwi doesn't exist in database, API response will return 400 error code.



Document image


4. Wellbore

4.1 Upsert a wellbore record

a) Data Preparation (Data import and format conversion)

Python


b) Upsert wellbore record

Python


4.2 Get a wellbore record

4.2.1 Get Wellbore Record by Source Well ID

Python


4.2.2 Get Wellbore Record by Source Well ID and Source Wellbore ID

Python


4.3 Delete a wellbore record by Source Well ID

Python


4.4 Delete a wellbore record by Source Well ID and Source Wellbore ID

Python


5 Deviation Survey

5.1 Upsert deviation survey

a) Data preparation (Data import and formation conversion)

Python


b) Upsert deviation survey

Python


5.2 Get Deviation Survey

5.2.1 Get Deviation Survey by Source Well ID

Python


5.2.2 Get Deviation Survey by Source Well ID and Source Wellbore ID

Python


5.2.3 Get Deviation Survey by Source

Python


5.3 Delete Deviation Survey

5.3.1 Delete Deviation Survey by Source Well ID

Python


5.3.2 Delete Deviation Survey by Source Well ID and Source Wellbore ID

Python


5.3.3 Delete Deviation Survey by Source

Python


6 Casing

6.1 Upsert Casing Records

a) Data Preparation (Data import and data format conversion)

Python


b) Upsert casing data

Python


6.2 Get casing record

6.2.1 Get Casing Record by Source Well ID

Python


6.2.2 Get Casing Record by Source Well ID and Source Wellbore ID

Python


6.2.3 Get Casing Record by Source

Python


6.3 Delete Casing Records

6.3.1 Delete Casing Records by Source Well ID

Python


6.3.2 Delete Casing Records by Source Wellbore ID

Python


6.3.2 Delete Casing Records by Source

Python


7 Tubing

7.1 Upsert Tubing Records

a) Data preparation (Data import and data format conversion)

Python


b) Upsert tubing records

Python


7.2 Get Tubing Records

7.2.1 Get Tubing Records by Source Well ID

Python


7.2.2 Get Tubing Records by Source Well ID and Source Wellbore ID

Python


7.2.3 Get Tubing Records by Source

Python


7.3 Delete Tubing Records

7.3.1 Delete Tubing Records by Source Well ID

Python


7.3.2 Delete Tubing Records by Source Well ID and Source Wellbore ID

Python


7.3.3 Delete Tubing Records by Source

Python


8 Formation

8.1 Upsert Formation

a) Data Preparation (Data import and formation conversion)

Python


b) Upsert formation

Python


8.2 Get formation

8.2.1 Get formation by source well ID

Python


8.2.2 Get formation by source wellbore ID

Python


8.3 Delete formation

8.3.1 Delete formation by source well ID

Python


8.3.2 Delete formation by source wellbore ID

Python