V2:
- Get the country list of all wells
- Get the field list of all wells
- Get a structure
- Get the well list
- Get the wellbore list
- Get the survey list
- Create a structure
- Create a well
- Create a wellbore
- Create a survey
- Code samples (JavaScript)
The API returns the country names that have been set by all wells in the current database.
Request Example
curl -request GET
--url '{baseURL}/drillplan/msd/v2/countries'
--header 'Authorization: value'
--header 'appkey: value'
--header 'content-type: application/json'
--header 'slb-data-partition-id: header'Response Example
[
"No Country",
"India",
"Croatia",
"Democratic Republic of the Congo",
"Angola"
]Note: "No Country" indicates some wells don't have country name.
The API returns the field names that have been set by all wells in the current database.
Request Example
curl -request GET
--url '{baseURL}/drillplan/msd/v2/fields'
--header 'Authorization: value'
--header 'appkey: value'
--header 'content-type: application/json'
--header 'slb-data-partition-id: header'Response Example
[
"No Field",
"field 1",
"field 2",
"field 3",
"field 4"
] Note: "No Field" indicates some wells don't have field name.
Retrieve a specific structure using a unique identifier ObjectId.
Structure Data Object
- id: Unique identifier ObjectId for the structure.
- name: Name of the structure.
- is_offshore: Boolean indicating if the structure is located offshore.
- location: Location of the structure.
- crs: A framework used to precisely measure locations on the surface of the Earth as coordinates.
- coordinates_type: spatial reference systems. Ensure that it matches exactly, including case sensitivity, whole words, and spaces.
- GRID: Flat, 2D Cartesian coordinates (Easting, Northing) on a map plane, derived by mathematically projecting the Earth's curved surface
- GEODETIC: Global angular coordinates (Latitude, Longitude) defining a point on the Earth's curved ellipsoidal surface, often with Height/Elevation
- northing: Y-coordinate in a coordinate reference system.
- easting: X-coordinate in a coordinate reference system.
- longitude: Angular coordinate east-west of the Prime Meridian.
- latitude: Angular coordinate north-south of the Equator.
- grid_convergence: Angular difference between grid north and true north.
- scale_factor: Scale factor applied in map projection calculations.
- crs_unit: Measurement unit used in the CRS Northing and Easting.
- wgs84_location: Geographic coordinates in WGS84 datum (latitude/longitude).
- longitude: Angular coordinate east-west of the Prime Meridian (WGS84).
- latitude: Angular coordinate north-south of the Equator (WGS84).
- ground_level: Elevation of ground level at the well location. It’s measured from the mean-sea level (MSL).
- source: Data source/origin of the well information. This is an enumeration, including:
- EDM: which is imported from EDM file.
- DOX: which is transferred from DOX.
- DrillPlan: which is created from DrillPlan.
- MSD: which is created from MSD.
- publicapi: which is created from public api.
- external_tag: User-definable labels.
- field: Name of the oil/gas field where the well is situated.
- north_reference: Reference system for directional measurements.
- Grid: Grid north.
- True: True north.
- uncertainty: A quantifiable doubt about the true value of a measurement.
- confidence: The probability that the true value lies within the stated uncertainty interval.
- radius: The half-width of the uncertainty interval around a measured value.
- slot_set: The set of slots.
- id: Unique identifier ObjectId for the slot.
- name: Name of the slot.
- location: Location of the structure.
- coordinates_type: Spatial reference systems. Ensure that it matches exactly, including case sensitivity, whole words, and spaces.
- GRID: Flat, 2D Cartesian coordinates (Easting, Northing) on a map plane, derived by mathematically projecting the Earth's curved surface.
- GEODETIC: Global angular coordinates (Latitude, Longitude) defining a point on the Earth's curved ellipsoidal surface, often with Height/Elevation.
- LOCAL CARTESIAN: Arbitrary 2D/3D Cartesian coordinates (East-West, North-South) defined relative to a local origin and orientation.
- LOCAL POLAR: Relative coordinates defined by measured Distance and Azimuth (horizontal angle) from a local instrument setup point.
- northing: Y-coordinate in a coordinate reference system.
- easting: X-coordinate in a coordinate reference system.
- longitude: Angular coordinate east-west of the Prime Meridian, unit is angular coordinate: Degrees (°).
- latitude: Angular coordinate north-south of the Equator, unit is angular coordinate: Degrees (°).
- ns: Distance northward from the same local origin point. Local coordinate.
- ew: Distance eastward from a locally defined origin point. Local coordinate.
- distance: Measured slope distance projected horizontally, or directly measured horizontal distance.
- azimuth: Measured clockwise angle from a defined reference direction.
- grid_convergence: Angular difference between grid north and true north.
- scale_factor: Scale factor applied in map projection calculations.
- coordinates_type: Spatial reference systems. Ensure that it matches exactly, including case sensitivity, whole words, and spaces.
- diameter: The size of the circular arcs forming the ends of the slot.
- wgs84_location: Geographic coordinates in WGS84 datum (latitude/longitude).
- longitude: Angular coordinate east-west of the Prime Meridian (WGS84).
- latitude: Angular coordinate north-south of the Equator (WGS84).
- external_tag: User-definable labels.
Request Example
curl -request GET
--url '{baseURL}/drillplan/msd/v2/structures/{id}'
--header 'Authorization: value'
--header 'appkey: value'
--header 'content-type: application/json'
--header 'slb-data-partition-id: header'Response Example
[
{
"id": "string",
"name": "string",
"is_offshore": true,
"location": {
"coordinates_type": "string",
"latitude": 0,
"longitude": 0,
"crs": "string",
"crs_unit": "string",
"northing": 0,
"easting": 0,
"grid_convergence": 0,
"scale_factor": 0
},
"wgs84_location": {
"longitude": 0,
"latitude": 0
},
"ground_level": 0,
"source": "string",
"external_tag": "string",
"field": "string",
"north_reference": "Grid",
"uncertainty": {
"confidence": 0,
"radius": 0
},
"slot_set": [
{
"id": "string",
"name": "string",
"wgs84_location": {
"longitude": 0,
"latitude": 0
},
"location": {
"ns": 0,
"ew": 0,
"distance": 0,
"azimuth": 0,
"northing": 0,
"easting": 0,
"grid_convergence": 0,
"scale_factor": 0,
"coordinates_type": "string",
"latitude": 0,
"longitude": 0
},
"diameter": 0,
"external_tag": "string"
}
]
}
]The API returns the well list.
Well Data Object
- id: Unique identifier ObjectId for the MSD well.
- name: Name of the well.
- structure_id: Reference ObjectId for an associated structure.
- structure: Name of the associated structure.
- slot_id: Id of the slot.
- client_name: Name of the client.
- ground_level: Elevation of ground level at the well location. It’s measured from the mean-sea level (MSL).
- wgs84_location: Geographic coordinates in WGS84 datum (latitude/longitude).
- longitude: Angular coordinate east-west of the Prime Meridian (WGS84).
- latitude: Angular coordinate north-south of the Equator (WGS84).
- is_offshore: Boolean indicating if the well is located offshore.
- true: offshore
- false: land
- field: Name of the oil/gas field where the well is situated.
- country: Country where the well is located.
- uwi: Unique Well Identifier
- source: Data source/origin of the well information. This is an enumeration, including:
- EDM: which is imported from EDM file.
- DOX: which is transferred from DOX.
- DrillPlan: which is created from DrillPlan.
- MSD: which is created from MSD.
- publicapi: which is created from public api.
- location: Projected coordinate system location details (easting/northing, etc.)
- crs: Name/ID of the Coordinate Reference System (CRS) used
- coordinates_type: Spatial reference systems. Ensure that it matches exactly, including case sensitivity, whole words, and spaces.
- GRID: Flat, 2D Cartesian coordinates (Easting, Northing) on a map plane, derived by mathematically projecting the Earth's curved surface.
- GEODETIC: Global angular coordinates (Latitude, Longitude) defining a point on the Earth's curved ellipsoidal surface, often with Height/Elevation.
- LOCAL CARTESIAN: Arbitrary 2D/3D Cartesian coordinates (East-West, North-South) defined relative to a local origin and orientation.
- LOCAL POLAR: Relative coordinates defined by measured Distance and Azimuth (horizontal angle) from a local instrument setup point.
- northing: Y-coordinate in a coordinate reference system.
- easting: X-coordinate in a coordinate reference system.
- latitude: Angular coordinate north-south of the Equator, unit is angular coordinate: Degrees (°).
- longitude: Angular coordinate east-west of the Prime Meridian, unit is angular coordinate: Degrees (°).
- ns: Distance northward from the same local origin point. Local coordinate.
- ew: Distance eastward from a locally defined origin point. Local coordinate.
- distance: Measured slope distance projected horizontally, or directly measured horizontal distance.
- azimuth: Measured clockwise angle from a defined reference direction.
- grid_convergence: Angular difference between grid north and true north, measured in plane angles.
- scale_factor: Scale factor applied in map projection calculations.
- crs_unit: Measurement unit used in the CRS Northing and Easting.
- uncertainty: A quantifiable doubt about the true value of a measurement.
- confidence: The probability that the true value lies within the stated uncertainty interval.
- radius: The half-width of the uncertainty interval around a measured value.
- north_reference: Reference system for directional measurements.
- Grid: Grid north.
- True: True north.
Parameters
- page: the index of the page, starting from 1, default is 1. If the page number is greater than the total page number, it returns an empty array.
- page size: number of wells per page, the range is 1-100, default is 100.
Payload
- All input text is case-sensitive. For instance, the results for "USA" and "usa" will be different.
- If the user wants to query data without a specified country, please set "No Country" in the country field.
- If the user wants to query data without a specified field, please set "No Field" in the country field.
- You can only set either the country or the field at a time; setting both simultaneously will result in a 400 error.
- If neither value is entered, the default response will include data for all wells.
Request Example
curl -i -X POST \
'{baseURL}/drillplan/apis/msdapi/v2/wells/query?page=0&page_size=0' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'slb-data-partition-id: string' \
-d '{
"field": "string",
"country": "string"
}'Response Example
[
{
"id": "string",
"name": "string",
"structure_id": "string",
"structure": "string",
"slot_id": "string",
"client_name": "string",
"ground_level": 0,
"wgs84_location": {
"longitude": 0,
"latitude": 0
},
"IsOffshore": true,
"field": "string",
"country": "string",
"uwi": "string",
"source": "string",
"location": {
"crs": "string",
"crs_unit": "string",
"coordinates_type": "string",
"northing": 0,
"easting": 0,
"latitude": 0,
"longitude": 0,
"grid_convergence": 0,
"scale_factor": 0,
"ns": 0,
"ew": 0,
"distance": 0,
"azimuth": 0
},
"north_reference": "Grid",
"uncertainty": {
"confidence": 0,
"radius": 0
},
"external_tag": "string"
}
]
Note:
- Returns 400 Bad Request, if the page size is out of the range.
- Returns 400 Bad Request, it cannot specify both field and country at the same time.
The API returns the wellbore list with the input well id.
Wellbore Data Object
- id: Unique identifier for the MSD wellbore.
- name: Name or label of the wellbore.
- well_id: Reference ID to the parent well.
- api: API (American Petroleum Institute) number, a standardized identifier for wellbores in the oil/gas industry.
- ubhi: Unique Borehole Identifier (UBHI), a distinct identifier for the borehole.
- business_system_id: Identifier from an external business system (e.g., Job Number or KUIEN, one of the two).
- parent_wellbore_id: Reference ID to the parent wellbore.
- external_tag: User-definable labels.
Request Example
curl -i -X GET \
'{baseURL}/drillplan/apis/msdapi/v2/wellbores/by-well/{wellId}' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'slb-data-partition-id: string'Response Example
[
{
"id": "string",
"name": "string",
"well_id": "string",
"api": "string",
"ubhi": "string",
"business_system_id": "string",
"parent_wellbore_id": "string",
"external_tag": "string",
}
]
The API returns the surveys list.
Survey Data Object
- id: Unique identifier for the MSD survey.
- name: Name/description of the survey.
- wellbore_id: Reference ID to the parent wellbore.
- survey_type: Classification of survey data. This is an enumeration, including:
- DefinitiveSurvey
- NonDefinitiveSurvey
- WorkingSurvey
- depth_reference: Elevation of Rotary Kelly Bushing (datum reference point for depth measurements), and it is above MSL.
- stations: List of survey stations defining the survey path.
- md: Measured Depth.
- incl: Inclination.
- azi: Azimuth.
- tvd: True Vertical Depth - vertical depth from Depth reference.
- ns: Local N/S (North-South) coordinate.
- ew: Local E/W (East-West) coordinate.
- dls: Dogleg Severity.
- tool_code: Identifier for survey tool code.
- calc_method: Algorithm used for Survey calculations.
- survey_date: The date when a survey was performed.
- geomag_settings: Refers to the configuration of parameters that define the Earth's magnetic field and related corrections used in directional drilling calculations. Proper geomag settings ensure accurate wellbore positioning by accounting for magnetic influences that affect downhole measurements.
- declination_date: (also known as the "epoch date" or "reference date") refers to the specific calendar date for which the magnetic declination (the angle between magnetic north and true north) is calculated or reported at a given location.
- geomagnetic_model: A mathematical representation (e.g., IGRF, BGGM) used to calculate local magnetic field values (including declination, dip angle, and field strength) at a specific location and time. Models are regularly updated to reflect changes in the Earth's magnetic field.
- field_strength: The intensity of the local Earth's magnetic field. Accurate field strength values are essential for correcting magnetic toolface readings and improving drilling precision.
- dip_angle: The angle at which the Earth's magnetic field lines intersect the horizontal plane. It varies with geographic location and helps determine local magnetic inclination for effective tool calibration and wellbore accuracy.
- declination: The angle between true geographic north (true north) and magnetic north. Declination must be accounted for to convert magnetic azimuth readings into true azimuth directions while drilling.
- tie_in: A reference point or depth in the well from which the planned trajectory or a new section of the wellbore is based.
- tie_in_md: The measured depth (MD) at which the tie-in occurs.
- tie_in_survey_id: The unique identifier of the survey record used as the tie-in point.
- hole_section: A discrete segment of the wellbore drilled with a particular bit size.
- name: The identifier or label assigned to a specific hole section (e.g., Surface, Intermediate, Production).
- end_md: The measured depth at which this hole section is designed or planned to end. This marks the transition point to the next hole section.
- hole_size: The diameter of the wellbore for the current hole section.
- external_tag: User-definable labels, free text.
Request Example
curl -request GET
--url '{baseURL}/drillplan/msd/v2/surveys/by-wellbore/{wellboreId}'
--header 'Authorization: value'
--header 'appkey: value'
--header 'content-type: application/json'
--header 'slb-data-partition-id: header'
Response Example
[
{
"id": "survey id 1",
"name": "survey name 1",
"wellbore_id": "wellbore id",
"stations": [
{
"md": 0.0,
"incl": 0.0,
"azi": 0.0,
"tvd": 0.0,
"ns": 0.0,
"ew": 0.0,
"dls": 0.0,
"tool_code": "ZERO",
"calc_method": " MinCurvature "
},
{
"md": 150.13,
"incl": 0.0,
"azi": 4.316548306032377,
"tvd": 150.13,
"ns": 0.0,
"ew": 0.0,
"dls": 0.0,
"tool_code": "SLB_MWD-STD-FLT",
"calc_method": "MinCurvature"
},
{
"md": 179.8,
"incl": 0.002094395102393196,
"azi": 4.316548306032377,
"tvd": 179.79997830880754,
"ns": -0.01198022573341854,
"ew": -0.028667755724058806,
"dls": 7.058965629906286E-05,
"tool_code": "SLB_MWD-STD-FLT",
"calc_method": "MinCurvature"
}
],
"survey_type": "DefinitiveSurvey",
"depth_reference": 26.06,
"survey_date": "2025-11-21T04:10:56.471Z",
"external_tag": null,
"geomag_settings": {
"declination_date": "2025-11-21T04:10:56.471Z",
"geomagnetic_model": "HDGM 2025",
"field_strength": 3.603725643839791E-05,
"dip_angle": 0.6733311719778312,
"declination": 0.09780679902883349
},
"tie_in": {
"tie_in_survey_id": null,
"tie_in_md": null
},
"hole_section": [
{
"name": null,
"end_md": 7.010400000000001,
"hole_size": 0.3302,
"casing_size": 0.0254
},
{
"name": null,
"end_md": 7.315200000000001,
"hole_size": 0.35559999999999997,
"casing_size": 0.0254
}
]
},
{
"id": "survey id 2",
"name": "survey name 2",
"wellbore_id": "wellbore id",
"stations": [
{
"md": 0.0,
"incl": 0.0,
"azi": 0.0,
"tvd": 0.0,
"ns": 0.0,
"ew": 0.0,
"dls": 0.0,
"tool_code": "SLB_MWD-STD-FLT",
"calc_method": " MinCurvature "
},
{
"md": 722.3760000000001,
"incl": 0.0,
"azi": 0.0,
"tvd": 722.3760000000001,
"ns": 0.0,
"ew": 0.0,
"dls": 0.0,
"tool_code": "SLB_INCL_ONLY_VERTICAL_ACTUAL",
"calc_method": "IncOnly"
},
{
"md": 853.7448,
"incl": 0.001570796389212735,
"azi": 3.236363904141354,
"tvd": 853.7446706589755,
"ns": -0.022163302117696734,
"ew": -0.0021067549743618956,
"dls": 0.0001476160118063521,
"tool_code": "SLB_MWD-STD",
"calc_method": "MinCurvature"
}
],
"survey_type": "NonDefinitiveSurvey",
"depth_reference": 26.06,
"survey_date": "2025-11-21T04:10:56.471Z",
"external_tag": null,
"geomag_settings": {
"declination_date": "2025-11-21T04:10:56.471Z",
"geomagnetic_model": "HDGM 2025",
"field_strength": 3.603725643839791E-05,
"dip_angle": 0.6733311719778312,
"declination": 0.09780679902883349
},
"tie_in": {
"tie_in_survey_id": null,
"tie_in_md": null
},
"hole_section": [
{
"name": null,
"end_md": 7.010400000000001,
"hole_size": 0.3302,
"casing_size": 0.0254
},
{
"name": null,
"end_md": 7.315200000000001,
"hole_size": 0.35559999999999997,
"casing_size": 0.0254
}
]
},
]
Create a new structure.
Structure Data Object
- name: Name of the structure. (Required)
- is_offshore: Boolean indicating if the structure is located offshore. (Required)
- location: Location of the structure. (Required)
- crs: A framework used to precisely measure locations on the surface of the Earth as coordinates.
- coordinates_type: Spatial reference systems. Ensure that it matches exactly, including case sensitivity, whole words.
- GRID: Flat, 2D Cartesian coordinates (Easting, Northing) on a map plane, derived by mathematically projecting the Earth's curved surface.
- GEODETIC: Global angular coordinates (Latitude, Longitude) defining a point on the Earth's curved ellipsoidal surface, often with Height/Elevation.
- northing: Y-coordinate in a coordinate reference system.
- easting: X-coordinate in a coordinate reference system.
- longitude: Angular coordinate east-west of the Prime Meridian, unit is angular coordinate: Degrees (°).
- latitude: Angular coordinate north-south of the Equator, unit is angular coordinate: Degrees (°).
- ground_level: Elevation of ground level at the well location. It’s measured from the mean-sea level (MSL). (Required)
- external_tag: User-definable labels, free text.
- field: Name of the field. (Required)
- north_reference: Reference system for directional measurements. (Required)
- Grid: Grid
- True: True
- uncertainty: A quantifiable doubt about the true value of a measurement.
- confidence: The probability that the true value lies within the stated uncertainty interval.
- radius: The half-width of the uncertainty interval around a measured value.
- slot_set: The set of Slots.
- name: Name of the slot. (Required)
- location: Location of the slot. (Required)
- coordinates_type: Spatial reference systems. Ensure that it matches exactly, including case sensitivity, whole words, space words.
- GRID: Flat, 2D Cartesian coordinates (Easting, Northing) on a map plane, derived by mathematically projecting the Earth's curved surface.
- GEODETIC: Global angular coordinates (Latitude, Longitude) defining a point on the Earth's curved ellipsoidal surface, often with Height/Elevation.
- LOCAL CARTESIAN: Arbitrary 2D/3D Cartesian coordinates (East-West, North-South) defined relative to a local origin and orientation.
- LOCAL POLAR: Relative coordinates defined by measured Distance and Azimuth (horizontal Angle) from a local instrument setup point.
- northing: Y-coordinate in a coordinate reference system.
- easting: X-coordinate in a coordinate reference system.
- latitude: Angular coordinate north-south of the Equator, unit is angular coordinate: Degrees (°).
- longitude: Angular coordinate east-west of the Prime Meridian, unit is angular coordinate: Degrees (°).
- ns: Distance northward from the same local origin point. Local coordinate.
- ew: Distance eastward from a locally defined origin point. Local coordinate.
- distance: Measured slope distance projected horizontally, or directly measured horizontal distance. Local coordinate.
- azimuth: Measured clockwise angle from a defined reference direction.
- coordinates_type: Spatial reference systems. Ensure that it matches exactly, including case sensitivity, whole words, space words.
- diameter: The size of the circular arcs forming the ends of the slot.
- external_tag: User-definable labels, free text.
Request Example
curl -i -X POST \
https://wys-01jwsqnmqenec5qj007071bb0n.wysiwyg.cloud.redocly.com/_mock/solutions/drillplan/apis/msdapi/v2/structures \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'slb-data-partition-id: string' \
-d '{
"name": "string",
"is_offshore": true,
"location": {
"coordinates_type": "string",
"northing": 0,
"easting": 0,
"latitude": 0,
"longitude": 0,
"crs": "string"
},
"ground_level": 0,
"field": "string",
"external_tag": "string",
"uncertainty": {
"confidence": 0,
"radius": 0
},
"north_reference": "Grid",
"slot_set": [
{
"name": "string",
"diameter": 0,
"external_tag": "string",
"location": {
"coordinates_type": "string",
"northing": 0,
"easting": 0,
"latitude": 0,
"longitude": 0,
"ns": 0,
"ew": 0,
"distance": 0,
"azimuth": 0
}
}
]
}'Response Example
{
"createdId": "684680422e3c38813af4dfd2"
}Create a new well.
Well Data Object
- name: Name of the well. (Required)
- slot_id: Unique identifier ObjectId for the slot.
- structure_id: Unique identifier ObjectId for the structure. (Required)
- location: Location of the well. (Required)
- crs: A framework used to precisely measure locations on the surface of the Earth as coordinates. It will use the structure's CRS if a CRS is not provided.
- coordinates_type: Spatial reference systems. Ensure that it matches exactly, including case sensitivity, whole words, space words.
- GRID: Flat, 2D Cartesian coordinates (Easting, Northing) on a map plane, derived by mathematically projecting the Earth's curved surface.
- GEODETIC: Global angular coordinates (Latitude, Longitude) defining a point on the Earth's curved ellipsoidal surface, often with Height/Elevation.
- LOCAL CARTESIAN: Arbitrary 2D/3D Cartesian coordinates (East-West, North-South) defined relative to a local origin and orientation.
- LOCAL POLAR: Relative coordinates defined by measured Distance and Azimuth (horizontal Angle) from a local instrument setup point.
- northing: Y-coordinate in a coordinate reference system.
- easting: X-coordinate in a coordinate reference system.
- latitude: Angular coordinate north-south of the Equator, unit is angular coordinate: Degrees (°).
- longitude: Angular coordinate east-west of the Prime Meridian, unit is angular coordinate: Degrees (°).
- ns: Distance northward from the same local origin point, Local coordinate.
- ew: Distance eastward from a locally defined origin point. Local coordinate.
- distance: Measured slope distance projected horizontally, or directly measured horizontal distance. Local coordinate.
- azimuth: Measured clockwise angle from a defined reference direction.
- ground_level: Elevation of ground level at the well location. It’s measured from the mean-sea level (MSL). (Required)
- external_tag: User-definable labels, free text.
- country: Country where the well is located.
- client_name: Name of the client.
- uncertainty: A quantifiable doubt about the true value of a measurement.
- confidence: The probability that the true value lies within the stated uncertainty interval.
- radius: The half-width of the uncertainty interval around a measured value.
- uwi: Unique Well Identifier.
Request Example
curl -i -X POST \
{baseURL}/drillplan/msd/v2/wells \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'slb-data-partition-id: string' \
-d '{
"name": "string",
"structure_id": "string",
"slot_id": "string",
"location": {
"coordinates_type": "string",
"northing": 0,
"easting": 0,
"latitude": 0,
"longitude": 0,
"crs": "string",
"ns": 0,
"ew": 0,
"distance": 0,
"azimuth": 0
},
"ground_level": 0,
"country": "string",
"client_name": "string",
"uncertainty": {
"confidence": 0,
"radius": 0
},
"uwi": "string",
"external_tag": "string"
}'Response Example
{
"createdId": "684680422e3c38813af4dfd5"
}Create a new wellbore.
Wellbore Data Object
- name: Name of the wellbore. (Required)
- well_id: Reference ID to the parent well. (Required)
- api: API (American Petroleum Institute) number, a standardized identifier for wellbores in the oil/gas industry.
- ubhi: Unique Borehole Identifier (UBHI), a distinct identifier for the borehole.
- parent_wellbore_id: Reference ID to the parent wellbore.
- external_tag: User-definable labels.
Request Example
curl -i -X POST \
{baseURL}/drillplan/msd/v2/wellbores \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'slb-data-partition-id: string' \
-d '{
"name": "string",
"well_id": "string",
"api": "string",
"ubhi": "string",
"parent_wellbore_id": "string",
"external_tag": "string"
}'Response Example
{
"createdId": "684680422e3c38813af4dfd5"
}Create a new survey.
Survey Data Object
- name: Name/description of the survey.
- wellbore_id: Reference ID to the parent wellbore.
- survey_type: Classification of survey data. This is an enumeration, including:
- DefinitiveSurvey
- NonDefinitiveSurvey
- WorkingSurvey
- survey_date: The date when a survey was performed.
- north_reference: Determines which of these NorthReferences the azimuth angles are referenced to.
- Grid: The north direction defined by map grid lines (e.g., UTM), which may differ slightly from True North depending on the map projection.
- True: Geographic north, based on the Earth's axis, representing the direction toward the North Pole.
- depth_reference: Elevation of Rotary Kelly Bushing (datum reference point for depth measurements), and it is above MSL.
- stations: List of survey stations defining the survey path.
- md: Measured Depth.
- incl: Inclination, measured in plane angles.
- azi: Azimuth, measured in plane angles.
- tvd: True Vertical Depth - vertical depth from Depth reference.
- ns: Local N/S (North-South) coordinate.
- ew: Local E/W (East-West) coordinate.
- tool_code: Identifier for survey tool code.
- geomag_settings: Refers to the configuration of parameters that define the Earth's magnetic field and related corrections used in directional drilling calculations. Proper Geomag Settings ensure accurate wellbore positioning by accounting for magnetic influences that impact downhole measurements.
- declination_date: (also known as the "epoch date" or "reference date") refers to the specific calendar date for which the magnetic declination (the angle between magnetic north and true north) is calculated or reported at a given location.
- geomagnetic_model: A mathematical representation (e.g., IGRF, BGGM) used to calculate local magnetic field values (including declination, dip angle, and field strength) at a specific location and time. Models are regularly updated to reflect changes in the Earth's magnetic field.
- field_strength: The intensity of the local Earth's magnetic field.
- dip_angle: The angle at which the Earth's magnetic field lines intersect the horizontal plane, measured in degrees. It varies with geographic location and helps determine local magnetic inclination for effective tool calibration and wellbore accuracy.
- declination: The angle between true geographic north (true north) and magnetic north, usually measured in degrees east or west. Declination must be accounted for to translate magnetic azimuth readings into true azimuth directions while drilling.
- tie_in: A reference point or depth in the well from which the planned trajectory or a new section of the wellbore is based.
- tie_in_md: The measured depth (MD) at which the tie-in occurs.
- tie_in_survey_id: The unique identifier of the survey record used as the tie-in point.
- hole_section: A discrete segment of the wellbore drilled with a particular bit size.
- name: The identifier or label assigned to a specific hole section (e.g., Surface, Intermediate, Production).
- end_md: The measured depth at which this hole section is designed or planned to end. This marks the transition point to the next hole section.
- hole_size: The diameter of the wellbore for the current hole section.
- casing_size: The casing size is the nominal outside diameter (OD) of the casing pipe.
- external_tag: User-definable labels, free text.
Request example for creating a standalone survey
curl -i -X POST \
{baseURL}/drillplan/apis/msdapi/v2/surveys \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'slb-data-partition-id: string' \
-d '{
"name": "string",
"wellbore_id": "string",
"survey_type": "DefinitiveSurvey",
"survey_date": "string",
"north_reference": "Grid",
"depth_reference": 0,
"stations": [
{
"md": 0,
"incl": 0,
"azi": 0,
"tvd": 0,
"ns": 0,
"ew": 0,
"tool_code": "string"
}
],
"geomag_settings": {
"declination_date": "2019-08-24T14:15:22Z",
"geomagnetic_model": "string",
"field_strength": 0,
"dip_angle": 0,
"declination": 0
},
"external_tag": "string",
"hole_section": [
{
"name": "string",
"end_md": 0,
"hole_size": 0,
"casing_size": 0
}
]
}'Request example for creating a sidetrack survey
curl -i -X POST \
{baseURL}/drillplan/apis/msdapi/v2/surveys \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-H 'slb-data-partition-id: string' \
-d '{
"name": "string",
"wellbore_id": "string",
"survey_type": "DefinitiveSurvey",
"survey_date": "string",
"north_reference": "Grid",
"depth_reference": 0,
"stations": [
{
"md": 0,
"incl": 0,
"azi": 0,
"tvd": 0,
"ns": 0,
"ew": 0,
"tool_code": "string"
}
],
"geomag_settings": {
"declination_date": "2019-08-24T14:15:22Z",
"geomagnetic_model": "string",
"field_strength": 0,
"dip_angle": 0,
"declination": 0
},
"external_tag": "string",
"tie_in": {
"tie_in_survey_id": "string",
"tie_in_md": 0
},
"hole_section": [
{
"name": "string",
"end_md": 0,
"hole_size": 0,
"casing_size": 0
}
]
}'Response Example
{
"createdId": "684680422e3c38813af4dfd5"
}- A structure is created first.
- A well is added beneath the structure.
- Within that well, a main bore is created, followed by a survey associated with the main bore.
- A sidetrack wellbore is then created from the same well.
- A corresponding sidetrack survey is added beneath the sidetrack wellbore.
//Step 1.
(async () => {
const structureId = createStructure();
console.log("Structure created with ID: " + structureId);
//Output:
//Structure created with ID: 632c32d69a3043bfefe09508
})();
//Step 2.
(async () => {
const wellId = createWell('632c32d69a3043bfefe09508');
console.log("Well created with ID: " + wellId);
//Output:
//Well created with ID: 6581709a6c28ffeda32bf040
})();
//Step 3.
(async () => {
const mainboreId = createMainBore('6581709a6c28ffeda32bf040');
console.log("Main bore created with ID: " + mainboreId);
//Output:
//Main bore created with ID: 632c32ce9a3043bfefe094f0
})();
(async () => {
const surveyId = createSurvey('632c32ce9a3043bfefe094f0');
console.log("Survey created with ID: " + surveyId);
//Output:
//Survey created with ID: 63310edc6830e960abbcb994
})();
//Step 4.
(async () => {
const sidetrackWellboreId = createSubBore('6581709a6c28ffeda32bf040', '632c32ce9a3043bfefe094f0');
console.log("Sidetrack wellbore created with ID: " + sidetrackWellboreId);
//Output:
//Sidetrack wellbore created with ID: 65816eb06c28ffeda32bf017
})();
//Step 5.
(async () => {
const sidetrackSurveyId = createSidetrackSurvey('65816eb06c28ffeda32bf017', '63310edc6830e960abbcb994');
console.log("Sidetrack survey created with ID: " + sidetrackSurveyId);
//Output:
//Sidetrack survey created with ID: 65816f606c28ffeda32bf038
})();async function createStructure() {
let json = {
"name": "test structure",
"is_offshore": false,
"ground_level": 123.45,
"location": {
"crs": "HPGN California State Plane, Zone V, Meters",
"coordinates_type": "Grid",
"northing": 1234567.78, //required if coordinates_type is Grid.
"easting": 1234567.00, //required if coordinates_type is Grid.
"latitude": 123456.00, //required if coordinates_type is Geodetic.
"longitude": 123456.00, //required if coordinates_type is Geodetic.
},
"field": "Test Field",
"external_tag": null,
"uncertainty": {
"confidence": 3.00,
"radius": "9"
},
"north_reference": "grid",
"slot_set": [
{
"name": "Slot 1A",
"diameter": 1,
"external_tag": "tag for slot",
"location": {
"coordinates_type": "LOCAL CARTESIAN",
"ns": 1.1234567890123,
"ew": 1.1234567890123,
"distance": 123.45,
"azimuth": 0.00,
"northing": 1234567.00,
"easting": 1234567.00,
"latitude": 123456.00,
"longitude": 123456.00,
}
}
]
};
let postUrl = "/public/api/msd/v2/structures";
const res = await post(postUrl, json);
return res.createdId ?? res.createdId
}
async function createWell(structureId) {
let json = {
"name": "well 1",
"slot_id":"" // Optional
"structure_id": structureId,
"location": {
"crs": "NAD83 Pennsylvania State Plane, Northern Zone, US Feet"
"ns": 1.1234567890123,
"ew": 1.1234567890123,
"distance": 123.45,
"azimuth": 0.00,
"coordinates_type": "Grid",
"northing": 123456.78,
"easting": 123456.56,
"latitude": 123456,
"longitude": 123456,
},
"ground_level": 123.45,
"external_tag": null,
"country":"test"
"client_name":"test"
"uncertainty": {
"confidence": 12.34,
"radius": 9.00
},
"uwi": "test"
};
let postUrl = "/public/api/msd/v2/wells";
const res = await post(postUrl, json);
return res.createdId ?? res.createdId
}
async function createMainBore(wellId) {
let json = {
"well_id": wellId,
"name": "main bore",
"api": "test",
"ubhi": "test",
"parent_wellbore_id": null,//optional if creating main bore.
"external_tag": "Tag_0"
};
let postUrl = "/public/api/msd/v2/wellbores";
const res = await post(postUrl, json);
return res.createdId ?? res.createdId
}
async function createSubBore(wellId, parentWellboreId) {
let json = {
"well_id": wellId,
"name": "sub bore",
"api": "2332",
"ubhi": "6789042",
"parent_wellbore_id": parentWellboreId,
"external_tag": "Tag_0"
};
let postUrl = "/public/api/msd/v2/wellbores";
const res = await post(postUrl, json);
return res.createdId ?? res.createdId
}
async function createSurvey(wellboreId) {
let json = {
"name": "parent survey",
"wellbore_id": wellboreId,
"survey_type": "NonDefinitiveSurvey",
"survey_date": "2025-11-01T15:30:00",
"north_reference": "Grid",
"depth_reference": 123.45,
"stations": [
{
"md": 0.00,
"incl": 0.00,
"azi": 0.00,
"tvd": 0.00,
"ns": 0.00,
"ew": 0.00,
"tool_code": "NAL_MWD_HDGM+SAG"
},
{
"md": 500,
"incl": 0.04,
"azi": 1.234,
"tvd": 123.45,
"ns": 0.00,
"ew": 0.12,
"tool_code": "NAL_MWD_HDGM+SAG"
}
],
"geomag_settings": {
"declination_date": "2025-12-01T15:30:00",
"geomagnetic_model": "HDGM 2019",
"field_strength": 0.000045869985760000006
"dip_angle": 0.9951268746938235,
"declination": 0.13838869228037218,
},
"hole_section": [
{
"name":"test"
"end_md": 123.45,
"hole_size": 5.00
"casing_size": 5.00
}
],
"external_tag":"test"
};
let postUrl = "/public/api/msd/v2/surveys";
const res = await post(postUrl, json);
return res.createdId ?? res.createdId
}async function createSidetrackSurvey(wellboreId, tieInSurveyId) {
let json = {
"name": "Test Survey",
"wellbore_id": wellboreId,
"survey_type": "NonDefinitiveSurvey",
"survey_date": "2025-11-30T02:58:10.577432Z",
"north_reference": "Grid",
"depth_reference": 1.23456,
"stations": [
{
"md": 0.00,
"incl": 0.00,
"azi": 0.0,
"tvd": 0.00,
"ns": 0.00,
"ew": 0.00,
"tool_code": "SLB_NSG+MSHOT"
},
{
"md": 200.24,
"incl": 0.123456,
"azi": 0.123456,
"tvd": 0.123456,
"ns": 0.123456,
"ew": 0.123456,
"tool_code": "SLB_NSG+MSHOT"
},
{
"md": 600.48,
"incl": 0.123456,
"azi": 0.123456,
"tvd": 0.123456,
"ns": 0.123456,
"ew": 0.123456,
"tool_code": "SLB_NSG+MSHOT"
}
],
"geomag_settings": {
"declination_date": "2025-11-01T02:58:10.577432Z", // Ensure this format is correct
"geomagnetic_model": "HDGM 2020",
"field_strength": 0.0000123456,
"dip_angle": 1.0000123456,
"declination": 0.0000123456
},
"tie_in": {
"tie_in_survey_id": tieInSurveyId,
"tie_in_md": 500
},
"hole_section": [
{
"name": "HoleSection 1",
"end_md": 1450.5,
"hole_size": 1.2,
"casing_size": 3.4
}
],
"external_tag": "tag 1"
};
let postUrl = "/public/api/msd/v2/surveys";
const res = await post(postUrl, json);
return res.createdId ?? res.createdId
}