Introduction

This service provides spatial reference conversions for coordinates. Coordinates are represented by an array of 3D points.

  "points": [
    {
      "x": -61.04340628871454,
      "y": 10.673103179456877,
      "z": 0
    },
    {
      "x": -62.28871454043406,
      "y": 11.794568776731031,
      "z": 0
    }
  ]

The context, which is the measurement and unit associated with the axes, is given by the CRS definition. In most of the cases, the CRS definition is 2D. In both the geographic and projected CRS types, the Z-axis is passed through unchanged, and its unit is only known to the client.

In addition to simple points as mentioned above, more complex geometry structures, such as GeoJSON, are supported by the service. GeoJSON only supports WGS 84, by definition. In order to enable spatial reference conversions, a similar structure has been created which uses the GeoJSON types prefixed by AnyCrs, such as AnyCrsFeatureCollection. AnyCrsFeatureCollection contains the CRS information and Z-unit as a persistable reference string.

Headers

*Header*	*Description*
data-partition-id (Required)	Specify the desired accessible partition ID. Only one data partition can be specified at a time.
correlation-id (Optional)	Used to track a single request throughout all the services it passes through. This can be a GUID in the header with a key. If you are the service initiating the request, you should generate the ID. Otherwise, you should just forward it on in the request.

The Data Platform stores data in different data partitions, depending on the access to those data partitions in the OSDU system.

Note: Viewer permission to the provided data-partition is required to use these APIs.

Latency, payload size

The CRS conversion and transformation service relies on the Esri projection engine to perform geo-spatial operations. There is considerable variability in response times depending on the kind of operation. The kind of operation is generally opaque to consumers. When transformations between different geographic CRSs are required and use large parameter files, such as the NTv2 method in Japan, Canada, and Australia, the response time can dramatically increase. Up to 90 seconds have been measured for transformations with the largest known parameter file (ESRI, 108109).

The second parameter that impacts the response time is the number of points in the request. Simple conversions with few points can have response times of about 0.5 seconds while 500000 points will require 180 to 200 seconds. The complex operations have response times of about 90 seconds for a few points to ~260 seconds for 500000 points.

This expected latency must be taken into account for the timeout definition and, more importantly, for the application design. Some conversions might be very slow.

To ensure proper scaling of the infrastructure, a best practice is to submit more requests with a smaller payload of ~5000-10000 points.

Axis definitions

Axis	CRS type	Measurement	Unit	Sign and directions
x	Geographic CRS	`Plane_Angle`	from CRS	positive values `E`, negative values `W` hemisphere
y	Geographic CRS	`Plane_Angle`	from CRS	positive values `N`, negative values `S` hemisphere
z	Geographic CRS	`Length`	pass-through	typically elevation relative to an implicit mean sea level surface
x	Projected CRS	`Length`	from CRS	direction given by the CRS
y	Projected CRS	`Length`	from CRS	direction given by the CRS
z	Projected CRS	`Length`	pass-through	typically elevation relative to an implicit mean sea evel surface

`convert` method

This method takes two CRS references (persistable references for example) that are exposed by the Spatial Reference Catalog and an array of points:

fromCRS: Persistable reference string for the CRS describing the context of the coordinates supplied in the request. This CRS controls the measurement and unit context of the axes - x, y, z. Details in Axis definitions.
toCRS: Persistable reference string for the target CRS, in which the response is expected. This toCRS controls the measurement and unit context of the axes - x, y, z. Details in Axis definitions.
points: The list of points (3D coordinates) to be converted/transformed.

Example point conversion

`convert` request

