For all the existing records in the Data Platform, we need a way for the user to retrieve the data so that it is rationalized to a common standard that allows for comparison from multiple data sources. For this, we currently support a few ways of supplying the frame of reference (FoR). The FoR provides the context in which the numbers are interpreted. With the FoR properly supplied, we can then use the FoR to convert to a standard format, which is units in SI, CRS in wgs84, elevation in msl, azimuth in true north, and dates in utc.
Data records in the Data Platform collect their FoR in the meta section. It contains the full, self-contained description of Units, Measurements and Coordinate Reference Systems, and DateTimes used in the record/document. We currently support conversion for only units, CRS, and datetime. In addition, only single coordinates are supported, and the coordinate property names must follow a specific naming convention, as explained in the Scenarios we support section.
The meta section is an array of elements that collects FoR information in records. The arrayed elements are called meta items.
A meta item is a member of a record's meta section and includes following properties:
- kind: Represents a string(enumeration) that identifies the kind of reference. Currently we only support the conversion for kind "DateTime", "Unit", and "CRS".
- name: Represents a string that contains a human-readable name/symbol for the reference.
- persistableReference: Represents a string that contains the self-contained description of the datetime, unit, or CRS.
- propertyNames: Represents an array of strings. The elements are property names, for which the reference is fixed.
- The CRS Catalog service and Unit service are suppliers of persistableReference strings.
CRS example persistable reference strings
A non-trivial projected CRS:
"name": "NAD27 * OGP-Usa Conus / Louisiana South [26782,15851]"
"persistableReference": "{\"lateBoundCRS\":{\"wkt\":\"PROJCS[\\\"NAD_1927_StatePlane_Louisiana_South_FIPS_1702\\\",GEOGCS[\\\"GCS_North_American_1927\\\",DATUM[\\\"D_North_American_1927\\\",SPHEROID[\\\"Clarke_1866\\\",6378206.4,294.9786982]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433]],PROJECTION[\\\"Lambert_Conformal_Conic\\\"],PARAMETER[\\\"False_Easting\\\",2000000.0],PARAMETER[\\\"False_Northing\\\",0.0],PARAMETER[\\\"Central_Meridian\\\",-91.3333333333333],PARAMETER[\\\"Standard_Parallel_1\\\",29.3],PARAMETER[\\\"Standard_Parallel_2\\\",30.7],PARAMETER[\\\"Latitude_Of_Origin\\\",28.6666666666667],UNIT[\\\"Foot_US\\\",0.304800609601219],AUTHORITY[\\\"EPSG\\\",26782]]\",\"ver\":\"PE_10_3_1\",\"name\":\"NAD_1927_StatePlane_Louisiana_South_FIPS_1702\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"26782\"},\"type\":\"LBC\"},\"singleCT\":{\"wkt\":\"GEOGTRAN[\\\"NAD_1927_To_WGS_1984_79_CONUS\\\",GEOGCS[\\\"GCS_North_American_1927\\\",DATUM[\\\"D_North_American_1927\\\",SPHEROID[\\\"Clarke_1866\\\",6378206.4,294.9786982]],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[\\\"NADCON\\\"],PARAMETER[\\\"Dataset_conus\\\",0.0],AUTHORITY[\\\"EPSG\\\",15851]]\",\"ver\":\"PE_10_3_1\",\"name\":\"NAD_1927_To_WGS_1984_79_CONUS\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"15851\"},\"type\":\"ST\"},\"ver\":\"PE_10_3_1\",\"name\":\"NAD27 * OGP-Usa Conus / Louisiana South [26782,15851]\",\"authCode\":{\"auth\":\"SLB\",\"code\":\"26782079\"},\"type\":\"EBC\"}"A simple UTM projection
"name": "WGS_1984_UTM_Zone_31N"
"persistableReference": "{\"wkt\":\"PROJCS[\\\"WGS_1984_UTM_Zone_31N\\\",GEOGCS[\\\"GCS_WGS_1984\\\",DATUM[\\\"D_WGS_1984\\\",SPHEROID[\\\"WGS_1984\\\",6378137.0,298.257223563]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433]],PROJECTION[\\\"Transverse_Mercator\\\"],PARAMETER[\\\"False_Easting\\\",500000.0],PARAMETER[\\\"False_Northing\\\",0.0],PARAMETER[\\\"Central_Meridian\\\",3.0],PARAMETER[\\\"Scale_Factor\\\",0.9996],PARAMETER[\\\"Latitude_Of_Origin\\\",0.0],UNIT[\\\"Meter\\\",1.0],AUTHORITY[\\\"EPSG\\\",32631]]\",\"ver\":\"PE_10_3_1\",\"name\":\"WGS_1984_UTM_Zone_31N\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"32631\"},\"type\":\"LBC\"}"A geographic CRS
"name": "NAD27 * OGP-Usa Conus [4267,15851]"
"persistableReference": "{\"lateBoundCRS\":{\"wkt\":\"GEOGCS[\\\"GCS_North_American_1927\\\",DATUM[\\\"D_North_American_1927\\\",SPHEROID[\\\"Clarke_1866\\\",6378206.4,294.9786982]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433],AUTHORITY[\\\"EPSG\\\",4267]]\",\"ver\":\"PE_10_3_1\",\"name\":\"GCS_North_American_1927\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"4267\"},\"type\":\"LBC\"},\"singleCT\":{\"wkt\":\"GEOGTRAN[\\\"NAD_1927_To_WGS_1984_79_CONUS\\\",GEOGCS[\\\"GCS_North_American_1927\\\",DATUM[\\\"D_North_American_1927\\\",SPHEROID[\\\"Clarke_1866\\\",6378206.4,294.9786982]],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[\\\"NADCON\\\"],PARAMETER[\\\"Dataset_conus\\\",0.0],AUTHORITY[\\\"EPSG\\\",15851]]\",\"ver\":\"PE_10_3_1\",\"name\":\"NAD_1927_To_WGS_1984_79_CONUS\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"15851\"},\"type\":\"ST\"},\"ver\":\"PE_10_3_1\",\"name\":\"NAD27 * OGP-Usa Conus [4267,15851]\",\"authCode\":{\"auth\":\"SLB\",\"code\":\"4267079\"},\"type\":\"EBC\"}"WGS84
"name": "GCS_WGS_1984"
"persistableReference": "{\"wkt\":\"GEOGCS[\\\"GCS_WGS_1984\\\",DATUM[\\\"D_WGS_1984\\\",SPHEROID[\\\"WGS_1984\\\",6378137.0,298.257223563]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433],AUTHORITY[\\\"EPSG\\\",4326]]\",\"ver\":\"PE_10_3_1\",\"name\":\"GCS_WGS_1984\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"4326\"},\"type\":\"LBC\"}"Unit examples with persistable reference strings
"name": "ftUS"
"persistableReference": "{\"scaleOffset\":{\"scale\":0.3048006096012192,\"offset\":0.0},\"symbol\":\"ftUS\",\"baseMeasurement\":{\"ancestry\":\"Length\",\"type\":\"UM\"},\"type\":\"USO\"}"
"name": "ft"
"persistableReference": "{\"scaleOffset\":{\"scale\":0.3048,\"offset\":0.0},\"symbol\":\"ft\",\"baseMeasurement\":{\"ancestry\":\"Length\",\"type\":\"UM\"},\"type\":\"USO\"}"
"name": "dega"
"persistableReference": "{\"abcd\":{\"a\":0.0,\"b\":3.141592653589793,\"c\":180.0,\"d\":0.0},\"symbol\":\"dega\",\"baseMeasurement\":{\"ancestry\":\"A\",\"type\":\"UM\"},\"type\":\"UAD\"}"
"name": "m"
"persistableReference": "{\"scaleOffset\":{\"scale\":1.0,\"offset\":0.0},\"symbol\":\"m\",\"baseMeasurement\":{\"ancestry\":\"Length\",\"type\":\"UM\"},\"type\":\"USO\"}"DateTime example persistable reference strings
"name": "Date"
{"persistableReference": "{\"type\": \"DAT\", \"format\": \"MM/dd/yyyy\"}"
"name": "DateTime"
{"persistableReference": "{\"type\": \"DTM\", \"format\": \"MM/dd/yyyy HH:mm:ss\", \"timeZone\": \"UTC\"}"
"name": "DateTime"
{"persistableReference": "{\"type\": \"DTM\", \"format\": \"MM/dd/yyyy HH:mm:ss\", \"timeZone\": \"GMT+05:30\"}"The following are some examples of meta items. Note: "persistable reference String" is not a valid value for a persistable reference and is only used for demonstration purposes.
- Everything is properly provided, but you need a further check on the data values to apply the conversion:
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"X",
"Y",
"Z"
],
"name": "GCS_WGS_1984"
}- Missing value for kind, no conversion could be applied:
{
"kind": "",
"persistableReference": "persistable reference String",
"propertyNames": [
"X",
"Y",
"Z"
],
"name": "GCS_WGS_1984"
}- Missing value for persistable reference, no conversion could be applied:
{
"kind": "CRS",
"persistableReference": "",
"propertyNames": [
"X",
"Y",
"Z"
],
"name": "GCS_WGS_1984"
}- Missing value for property names, no conversion could be applied:
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [],
"name": "GCS_WGS_1984"
}In one of our storage APIs, which is introduced later in this documentation, we get a meta section of records, extract FoR information and properties that need to be converted, do the conversion, and put the converted value back into record.
As mentioned in the Introduction section, we need a way for the user to retrieve the data so that it is rationalized to a common standard that allows for comparison from multiple data sources. We have an API in the Storage service that can fetch multiple records at once, and it allows you to request that data be converted to a common standard by using a custom header {frame-of-reference}.
This API can fetch at most 20 records at once, and if conversion is requested by the user, the meta section of each record is checked. Then each meta item in the meta section is looped over to get the information of its kind, property names, and persistableReference. If any errors occur during the conversion, detailed error messages are noted and returned to the user, along with the records the user requested.
There are 5 types of attributes included in the common standard: Unit, CRS, DateTime, Elevation, and Azimuth. We only support conversion for Unit, CRS, and DateTime.
If the record itself is missing anything necessary for the conversion, for example the "kind" field in the meta item or missing the properties which are listed in the meta item, we provide explicit error messages indicating which items are missing and what the result is (in these cases, no conversion applied) back to the user. Although data quality itself is out of this API's scope, using explicit error messages lets the data owner know what needs to be fixed before their data can be successfully converted.
To use this API, users must specify the {data-partition-id} and {frame-of-reference} in the header. Currently only "none" and "units=SI;crs=wgs84;elevation=msl;azimuth=true north;dates=utc;" are valid values for the header {frame-of-reference}.
In the request body, users should additionally provide no more than 20 record IDs to fetch the record with or without the conversion.
The returned records could either be with the original value or the converted(units=SI;crs=wgs84) value, depending on user's request and the conversion status. The original value is returned when users do not request the conversion or when the conversion is requested, but fails. In addition to the records the user requests, if conversion is requested, a general conversion status and a list of detailed conversion informational error messages for each record is included in the response, indicating whether the conversion was successful or not, and if not, what errors occured.
There are three different general conversion statuses: SUCCESS, ERROR, and NO_FRAME_OF_REFERENCE:
- SUCCESS indicates the normalization of the whole record is successful without any errors.
- ERROR indicates that at least one error occured during normalization and a detailed error message is provided in the response.
- NO_FRAME_OF_REFERENCE indicates that no meta block was provided in the record, and thus no normalization can be applied. Sometimes information messages are even when the general status is SUCCESS. When this happens, it means there are some issues with the data, but the issues did not affect the conversion of other properties listed in the meta block. For example:
- For unit normalization: When an empty property is found during unit conversion, we will skip that empty property and continue the conversion for rest of properties.
- For CRS normalization: When two pairs of coordinates and a separate coordinate are provided, the separate one is filtered out and listed in the message, but normalization for the other two pairs of coordinates are applied.
The following is a curl command to call the API together with the response example.
POST /api/storage/v2/query/records:batchcurl
curl --request POST \
--url '/api/storage/v2/query/records:batch' \
--header 'Authorization: Bearer <JWT>' \
--header 'Content-Type: application/json' \
--header 'data-partition-id: opendes' \
--header 'frame-of-reference: units=SI;crs=wgs84;elevation=msl;azimuth=true north;dates=utc;' \
--data '{
"records": [
"opendes:test:fetchtest-1",
"opendes:test:fetchtest-2",
"opendes:test:fetchtest-4",
"opendes:test:fetchtest-5",
"opendes:test:fetchtest-6"
]
}response example
{
"records": [
{
"data": {
"msg": "testing record 2 for new fetch api",
"X": -61.04340628871454,
"Y": 10.673103179456877,
"Z": 0
},
"id": "opendes:test:fetchtest-2",
"version": 1558382737285141,
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"createUser": "test@{datapartition}.{domain}.com",
"createTime": "2019-05-20T15:06:28.002Z",
"modifyUser": "test@{datapartition}.{domain}.com",
"modifyTime": "2019-05-20T20:05:37.285Z"
},
{
"data": {
"msg": "testing record 5 for new fetch api",
"LON": -7.558014421269646,
"LAT": 49.766862184738834,
"Z": 0
},
"meta": [
{
"path": "",
"kind": "CRS",
"propertyNames": [
"LAT",
"LON",
"Z"
],
"name": "GCS_WGS_1984",
"persistableReference": "{\"wkt\":\"GEOGCS[\\\"GCS_WGS_1984\\\",DATUM[\\\"D_WGS_1984\\\",SPHEROID[\\\"WGS_1984\\\",6378137.0,298.257223563]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433],AUTHORITY[\\\"EPSG\\\",4326]]\",\"ver\":\"PE_10_3_1\",\"name\":\"GCS_WGS_1984\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"4326\"},\"type\":\"LBC\"}"
}
],
"id": "opendes:test:fetchtest-5",
"version": 1559084171227774,
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"createUser": "test@{datapartition}.{domain}.com",
"createTime": "2019-05-28T22:53:06.631Z",
"modifyUser": "test@{datapartition}.{domain}.com",
"modifyTime": "2019-05-28T22:56:11.227Z"
},
{
"data": {
"msg": "testing record 6 for new fetch api",
"projectOutlineLocalGeographic": {
"crsKey": "naive",
"points": [
[
-7.557196470516528,
49.76735555937625,
0
],
[
-7.557196715365543,
49.76735700183289,
0
],
[
-7.557189502300175,
49.767357378586794,
0
]
]
}
},
"meta": [
{
"path": "",
"kind": "CRS",
"propertyNames": [
"projectOutlineLocalGeographic"
],
"name": "GCS_WGS_1984",
"persistableReference": "{\"wkt\":\"GEOGCS[\\\"GCS_WGS_1984\\\",DATUM[\\\"D_WGS_1984\\\",SPHEROID[\\\"WGS_1984\\\",6378137.0,298.257223563]],PRIMEM[\\\"Greenwich\\\",0.0],UNIT[\\\"Degree\\\",0.0174532925199433],AUTHORITY[\\\"EPSG\\\",4326]]\",\"ver\":\"PE_10_3_1\",\"name\":\"GCS_WGS_1984\",\"authCode\":{\"auth\":\"EPSG\",\"code\":\"4326\"},\"type\":\"LBC\"}"
}
],
"id": "opendes:test:fetchtest-6",
"version": 1559169545810287,
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"createUser": "test@{datapartition}.{domain}.com",
"createTime": "2019-05-29T22:39:05.810Z"
},
{
"data": {
"msg": "testing record 4 for new fetch api",
"Y": 5.673103179456877,
"Z": 0
},
"meta": [
{
"path": "",
"kind": "CRS",
"persistableReference": "%7B%22LB_CRS%22%3A%22%257B%2522WKT%2522%253A%2522PROJCS%255B%255C%2522British_National_Grid%255C%2522%252CGEOGCS%255B%255C%2522GCS_OSGB_1936%255C%2522%252CDATUM%255B%255C%2522D_OSGB_1936%255C%2522%252CSPHEROID%255B%255C%2522Airy_1830%255C%2522%252C6377563.396%252C299.3249646%255D%255D%252CPRIMEM%255B%255C%2522Greenwich%255C%2522%252C0.0%255D%252CUNIT%255B%255C%2522Degree%255C%2522%252C0.0174532925199433%255D%255D%252CPROJECTION%255B%255C%2522Transverse_Mercator%255C%2522%255D%252CPARAMETER%255B%255C%2522False_Easting%255C%2522%252C400000.0%255D%252CPARAMETER%255B%255C%2522False_Northing%255C%2522%252C-100000.0%255D%252CPARAMETER%255B%255C%2522Central_Meridian%255C%2522%252C-2.0%255D%252CPARAMETER%255B%255C%2522Scale_Factor%255C%2522%252C0.9996012717%255D%252CPARAMETER%255B%255C%2522Latitude_Of_Origin%255C%2522%252C49.0%255D%252CUNIT%255B%255C%2522Meter%255C%2522%252C1.0%255D%252CAUTHORITY%255B%255C%2522EPSG%255C%2522%252C27700%255D%255D%2522%252C%2522Type%2522%253A%2522LBCRS%2522%252C%2522EngineVersion%2522%253A%2522PE_10_3_1%2522%252C%2522AuthorityCode%2522%253A%257B%2522Authority%2522%253A%2522EPSG%2522%252C%2522Code%2522%253A%252227700%2522%257D%252C%2522Name%2522%253A%2522British_National_Grid%2522%257D%22%2C%22TRF%22%3A%22%257B%2522WKT%2522%253A%2522GEOGTRAN%255B%255C%2522OSGB_1936_To_WGS_1984_Petroleum%255C%2522%252CGEOGCS%255B%255C%2522GCS_OSGB_1936%255C%2522%252CDATUM%255B%255C%2522D_OSGB_1936%255C%2522%252CSPHEROID%255B%255C%2522Airy_1830%255C%2522%252C6377563.396%252C299.3249646%255D%255D%252CPRIMEM%255B%255C%2522Greenwich%255C%2522%252C0.0%255D%252CUNIT%255B%255C%2522Degree%255C%2522%252C0.0174532925199433%255D%255D%252CGEOGCS%255B%255C%2522GCS_WGS_1984%255C%2522%252CDATUM%255B%255C%2522D_WGS_1984%255C%2522%252CSPHEROID%255B%255C%2522WGS_1984%255C%2522%252C6378137.0%252C298.257223563%255D%255D%252CPRIMEM%255B%255C%2522Greenwich%255C%2522%252C0.0%255D%252CUNIT%255B%255C%2522Degree%255C%2522%252C0.0174532925199433%255D%255D%252CMETHOD%255B%255C%2522Position_Vector%255C%2522%255D%252CPARAMETER%255B%255C%2522X_Axis_Translation%255C%2522%252C446.448%255D%252CPARAMETER%255B%255C%2522Y_Axis_Translation%255C%2522%252C-125.157%255D%252CPARAMETER%255B%255C%2522Z_Axis_Translation%255C%2522%252C542.06%255D%252CPARAMETER%255B%255C%2522X_Axis_Rotation%255C%2522%252C0.15%255D%252CPARAMETER%255B%255C%2522Y_Axis_Rotation%255C%2522%252C0.247%255D%252CPARAMETER%255B%255C%2522Z_Axis_Rotation%255C%2522%252C0.842%255D%252CPARAMETER%255B%255C%2522Scale_Difference%255C%2522%252C-20.489%255D%252CAUTHORITY%255B%255C%2522EPSG%255C%2522%252C1314%255D%255D%2522%252C%2522Type%2522%253A%2522STRF%2522%252C%2522EngineVersion%2522%253A%2522PE_10_3_1%2522%252C%2522AuthorityCode%2522%253A%257B%2522Authority%2522%253A%2522EPSG%2522%252C%2522Code%2522%253A%25221314%2522%257D%252C%2522Name%2522%253A%2522OSGB_1936_To_WGS_1984_Petroleum%2522%257D%22%2C%22Type%22%3A%22EBCRS%22%2C%22EngineVersion%22%3A%22PE_10_3_1%22%2C%22Name%22%3A%22OSGB+1936+*+UKOOA-Pet+%2F+British+National+Grid+%5B27700%2C1314%5D%22%2C%22AuthorityCode%22%3A%7B%22Authority%22%3A%22SLB%22%2C%22Code%22%3A%2227700006%22%7D%7D",
"propertyNames": [
"X",
"Y",
"Z"
],
"name": "GCS_WGS_1984"
}
],
"id": "opendes:test:fetchtest-4",
"version": 1558371879388837,
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
],
"status": "compliant"
},
"createUser": "test@{datapartition}.{domain}.com",
"createTime": "2019-05-20T17:04:39.388Z"
}
],
"notFound": [
"opendes:test:fetchtest-1"
],
"conversionStatuses": [
{
"id": "opendes:test:fetchtest-2",
"status": "NO_FRAME_OF_REFERENCE",
"errors": [
"No Meta Block in This Record."
]
},
{
"id": "opendes:test:fetchtest-5",
"status": "SUCCESS",
"errors": [
"CRS conversion: Unknown coordinate pair 'z'."
]
},
{
"id": "opendes:test:fetchtest-6",
"status": "SUCCESS",
"errors": []
},
{
"id": "opendes:test:fetchtest-4",
"status": "ERROR",
"errors": [
"CRS conversion: property 'X' is missing in datablock, no conversion applied to this property and its corresponding pairing property.",
"CRS conversion: Unknown coordinate pair 'z'."
]
}
]
}The following are some examples that you can refer to when using this API.
- Data all good, conversion applied, converted value would replace the original value, no error message in this case, and general status: SUCCESS.
Original record:
{
"id": "opendes:test:fetchtest-1",
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
]
},
"data": {
"msg": "testing record 1 for new fetch api",
"X": -61.04340628871454,
"Y": 10.673103179456877,
"Z": 0
},
"meta": [
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"X",
"Y",
"Z"
],
"name": "GCS_WGS_1984"
}
]
}Original record for a homogeneous case: [Update specified fields for all the items in the nested array]
{
"id": "opendes:test:fetchtest-1",
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
]
},
"data": {
"msg": "testing record 1 for new fetch api",
"Markers": [{
"MarkerName": "Marker 1",
"MarkerMeasuredDepth": 3280.839895013123,
"MarkerDate": "2020-02-13T09:13:15.55Z",
"FeatureTypeID": "partition-id:reference-data--FeatureType:Top:",
"PositiveVerticalDelta": 328.0839895013123,
"NegativeVerticalDelta": 0,
"SurfaceDipAngle": 15.729577951308233,
"SurfaceDipAzimuth": 271.88733853924697
},
{
"MarkerName": "Marker 2",
"MarkerMeasuredDepth": 2187.2265966754153,
"FeatureTypeID": "partition-id:reference-data--FeatureType:Top:",
"PositiveVerticalDelta": 0,
"NegativeVerticalDelta": 328.0839895013123,
"SurfaceDipAngle": 16.302535746439055,
"SurfaceDipAzimuth": 184.59155902616465
},
{
"MarkerName": "Marker 3",
"MarkerMeasuredDepth": 9842.51968503937,
"FeatureTypeID": "partition-id:reference-data--FeatureType:Top:",
"PositiveVerticalDelta": 328.0839895013123,
"NegativeVerticalDelta": 0,
"SurfaceDipAngle": 9.875493541569878,
"SurfaceDipAzimuth": 157.29577951308232
}
]
},
"meta": [
{
"kind": "Unit",
"name": "dega",
"persistableReference": "persistable reference String",
"unitOfMeasureID": "unit of measure id String",
"propertyNames": [
"Markers[].SurfaceDipAngle",
"Markers[].SurfaceDipAzimuth"
]
}
]
}Original record for an inhomogeneous case: [Update specified fields for specifying the items in the nested array]
{
"id": "opendes:test:fetchtest-1",
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
]
},
"data": {
"msg": "testing record 1 for new fetch api",
"Markers": [{
"MarkerName": "Marker 1",
"MarkerMeasuredDepth": 3280.839895013123,
"MarkerDate": "2020-02-13T09:13:15.55Z",
"FeatureTypeID": "partition-id:reference-data--FeatureType:Top:",
"PositiveVerticalDelta": 328.0839895013123,
"NegativeVerticalDelta": 0,
"SurfaceDipAngle": 15.729577951308233,
"SurfaceDipAzimuth": 271.88733853924697
},
{
"MarkerName": "Marker 2",
"MarkerMeasuredDepth": 2187.2265966754153,
"FeatureTypeID": "partition-id:reference-data--FeatureType:Top:",
"PositiveVerticalDelta": 0,
"NegativeVerticalDelta": 328.0839895013123,
"SurfaceDipAngle": 16.302535746439055,
"SurfaceDipAzimuth": 184.59155902616465
},
{
"MarkerName": "Marker 3",
"MarkerMeasuredDepth": 9842.51968503937,
"FeatureTypeID": "partition-id:reference-data--FeatureType:Top:",
"PositiveVerticalDelta": 328.0839895013123,
"NegativeVerticalDelta": 0,
"SurfaceDipAngle": 9.875493541569878,
"SurfaceDipAzimuth": 157.29577951308232
}
]
},
"meta": [
{
"kind": "Unit",
"name": "dega",
"persistableReference": "persistable reference String",
"unitOfMeasureID": "unit of measure id String",
"propertyNames": [
"Markers[1].SurfaceDipAngle",
"Markers[2].SurfaceDipAzimuth"
]
}
]
}- Missing meta block in the record: If this record is requested, the original record would be returned together with an error message indicating that the meta block is missing in the record. General status: NO_FRAME_OF_REFERENCE.
Original record:
{
"id": "opendes:test:fetchtest-1",
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
]
},
"data": {
"msg": "testing record 1 for new fetch api",
"X": -61.04340628871454,
"Y": 10.673103179456877,
"Z": 0
}
}- The meta item is invalid, in this case, missing "kind" in meta item, as described in Meta item examples. The original record is returned with an error message that indicates something is invalid in the meta item. General status: ERROR.
Original record:
{
"id": "opendes:test:fetchtest-1",
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
]
},
"data": {
"msg": "testing record 1 for new fetch api",
"X": -61.04340628871454,
"Y": 10.673103179456877,
"Z": 0
},
"meta": [
{
"kind": "",
"persistableReference": "persistable reference String",
"propertyNames": [
"X",
"Y",
"Z"
],
"name": "GCS_WGS_1984"
}
]
}- Missing data in a data block, in this case, missing property Y: If the properties listed in the meta item do not exist in the data block of this record, the original record is returned with an error message indicating data is missing from the data block. General status: ERROR.
Original record:
{
"id": "opendes:test:fetchtest-1",
"kind": "opendes:test:fetchtest:1.0.0",
"acl": {
"viewers": [
"data.default.viewers@{datapartition}.{domain}.com"
],
"owners": [
"data.default.owners@{datapartition}.{domain}.com"
]
},
"legal": {
"legaltags": [
"common-test-fetchtest-1"
],
"otherRelevantDataCountries": [
"US"
]
},
"data": {
"msg": "testing record 1 for new fetch api",
"X": -61.04340628871454,
"Z": 0
},
"meta": [
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"X",
"Y",
"Z"
],
"name": "GCS_WGS_1984"
}
]
}There will be other errors that occur with real data. For example, the data value should be of type double, but if it shows up as a string, the value of the persistable reference is incorrect, etc. A detailed error message is included in the response body so that users can determine why conversion cannot be applied and what to do to fix the data with data owners.
- Scenarios we support for CRS:
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"X",
"Y",
"Z"
],
"name": "NAD27 * OGP-Usa Conus / Louisiana South [26782,15851]"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"X",
"Y"
],
"name": "NAD27 * OGP-Usa Conus / Louisiana South [26782,15851]"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"LAT",
"LON"
],
"name": "NAD27 * OGP-Usa Conus [4267,15851]"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"Longitude",
"Latitude"
],
"name": "NAD27 * OGP-Usa Conus [4267,15851]"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"wlbEwUtm",
"wlbNsUtm"
],
"name": "WGS_1984_UTM_Zone_31N"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"wlbEwDesDeg",
"wlbNsDecDeg"
],
"name": "GCS_WGS_1984"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"TOPHOLEXNG",
"TOPHOLEYNG"
],
"name": "GCS_WGS_1984"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"TOPHOLEXDD",
"TOPHOLEYDD"
],
"name": "GCS_WGS_1984"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"BHLongitude",
"BHLatitude"
],
"name": "GCS_WGS_1984"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"NativeGeographicCrs"
],
"name": "NAD27 * OGP-Usa Conus [4267,15851]"
}
{
"kind": "CRS",
"persistableReference": "persistable reference String",
"propertyNames": [
"NativeProjectedCrs"
],
"name": "NAD27 * OGP-Usa Conus / Louisiana South [26782,15851]"
}- Scenarios we support for DateTime:
{
"kind": "DateTime",
"persistableReference": "{\"type\": \"DAT\", \"format\": \"MM/dd/yyyy\"}",
"propertyNames": [
"creationDate"
]
}
{
"kind": "DateTime",
"persistableReference": "{\"type\": \"DTM\", \"format\": \"MM/dd/yyyy HH:mm:ss\", \"timeZone\": \"UTC\"}",
"propertyNames": [
"creationDate"
]
}Users can find supported DateTime formats in the Supported DateTime formats section and supported time zones in the Supported DateTime time zones section.
Error messages are made up of three parts:
- The part of the conversion that is producing the error: CRS conversion, Unit conversion, or DateTime conversion.
- The exact reason why the error occured: The most likely reason is that one or more values are missing or invalid.
- The result of this error: No conversion occurs at this time.
| Error message contents | When and why it occurs |
|---|---|
| CRS/Unit/DateTime Conversion: DataBlock is missing or empty in this record, no conversion applied. | The record is missing its data part, so we cannot get any data from the record. |
| CRS/Unit/DateTime conversion: Required property 'kind' in meta block is missing or empty, no conversion applied. | The ‘kind’ field in the meta item is missing. This usually points out the type of the conversion: CRS/Unit/DateTime. |
| CRS/Unit/DateTime conversion: 'propertyNames' in the meta block is missing or empty, no conversion applied. | The ‘propertyNames’ field in the meta item is missing. Usually it lists all of the properties that share the same persistableReference in the data block. Without this, we do not know which data properties to convert. |
| CRS conversion: Inappropriate number of properties for point conversion, unsupported property set, no conversion applied. | For CRS conversion, we need exactly one nested data property, which contains a list of points or 2-3 properties (lon, lat, elevation) to construct the structure called "Point" which is needed for CRS conversion. If more than 3 properties are listed in the ‘propertyNames’ field, we cannot support the CRS conversion because we cannot determine the mapping between those four or more properties with lon, lat, and elevation in Point. |
| CRS/Unit/DateTime conversion: 'propertyNames' illegal, no conversion applied. | This error indicates a bad format in the ‘propertyNames’ field of the record. The ‘propertyNames’ field must be a JsonArray, otherwise the IllegalStateException error occurs when we try to get it from the record itself. |
| CRS/Unit/DateTime conversion: 'persistableReference' missing, no conversion applied. | The ‘persistableReference’ field in the meta item is missing. Without this field, no conversion can be applied. |
| CRS/Unit/DateTime conversion: The '%s' property is missing in the datablock, no conversion applied. | For CRS conversion, no property listed in the ‘propertyNames’ field in the meta item can be empty or non-existant in the data block of the record. These values are required to construct the structure Point which is needed for CRS conversion. Any missing or empty values will cause this error. |
| CRS/Unit/DateTime conversion: Cannot cast the value of the '%s' property to double, error message: %s, no conversion applied. | Usually, properties listed for CRS/Unit conversion are of type double. If the value is not of type double, a ClassCastException error occurs. The error message contains the property’s name along with the error message from the exception so that users understand which property must be fixed before conversion can occur. |
| CRS/Unit conversion: Illegal value for the '%s' property, error message: %s, no conversion applied. | When the value of the property is not of type double, such as when it's of type String, a NumberFormatException or IllegalStateException error occurs. |
| CRS conversion: Required properties for point conversion not sufficient, no conversion applied. | The properties listed in the meta item all represent the longitude or latitude, but not both, so we cannot construct the Point, even if there are two or three properties provided. This is the final check before sending the data to the CRS converter to make sure the conversion can be applied. This error means either the latitude or longitude of the point is missing. |
| CRS conversion: Invalid nested property name: '%s', no conversion applied. | Currently only a fixed list of property names are supported. The conversion must be able to understand which properties represent latitude/longitude/easting/northing. For supported property names, please see the Supported property names section. |
| CRS conversion: Missing the 'points' property in the nested property, no conversion applied. | If a nested property is listed in the meta item, then it must contain a field named ‘points’ which holds a list of points. If this field is missing or empty, no conversion occurs. |
| CRS conversion: Bad request from the CRS converter, illegal persistable reference, no conversion applied. | We call the CRS converter to perform the conversion. If the CRS converter returns "400 bad request," it means the JSON format of the persistable reference is not correct. |
| Response from CRS converter: %s | Other than 400, sometimes we see other 5xx responses from the CRS converter. This API cannot handle these cases. We pass on the response we have from the CRS converter and let you decide whether to ignore this case, retry, or contact us for further information. |
| CRS conversion: Illegal value in nested property '%s', error message: %s, no conversion applied. | The field ‘points’ in the nested property needs to be a JsonArray, otherwise a ClassCastException or IllegalStateException error occurs when we try to get it. If we see these exceptions, we put the property’s name and the error message from the exception into our error message so that users understand how to fix it. |
| DateTime conversion: Frame of reference does not match given data for property %s, no conversion applied. | The DateTime format in the persistableReference does not match the given data. |
| DateTime conversion: Invalid DateTime format. %s. No conversion applied. | The format for the DateTime is invalid, meaning the pattern is illegal in the DateTime format. For supported DateTime formats, please see the Supported DateTime formats section. |
| DateTime conversion: "%s" could not be parsed for property %s. %s. No conversion applied. | The value for the DateTime is invalid. For example, valid values for MonthOfYear are 1-12, so this error message appears if the month value is greater than 12. |
| DateTime conversion: Unknown time zone ID: %s. No conversion applied. | The time zone does not exist. For supported time zone IDs, see the Supported DateTime time zones section. |
| DateTime conversion: Invalid ID for region-based ZoneId, invalid format: Invalid Timezone. No conversion applied. | The time zone format is not allowed. |
| DateTime conversion: Error parsing "%s". No conversion applied. | There was an issue while parsing the text. Check that the persistable reference is correct and that the DateTime information is sufficient. |
Supported property names for Longitude:
| Property Name |
|---|
| X |
| LON |
| Longitude |
| wlbEwUtm |
| wlbEwDesDeg |
| TOPHOLEXNG |
| TOPHOLEXDD |
| BHLongitude |
| Utm_X |
Supported property names for Latitude:
| Property Name |
|---|
| Y |
| LAT |
| Latitude |
| wlbNsUtm |
| wlbNsDecDeg |
| TOPHOLEYNG |
| TOPHOLEYDD |
| BHLatitude |
| Utm_Y |
Supported nested property names:
| Property Name |
|---|
| projectOutlineLocalGeographic |
| projectOutlineProjected |
These are some examples of the many supported formats for DAT and DTM.
Supported formats for DAT:
| Format | Example |
|---|---|
| MM/dd/yyyy | 08/23/2019 |
| MM-dd-yy | 08-23-2019 |
| MM.dd.yy | 08.23.2019 |
| MM dd yy | 08 23 2019 |
| MMM/dd/yy | Aug/23/19 |
| MMMM/dd/yy | August/23/19 |
| MMMM d, yyyy | August 23, 2019 |
| dd-MMM-yyyy | 23-Aug-2019 |
| dd/MM/yyyy | 23/08/2019 |
| yyyy/M/d | 2019/8/23 |
| yyyy-MM-d | 2019-08-23 |
| E, MMM dd yyyy | Fri, Aug 23 2019 |
| EEEE, MMM dd yyyy | Friday, Aug 23 2019 |
Supported formats for DTM:
| Format | Example |
|---|---|
| MM/dd/yyyy HH:mm:ss | 08/23/2019 12:08:01 |
| MM/dd/yyyy HH:mm:ss.SSS | 08/23/2019 12:08:01.001 |
| MM/dd/yyyy H.mm.ss | 08/23/2019 12.08.01 |
| yyyy-MM-ddTHH:mm:ssZ | 2019-08-23T12:08:01Z |
| EEEE, MMM dd, yyyy HH:mm:ss a | Friday, Aug 23, 2019 12:08:01 PM |
Converting a DateTime between time zones is supported, as long as a valid time zone ID exists in the persistable reference. Besides time zone ID, format UTC+offset and GMT+offset are also supported.
The list of valid time zone IDs can be found below:
List of valid time zone IDs
Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmara
Africa/Asmera
Africa/Bamako
Africa/Bangui
Africa/Banjul
Africa/Bissau
Africa/Blantyre
Africa/Brazzaville
Africa/Bujumbura
Africa/Cairo
Africa/Casablanca
Africa/Ceuta
Africa/Conakry
Africa/Dakar
Africa/Dar_es_Salaam
Africa/Djibouti
Africa/Douala
Africa/El_Aaiun
Africa/Freetown
Africa/Gaborone
Africa/Harare
Africa/Johannesburg
Africa/Juba
Africa/Kampala
Africa/Khartoum
Africa/Kigali
Africa/Kinshasa
Africa/Lagos
Africa/Libreville
Africa/Lome
Africa/Luanda
Africa/Lubumbashi
Africa/Lusaka
Africa/Malabo
Africa/Maputo
Africa/Maseru
Africa/Mbabane
Africa/Mogadishu
Africa/Monrovia
Africa/Nairobi
Africa/Ndjamena
Africa/Niamey
Africa/Nouakchott
Africa/Ouagadougou
Africa/Porto-Novo
Africa/Sao_Tome
Africa/Timbuktu
Africa/Tripoli
Africa/Tunis
Africa/Windhoek
America/Adak
America/Anchorage
America/Anguilla
America/Antigua
America/Araguaina
America/Argentina/Buenos_Aires
America/Argentina/Catamarca
America/Argentina/ComodRivadavia
America/Argentina/Cordoba
America/Argentina/Jujuy
America/Argentina/La_Rioja
America/Argentina/Mendoza
America/Argentina/Rio_Gallegos
America/Argentina/Salta
America/Argentina/San_Juan
America/Argentina/San_Luis
America/Argentina/Tucuman
America/Argentina/Ushuaia
America/Aruba
America/Asuncion
America/Atikokan
America/Atka
America/Bahia
America/Bahia_Banderas
America/Barbados
America/Belem
America/Belize
America/Blanc-Sablon
America/Boa_Vista
America/Bogota
America/Boise
America/Buenos_Aires
America/Cambridge_Bay
America/Campo_Grande
America/Cancun
America/Caracas
America/Catamarca
America/Cayenne
America/Cayman
America/Chicago
America/Chihuahua
America/Coral_Harbour
America/Cordoba
America/Costa_Rica
America/Creston
America/Cuiaba
America/Curacao
America/Danmarkshavn
America/Dawson
America/Dawson_Creek
America/Denver
America/Detroit
America/Dominica
America/Edmonton
America/Eirunepe
America/El_Salvador
America/Ensenada
America/Fort_Nelson
America/Fort_Wayne
America/Fortaleza
America/Glace_Bay
America/Godthab
America/Goose_Bay
America/Grand_Turk
America/Grenada
America/Guadeloupe
America/Guatemala
America/Guayaquil
America/Guyana
America/Halifax
America/Havana
America/Hermosillo
America/Indiana/Indianapolis
America/Indiana/Knox
America/Indiana/Marengo
America/Indiana/Petersburg
America/Indiana/Tell_City
America/Indiana/Vevay
America/Indiana/Vincennes
America/Indiana/Winamac
America/Indianapolis
America/Inuvik
America/Iqaluit
America/Jamaica
America/Jujuy
America/Juneau
America/Kentucky/Louisville
America/Kentucky/Monticello
America/Knox_IN
America/Kralendijk
America/La_Paz
America/Lima
America/Los_Angeles
America/Louisville
America/Lower_Princes
America/Maceio
America/Managua
America/Manaus
America/Marigot
America/Martinique
America/Matamoros
America/Mazatlan
America/Mendoza
America/Menominee
America/Merida
America/Metlakatla
America/Mexico_City
America/Miquelon
America/Moncton
America/Monterrey
America/Montevideo
America/Montreal
America/Montserrat
America/Nassau
America/New_York
America/Nipigon
America/Nome
America/Noronha
America/North_Dakota/Beulah
America/North_Dakota/Center
America/North_Dakota/New_Salem
America/Ojinaga
America/Panama
America/Pangnirtung
America/Paramaribo
America/Phoenix
America/Port_of_Spain
America/Port-au-Prince
America/Porto_Acre
America/Porto_Velho
America/Puerto_Rico
America/Punta_Arenas
America/Rainy_River
America/Rankin_Inlet
America/Recife
America/Regina
America/Resolute
America/Rio_Branco
America/Rosario
America/Santa_Isabel
America/Santarem
America/Santiago
America/Santo_Domingo
America/Sao_Paulo
America/Scoresbysund
America/Shiprock
America/Sitka
America/St_Barthelemy
America/St_Johns
America/St_Kitts
America/St_Lucia
America/St_Thomas
America/St_Vincent
America/Swift_Current
America/Tegucigalpa
America/Thule
America/Thunder_Bay
America/Tijuana
America/Toronto
America/Tortola
America/Vancouver
America/Virgin
America/Whitehorse
America/Winnipeg
America/Yakutat
America/Yellowknife
Antarctica/Casey
Antarctica/Davis
Antarctica/DumontDUrville
Antarctica/Macquarie
Antarctica/Mawson
Antarctica/McMurdo
Antarctica/Palmer
Antarctica/Rothera
Antarctica/South_Pole
Antarctica/Syowa
Antarctica/Troll
Antarctica/Vostok
Arctic/Longyearbyen
Asia/Aden
Asia/Almaty
Asia/Amman
Asia/Anadyr
Asia/Aqtau
Asia/Aqtobe
Asia/Ashgabat
Asia/Ashkhabad
Asia/Atyrau
Asia/Baghdad
Asia/Bahrain
Asia/Baku
Asia/Bangkok
Asia/Barnaul
Asia/Beirut
Asia/Bishkek
Asia/Brunei
Asia/Calcutta
Asia/Chita
Asia/Choibalsan
Asia/Chongqing
Asia/Chungking
Asia/Colombo
Asia/Dacca
Asia/Damascus
Asia/Dhaka
Asia/Dili
Asia/Dubai
Asia/Dushanbe
Asia/Famagusta
Asia/Gaza
Asia/Harbin
Asia/Hebron
Asia/Ho_Chi_Minh
Asia/Hong_Kong
Asia/Hovd
Asia/Irkutsk
Asia/Istanbul
Asia/Jakarta
Asia/Jayapura
Asia/Jerusalem
Asia/Kabul
Asia/Kamchatka
Asia/Karachi
Asia/Kashgar
Asia/Kathmandu
Asia/Katmandu
Asia/Khandyga
Asia/Kolkata
Asia/Krasnoyarsk
Asia/Kuala_Lumpur
Asia/Kuching
Asia/Kuwait
Asia/Macao
Asia/Macau
Asia/Magadan
Asia/Makassar
Asia/Manila
Asia/Muscat
Asia/Nicosia
Asia/Novokuznetsk
Asia/Novosibirsk
Asia/Omsk
Asia/Oral
Asia/Phnom_Penh
Asia/Pontianak
Asia/Pyongyang
Asia/Qatar
Asia/Qyzylorda
Asia/Rangoon
Asia/Riyadh
Asia/Saigon
Asia/Sakhalin
Asia/Samarkand
Asia/Seoul
Asia/Shanghai
Asia/Singapore
Asia/Srednekolymsk
Asia/Taipei
Asia/Tashkent
Asia/Tbilisi
Asia/Tehran
Asia/Tel_Aviv
Asia/Thimbu
Asia/Thimphu
Asia/Tokyo
Asia/Tomsk
Asia/Ujung_Pandang
Asia/Ulaanbaatar
Asia/Ulan_Bator
Asia/Urumqi
Asia/Ust-Nera
Asia/Vientiane
Asia/Vladivostok
Asia/Yakutsk
Asia/Yangon
Asia/Yekaterinburg
Asia/Yerevan
Atlantic/Azores
Atlantic/Bermuda
Atlantic/Canary
Atlantic/Cape_Verde
Atlantic/Faeroe
Atlantic/Faroe
Atlantic/Jan_Mayen
Atlantic/Madeira
Atlantic/Reykjavik
Atlantic/South_Georgia
Atlantic/St_Helena
Atlantic/Stanley
Australia/ACT
Australia/Adelaide
Australia/Brisbane
Australia/Broken_Hill
Australia/Canberra
Australia/Currie
Australia/Darwin
Australia/Eucla
Australia/Hobart
Australia/LHI
Australia/Lindeman
Australia/Lord_Howe
Australia/Melbourne
Australia/North
Australia/NSW
Australia/Perth
Australia/Queensland
Australia/South
Australia/Sydney
Australia/Tasmania
Australia/Victoria
Australia/West
Australia/Yancowinna
Brazil/Acre
Brazil/DeNoronha
Brazil/East
Brazil/West
Canada/Atlantic
Canada/Central
Canada/Eastern
Canada/Mountain
Canada/Newfoundland
Canada/Pacific
Canada/Saskatchewan
Canada/Yukon
CET
Chile/Continental
Chile/EasterIsland
CST6CDT
Cuba
EET
Egypt
Eire
EST5EDT
Etc/GMT
Etc/GMT+0
Etc/GMT+1
Etc/GMT+10
Etc/GMT+12
Etc/GMT+11
Etc/GMT+2
Etc/GMT+3
Etc/GMT+4
Etc/GMT+5
Etc/GMT+6
Etc/GMT+7
Etc/GMT+8
Etc/GMT+9
Etc/GMT0
Etc/GMT-0
Etc/GMT-1
Etc/GMT-10
Etc/GMT-11
Etc/GMT-12
Etc/GMT-13
Etc/GMT-14
Etc/GMT-2
Etc/GMT-3
Etc/GMT-4
Etc/GMT-5
Etc/GMT-6
Etc/GMT-7
Etc/GMT-8
Etc/GMT-9
Etc/Greenwich
Etc/UCT
Etc/Universal
Etc/UTC
Etc/Zulu
Europe/Amsterdam
Europe/Andorra
Europe/Astrakhan
Europe/Athens
Europe/Belfast
Europe/Belgrade
Europe/Berlin
Europe/Bratislava
Europe/Brussels
Europe/Bucharest
Europe/Budapest
Europe/Busingen
Europe/Chisinau
Europe/Copenhagen
Europe/Dublin
Europe/Gibraltar
Europe/Guernsey
Europe/Helsinki
Europe/Isle_of_Man
Europe/Istanbul
Europe/Jersey
Europe/Kaliningrad
Europe/Kiev
Europe/Kirov
Europe/Lisbon
Europe/Ljubljana
Europe/London
Europe/Luxembourg
Europe/Madrid
Europe/Malta
Europe/Mariehamn
Europe/Minsk
Europe/Monaco
Europe/Moscow
Europe/Nicosia
Europe/Oslo
Europe/Paris
Europe/Podgorica
Europe/Prague
Europe/Riga
Europe/Rome
Europe/Samara
Europe/San_Marino
Europe/Sarajevo
Europe/Saratov
Europe/Simferopol
Europe/Skopje
Europe/Sofia
Europe/Stockholm
Europe/Tallinn
Europe/Tirane
Europe/Tiraspol
Europe/Ulyanovsk
Europe/Uzhgorod
Europe/Vaduz
Europe/Vatican
Europe/Vienna
Europe/Vilnius
Europe/Volgograd
Europe/Warsaw
Europe/Zagreb
Europe/Zaporozhye
Europe/Zurich
GB
GB-Eire
GMT
GMT0
Greenwich
Hongkong
Iceland
Indian/Antananarivo
Indian/Chagos
Indian/Christmas
Indian/Cocos
Indian/Comoro
Indian/Kerguelen
Indian/Mahe
Indian/Maldives
Indian/Mauritius
Indian/Mayotte
Indian/Reunion
Iran
Israel
Jamaica
Japan
Kwajalein
Libya
MET
Mexico/BajaNorte
Mexico/BajaSur
Mexico/General
MST7MDT
Navajo
NZ
NZ-CHAT
Pacific/Apia
Pacific/Auckland
Pacific/Bougainville
Pacific/Chatham
Pacific/Chuuk
Pacific/Easter
Pacific/Efate
Pacific/Enderbury
Pacific/Fakaofo
Pacific/Fiji
Pacific/Funafuti
Pacific/Galapagos
Pacific/Gambier
Pacific/Guadalcanal
Pacific/Guam
Pacific/Honolulu
Pacific/Johnston
Pacific/Kiritimati
Pacific/Kosrae
Pacific/Kwajalein
Pacific/Majuro
Pacific/Marquesas
Pacific/Midway
Pacific/Nauru
Pacific/Niue
Pacific/Norfolk
Pacific/Noumea
Pacific/Pago_Pago
Pacific/Palau
Pacific/Pitcairn
Pacific/Pohnpei
Pacific/Ponape
Pacific/Port_Moresby
Pacific/Rarotonga
Pacific/Saipan
Pacific/Samoa
Pacific/Tahiti
Pacific/Tarawa
Pacific/Tongatapu
Pacific/Truk
Pacific/Wake
Pacific/Wallis
Pacific/Yap
Poland
Portugal
PRC
PST8PDT
ROK
Singapore
SystemV/AST4
SystemV/AST4ADT
SystemV/CST6
SystemV/CST6CDT
SystemV/EST5
SystemV/EST5EDT
SystemV/HST10
SystemV/MST7
SystemV/MST7MDT
SystemV/PST8
SystemV/PST8PDT
SystemV/YST9
SystemV/YST9YDT
Turkey
UCT
Universal
US/Alaska
US/Aleutian
US/Arizona
US/Central
US/Eastern
US/East-Indiana
US/Hawaii
US/Indiana-Starke
US/Michigan
US/Mountain
US/Pacific
US/Pacific-New
US/Samoa
UTC
WET
W-SU
ZuluOffset is supported for UTC and GMT. Valid formats can be found below.
| Format |
|---|
| Z - for UTC |
| +h |
| +hh |
| +hh:mm |
| -hh:mm |
| +hhmm |
| -hhmm |
| +hh:mm:ss |
| -hh:mm:ss |
| +hhmmss |
| -hhmmss |