- URL:https://<geometryservice-url>/findTransformations
- Related Resources:Project
- Version Introduced:10.3
Description
The findTransformations operation is performed on a geometry service resource. This operation returns a list of applicable geographic transformations you should use when projecting geometries from the input spatial reference to the output spatial reference. The transformations are in JSON format and are returned in order of most applicable to least applicable. Recall that a geographic transformation is not needed when the input and output spatial references have the same underlying geographic coordinate systems. In this case, findTransformations returns an empty list.
Every returned geographic transformation is a forward transformation, meaning that it can be used as is to project from the input spatial reference to the output spatial reference. When a predefined transformation needs to be applied in the reverse direction, it is returned as a forward composite transformation containing one transformation and a transformForward element with a value of false. See the examples given below.
You can provide arguments to the findTransformations operation as query parameters defined in the following parameters table.
Request parameters
| Parameter | Details |
|---|---|
| inSR (Required) | Specifies the well-known ID (WKID) of the spatial reference or a spatial reference JSON object for the input geometries. For a list of valid WKID values, see Using spatial references. |
| outSR (Required) | Specifies the WKID of the spatial reference or a spatial reference JSON object for the projected geometries. For a list of valid WKID values, see Using spatial references. |
| extentOfInterest (Optional) | Sets the bounding box of the area of interest specified as a JSON envelope. If provided, the extent of interest is used to return the most applicable geographic transformations for the area. If a spatial reference is not included in the JSON envelope, the inSR is used for the envelope. |
| numOfResults (Optional) | Specifies the number of geographic transformations to return. The default value is 1. If numOfResults has a value of -1, all applicable transformations are returned. |
| vertical (Optional) | Added at 10.5. Specifies whether or not to check for vertical transformations. The default value is false. If vertical is set to true, both inSR and outSR must have a vertical coordinate system. A list of hvtransforms will be returned in this case. Values: true | false |
| f | The response format. The default format is html. Values: html | json | pjson |
Example usage
The following are sample request URLs for findTransformations.
Example one
This example finds the top three transformations that should be used when projecting data from GCS_North_American_1927 (wkid = 4267) to GCS_WGS_1984 (wkid = 4326).
https://machine.domain.com/webadaptor/rest/services/Utilities/Geometry/GeometryServer/findTransformations?inSR=4267&outSR=4326&extentOfInterest=&numOfResults=3&f=pjsonThe first two transformations are forward single transformations. The third transformation is a forward composite transformation. It will first apply the transformation 108001 in the forward direction from NAD 27 to NAD 83, and it will then apply 108190 in the reverse direction from NAD 83 to WGS 84. Note that although the second transformation in the composite transformation is applied in the reverse direction, the entire composite transformation is a forward transformation. You could copy and paste the composite transformation, or any transformation returned by findTransformations, into the project operation as is without having to change the default direction, which is forward.
The output looks like the following:
[
{
"wkid": 15851,
"latestWkid": 15851,
"name": "NAD_1927_To_WGS_1984_79_CONUS"
},
{
"wkid": 8072,
"latestWkid": 1172,
"name": "NAD_1927_To_WGS_1984_3"
},
{
"geoTransforms": [
{
"wkid": 108001,
"latestWkid": 1241,
"transformForward": true,
"name": "NAD_1927_To_NAD_1983_NADCON"
},
{
"wkid": 108190,
"latestWkid": 108190,
"transformForward": false,
"name": "WGS_1984_(ITRF00)_To_NAD_1983"
}
]
}
]Example two
This example performs the reverse of the operation performed in example one. This example projects data from GCS_WGS_1984 (wkid = 4326) to GCS_North_American_1927 (wkid = 4267) and retrieves the top three transformations.
https://machine.domain.com/webadaptor/rest/services/Utilities/Geometry/GeometryServer/findTransformations?inSR=4326&outSR=4267&extentOfInterest=&numOfResults=3&f=pjsonNotice that the first two transformations are composite transformations containing a single transformation with the transformForward element set to false. The reason for this is that findTransformations always returns forward transformations. The transformation with wkid = 15851 is the best one for this situation, but if you use it directly, it must be used in the reverse direction. The composite transformation with one transformation is a forward transformation.
The output looks like the following:
[
{
"geoTransforms": [
{
"wkid": 15851,
"latestWkid": 15851,
"transformForward": false,
"name": "NAD_1927_To_WGS_1984_79_CONUS"
}
]
},
{
"geoTransforms": [
{
"wkid": 8072,
"latestWkid": 1172,
"transformForward": false,
"name": "NAD_1927_To_WGS_1984_3"
}
]
},
{
"geoTransforms": [
{
"wkid": 108190,
"latestWkid": 108190,
"transformForward": true,
"name": "WGS_1984_(ITRF00)_To_NAD_1983"
},
{
"wkid": 108001,
"latestWkid": 1241,
"transformForward": false,
"name": "NAD_1927_To_NAD_1983_NADCON"
}
]
}
]Example three
This example shows how to find the top two transformations for projecting data from North_America_Equidistant_Conic, a projected coordinate system with NAD 83 as its underlying geographic coordinate system, to World_Mercator, a projected coordinate system with WGS 84 as its underlying geographic coordinate system.
https://machine.domain.com/webadaptor/rest/services/Utilities/Geometry/GeometryServer/findTransformations?inSR=102010&outSR=54004&extentOfInterest=&numOfResults=2&f=pjsonThe output looks like the following:
[
{
"geoTransforms": [
{
"wkid": 108190,
"latestWkid": 108190,
"transformForward": false,
"name": "WGS_1984_(ITRF00)_To_NAD_1983"
}
]
},
{
"wkid": 8494,
"latestWkid": 1515,
"name": "NAD_1983_To_WGS_1984_5"
}
]To run the same query, but with an envelope covering an area in Southern California containing Esri headquarters, you would add the extentOfInterest parameter.
{
"xmin": -118,"ymin": 33,
"xmax": -116,"ymax": 35,
"spatialReference": {"wkid": 4326}
}With the extentOfInterest parameter added, the results consist of different transformations.
[
{
"geoTransforms": [
{
"wkid": 108190,
"latestWkid": 108190,
"transformForward": false,
"name": "WGS_1984_(ITRF00)_To_NAD_1983"
}
]
},
{
"geoTransforms": [
{
"wkid": 8422,
"latestWkid": 1477,
"transformForward": true,
"name": "NAD_1983_To_HARN_CA_S"
},
{
"wkid": 1900,
"latestWkid": 1900,
"transformForward": true,
"name": "NAD_1983_HARN_To_WGS_1984_2"
}
]
}
]
Example four
This example shows how to find the top horizontal or vertical transformation when projecting data from GCS_ETRS_1989 (WKID = 4258) and vertical coordinate system ETRS_1989 (WKID = 115701) to GCS_North_American_1983 (WKID = 4269) and vertical coordinate system NAD_1983 (WKID = 115702). Notice that since Vertical is set to true, the result is an array of hvTransforms rather than geoTransforms.
https://machine.domain.com/webadaptor/rest/services/Utilities/Geometry/GeometryServer/findTransformations?inSR={"wkid": 4258, "vcsWkid": 115701}&outSR={"wkid": 4269, "vcsWkid": 115702}&extentOfInterest=&numOfResults=&vertical=true&f=pjsonThe output looks like the following:
[
{
"hvTransforms": [
{
"wkid": 1149,
"latestWkid": 1149,
"transformForward": true,
"name": "ETRS_1989_To_WGS_1984"
},
{
"wkid": 8088,
"latestWkid": 1188,
"transformForward": false,
"name": "NAD_1983_To_WGS_1984_1"
}
]
}
]