An example for a [ConvertPointsRequest](#ConvertPointsRequest):

{
  "fromCRS": "{\"lateBoundCRS\":{\"wkt\":\"GEOGCS[\\\"GCS_Provisional_S_American_1956\\\",DATUM[\\\"D_Provisional_S_American_1956\\\",SPHEROID[\\\"International_1924\\\",6378388.0,297.0]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433],AUTHORITY[\\\"EPSG\\\",4248]]\",\"ver\":\"PE_10_3_1\",\"name\":\"GCS_Provisional_S_American_1956\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"4248\"},\"type\":\"LBC\"},\"singleCT\":{\"wkt\":\"GEOGTRAN[\\\"PSAD_1956_To_WGS_1984_9\\\",GEOGCS[\\\"GCS_Provisional_S_American_1956\\\",DATUM[\\\"D_Provisional_S_American_1956\\\",SPHEROID[\\\"International_1924\\\",6378388.0,297.0]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433]],GEOGCS[\\\"GCS_WGS_1984\\\",DATUM[\\\"D_WGS_1984\\\",SPHEROID[\\\"WGS_1984\\\",6378137.0,298.257223563]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433]],METHOD[\\\"Geocentric_Translation\\\"],PARAMETER[\\\"X_Axis_Translation\\\",-295.0],PARAMETER[\\\"Y_Axis_Translation\\\",173.0],PARAMETER[\\\"Z_Axis_Translation\\\",-371.0],AUTHORITY[\\\"EPSG\\\",1209]]\",\"ver\":\"PE_10_3_1\",\"name\":\"PSAD_1956_To_WGS_1984_9\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"1209\"},\"type\":\"ST\"},\"ver\":\"PE_10_3_1\",\"name\":\"PSAD56 * DMA-Ven [4248,1209]\",\"authCode\":{\"auth\":\"OSDU\",\"code\":\"4248009\"},\"type\":\"EBC\"}",
  "toCRS": "{\"lateBoundCRS\":{\"wkt\":\"PROJCS[\\\"Trinidad_1903_Trinidad_Grid\\\",GEOGCS[\\\"GCS_Trinidad_1903\\\",DATUM[\\\"D_Trinidad_1903\\\",SPHEROID[\\\"Clarke_1858\\\",6378293.64520876,294.260676369]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433]],PROJECTION[\\\"Cassini\\\"],PARAMETER[\\\"False_Easting\\\",430000.0],PARAMETER[\\\"False_Northing\\\",325000.0],PARAMETER[\\\"Central_Meridian\\\",-61.3333333333333],PARAMETER[\\\"Scale_Factor\\\",1.0],PARAMETER[\\\"Latitude_Of_Origin\\\",10.4416666666667],UNIT[\\\"Link_Clarke\\\",0.201166195164],AUTHORITY[\\\"EPSG\\\",30200]]\",\"ver\":\"PE_10_3_1\",\"name\":\"Trinidad_1903_Trinidad_Grid\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"30200\"},\"type\":\"LBC\"},\"singleCT\":{\"wkt\":\"GEOGTRAN[\\\"Trinidad_1903_To_WGS_1984_2\\\",GEOGCS[\\\"GCS_Trinidad_1903\\\",DATUM[\\\"D_Trinidad_1903\\\",SPHEROID[\\\"Clarke_1858\\\",6378293.64520876,294.260676369]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433]],GEOGCS[\\\"GCS_WGS_1984\\\",DATUM[\\\"D_WGS_1984\\\",SPHEROID[\\\"WGS_1984\\\",6378137.0,298.257223563]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433]],METHOD[\\\"Geocentric_Translation\\\"],PARAMETER[\\\"X_Axis_Translation\\\",-61.0],PARAMETER[\\\"Y_Axis_Translation\\\",285.2],PARAMETER[\\\"Z_Axis_Translation\\\",471.6],AUTHORITY[\\\"EPSG\\\",10085]]\",\"ver\":\"PE_10_3_1\",\"name\":\"Trinidad_1903_To_WGS_1984_2\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"10085\"},\"type\":\"ST\"},\"ver\":\"PE_10_3_1\",\"name\":\"Trinidad 1903 * EOG-Tto Trin / Trinidad Grid [30200,10085]\",\"authCode\":{\"auth\":\"OSDU\",\"code\":\"30200002\"},\"type\":\"EBC\"}",
  "points": [
    {
      "x": -61.04340628871454,
      "y": 10.673103179456877,
      "z": 0
    },
    {
      "x": -62.28871454043406,
      "y": 11.794568776731031,
      "z": 0
    }
  ]
}

Name	Type	Description
fromCRS	str	Source CRS as persistable reference string
toCRS	str	Target CRS as persistable reference string
points	list[Point]	List of points to be converted

Name	Type	Description
successCount	int	Number of points successfully converted. If the number is less than the request array length, conversion/transformation failures occurred. Individual points, which failed to convert/transform, are represented as `"NaN"`.
points	list[Point]	Converted points; length and order of the array is the same as in the request. Points, which failed to convert, are returned as NaN.
operationsApplied	list[string]	The operations (conversions and/or transformation) applied to the points.

Name	Type	Description	Notes
featureCollection	AnyCrsGeoJsonFeatureCollection	The GeoJSON FeatureCollection or non-GeoJSON AnyCrsFeatureCollection to be converted. The fromCRS is either WGS 84 for GeoJSON or `AnyCrsFeatureCollection.persistableReference`.
toCRS	str	The GeoJSON FeatureCollection or AnyCrsFeatureCollection structure to be converted/transformed. GeoJSON is always based on WGS 84; AnyCrsFeatureCollection carries the CRS context in the persistableReferenceCrs property.
toUnitZ	str	The vertical axis unit for this AnyCrsGeoJsonFeatureCollection as a persistable reference string. Not required for 2D coordinates.	[optional]

Name	Type	Description
totalCount	int	The total number of coordinates in the GeoJSON FeatureCollection or AnyCrsFeatureCollection.
successCount	int	The number of coordinates in the GeoJSON FeatureCollection or AnyCrsFeatureCollection that were successfully converted/transformed. If this number is less than totalCount, then conversion/transformation errors have occurred. Unconverted coordinates are marked as `"NaN"`.
featureCollection	AnyCrsGeoJsonFeatureCollection
operationsApplied	list[str]	The list of operations, which have been applied to the points.

Name	Type	Description	Notes
type	str	Either `FeatureCollection` for standard GeoJSON or `AnyCrsFeatureCollection` for non-standard.	required
features	list[AnyCrsGeoJsonFeature]		required
bbox	list[double]	The rectangular bounding box. It has the same dimensions as coordinates: [west, south, east, north] or [west, south, min-elevation, east, north, max-elevation].	[optional]
persistableReferenceCrs	str	The spatial context of this AnyCrsGeoJsonFeatureCollection as persistable reference string.	[optional]
persistableReferenceUnitZ	str	The vertical axis unit for this AnyCrsGeoJsonFeatureCollection as persistable reference string.	[optional]

Name	Type	Description	Notes
type	str	Either `Feature` for standard GeoJSON or `AnyCrsFeature` for non-standard.	required
properties	AnyProperty		required
geometry	AnyCrsGeoJsonFeatureGeometry		required
bbox	list[double]	The rectangular bounding box. It has the same dimensions as coordinates: [west, south, east, north] or [west, south, min-elevation, east, north, max-elevation].	[optional]

Name	Type	Description	Notes
type	str	The geometry type enumeration. For GeoJSON standard the allowed values are: `"Point"`, `"LineString"`, `"Polygon"`, `"MultiPoint"`, `"MultiLineString"`, `"MultiPolygon"`, `"GeometryCollection"`. For non-standard AnyCrsFeature geometries, the allowed values are: `"AnyCrsPoint"`, `"AnyCrsLineString"`, `"AnyCrsPolygon"`, `"AnyCrsMultiPoint"`, `"AnyCrsMultiLineString"`, `"AnyCrsMultiPolygon"`, `"AnyCrsGeometryCollection"`.	required
coordinates	object	Depending on `type`, a 2D, 3D, or 4D array of 2D or 3D coordinate arrays.
bbox	list[double]	The rectangular bounding box. It has the same dimensions as coordinates: [west, south, east, north] or [west, south, min-elevation, east, north, max-elevation].	[optional]

Name	Type	Description
x	double	x coordinate or longitude
y	double	y coordinate or latitude
z	double	z coordinate

Name	Type	Description	Notes
trajectoryCrs	str	Coordinate reference system for the reference point. Typically the CRS is a projected CRS. If a geographic CRS is provided, the unitXY must be defined and the azimuthReference must be TrueNorth.
azimuthReference	str	Azimuth reference for the input trajectory station azimuth values (TrueNorth or GridNorth).
unitXY	str	The horizontal unit of the dx and dy in the input trajectory stations. The unit must be a length unit in 'persistable reference' format. See example.
unitZ	str	The vertical unit of the dz in the input trajectory stations. The unit must be a length unit in 'persistable reference' format. See example.
referencePoint	Point	The 3D reference point in the 'trajectoryCRS' where MD==0.
inputStations	list[TrajectoryStationIn]	The array of input trajectory stations.
method	str	The computation method: 'AzimuthalEquidistant' (default) or 'LMP' (Lee's modified proposal SPE96813).
interpolate	bool	Perform trajectory interpolation on demand. The default is true.	[optional]

Name	Type	Description
md	double	MD (measured depth) from vertical reference point in 'unitZ'.
inclination	double	Inclination angle in degrees of arc. 0.0 is vertical, 90.0 is horizontal.
azimuth	double	Azimuth angle in degrees of arc, 0.0/360.0 is North. Reference given by azimuthReference (TrueNorth or GridNorth).
dx	double	E-W deviation in the local Cartesian engineering CRS from the well reference point. The unit is given by container's 'unitXY' or projected 'trajectoryCRS'.
dy	double	N-S deviation in the local Cartesian engineering CRS from the well reference point. Y is aligned with the azimuth reference (TrueNorth or projected GridNorth). The unit is given by container's 'unitXY' or projected 'trajectoryCRS'.
dz	double	True vertical deviation in the local Cartesian engineering CRS from the well reference point. The unit is given by container's unitZ, downwards positive.

Name	Type	Description
md	double	MD (measured depth) from the vertical reference point in 'unitZ'.
inclination	double	Inclination angle in degrees of arc, 0.0 is vertical, 90.0 is horizontal.
azimuthTN	double	True north azimuth angle in degrees of arc, 0.0/360.0 is north.
azimuthGN	double	Grid north azimuth angle in degrees of arc, 0.0/360.0 is north.
dxTN	double	True E-W deviation in the local Cartesian engineering CRS from the well reference point. The unit is given by container's 'unitXY'.
dyTN	double	True N-S deviation in the local Cartesian engineering CRS from the well reference point. Y is aligned with TrueNorth. The unit is given by container's 'unitXY'.
point	Point	Trajectory station point in trajectoryCRS and vertical unit as defined in container's 'unitZ'. `point.z` is an elevation, positive upwards. `-point.z` corresponds to TVDSS (true vertical depth sub-sea).
wgs84Longitude	double	WGS 84 longitude in dega.
wgs84Latitude	double	WGS 84 latitude in dega.
dls	double	Curvature, Dog Leg Severity, measured in 'unitDls'.
original	bool	Original trajectory station if true, interpolated trajectory station if false.
dz	double	The relative true vertical depth measured from the reference point, downwards positively increasing. Also known as TVD (true vertical depth)

Table of contents

Introduction

Headers

Latency, payload size

Axis definitions

convert method

Example point conversion

convert request

convert response

What actually happened?

Are two CRSs equivalent?

Failures and partial failures

Other failures

convertGeoJson method

Example GeoJSON Conversion

convertGeoJson request

convertGeoJson response

Request and response data structures

ConvertPointsRequest

Properties

ConvertPointsResponse

Properties

ConvertGeoJsonRequest

Properties

ConvertGeoJsonResponse

Properties

AnyCrsGeoJsonFeatureCollection

Properties

AnyCrsGeoJsonFeature

Properties

AnyCrsGeoJsonFeatureGeometry

Properties

Point

Properties

Trajectory conversions

convertTrajectory method

Request and response trajectory data structures

ConvertTrajectoryRequest

Properties

TrajectoryStationIn

Properties

ConvertTrajectoryResponse

Properties

TrajectoryStationOut

Properties

Known issues

Was this helpful?

`convert` method

`convert` request

`convert` response

`convertGeoJson` method

`convertGeoJson` request

`convertGeoJson` response

`convertTrajectory` method