The coordinate conversion API

Table of Contents

• Introduction

• OpenAPI style coordinate conversion

  • The coordinate list object
  • The conversion request format
  • The conversion response object

• Example usage in python

• Supported coordinate systems

• Comma separated value (CSV) based coordinate conversions

Introduction

LINZ offers a coordinate conversion API that is more suitable than the coordinate conversion web application for converting large numbers of coordinates. There are some differences between this service and the concord web application:

• The API does not handle different coordinate representations such as as map references or converting decimal values to degrees/minutes/seconds strings. All coordinates are simple floating point numbers - either degrees or metres.

• The API uses a different software for coordinate conversions that may result in some sub millimetre differences between the results from the online converter and from the API.

• The API can handle a much larger number of coordinates than the online converter. Currently it supports converting up to 200000 coordinates in a single request.

The conversion API is located at https://www.geodesy.linz.govt.nz/api/conversions/v1. This URL will return a JSON formatted OpenAPI specification defining the API, which can be used to support building application that interface with the API.

The API also supports a simple comma separated value (CSV) format for input and output coordinate lists.

OpenAPI style coordinate conversion

The coordinate list object

Coordinate conversions are applied to a "coordinate list object" and return a converted coordinate list object following the same structure. The coordinate list object is structured as in the following example:

{
    "crs": "LINZ:NZGD2000/NZVD2016",
    "coordinateOrder": [
        "east",
        "north",
        "up"
    ],
    "coordinateEpoch": 2019.53,
    "coordinates": [
        [
            173.218789,
            -41.89021,
            157.81
        ],
        [
            172.54831,
            -40.769019,
            23.28
        ]
    ]
}

The elements of this structure are:

The conversion request format

A coodinate list object is converted to a different coordinate system by sending it in a POST request to https://www.geodesy.linz.govt.nz/api/conversions/v1/convert-to?crs=_targetCrs_&coordinate=_targetCoordinateOrder_, eg

curl --no-progress-meter -d @input_coords.json https://www.geodesy.linz.govt.nz/api/conversions/v1/convert-to?crs=LINZ:ITRF2014/NZVD2016&coordinateOrder=north/east/up

This has two parameters:

The conversion response object

The response JSON object contains the converted coordinate list with some summary information about the conversion. It is structured as in the following example:

{
    "coordinateErrors": [
        "Coordinates out of range for calculating geoid height (1)"
    ],
    "coordinateList": {
        "coordinateEpoch": 2019.53,
        "coordinateOrder": [
            "north",
            "east",
            "up"
        ],
        "coordinates": [
            [
                -41.890203953,
                173.21878889,
                157.81
            ],
            [
                -40.769011786,
                172.548310329,
                23.28
            ],
            null
        ],
        "crs": "LINZ:ITRF2014/NZVD2016"
    },
    "failCoordCount": 1,
    "inputCoordCount": 3,
    "status": "success"
}

The elements of this are:

Example usage in Python

This example demonstrates using the API to convert coordinates using the Python language. This example uses the Python requests module to simplify the API call:

import requests
import json

api = "https://www.geodesy.linz.govt.nz/api/conversions/v1/convert-to"

coordlist = {
    "crs": "LINZ:NZGD2000/NZVD2016",
    "coordinateOrder": ["east", "north", "up"],
    "coordinateEpoch": 2019.53,
    "coordinates": [
        [173.218789, -41.89021, 157.81],
        [172.54831, -40.769019, 23.28]
    ],
}

params = {"crs": "LINZ:NZTM", "coordinateOrder": "north/east"}

response = requests.post(api, params=params, json=coordlist)

if response.status_code == 200:
    nztmcoords = response.json()
    print(json.dumps(nztmcoords, indent=2))
else:
    print(f"Error: {response.text}")

Supported coordinate systems

The API also has an endpoint for listing the supported coordinate systems: https://www.geodesy.linz.govt.nz/api/conversions/v1/list-coordinate-systems. This returns an object as shown below with two elements, “crs” and “verticalCrs”. “crs” is a list of geometric coordinate systems and “verticalCrs” is a list of height coordinate systems.

{
    "crs": [
        {
            "linzCrsCode": "AGD66",
            "name": "Australian Geodetic Datum 1966"
        },
        {
            "linzCrsCode": "AGD84",
            "name": "Australian Geodetic Datum 1984"
        },
        {
            "linzCrsCode": "AITM2000",
            "name": "Antipodes Islands Transverse Mercator 2000"
        },
        ...
    ],
    "status": "success",
    "verticalCrs": [
        {
            "linzVerticalCrsCode": "AUCKHT1946",
            "name": "Auckland 1946 (from NZVD2016)"
        },
        {
            "linzVerticalCrsCode": "AUCKHT1946_NZVD09",
            "name": "Auckland 1946 (NZVD09)"
        },
        {
            "linzVerticalCrsCode": "BLUFHT1955",
            "name": "Bluff 1955 (from NZVD2016)"
        },
        {
            "linzVerticalCrsCode": "BLUFHT1955_NZVD09",
            "name": "Bluff 1955 (NZVD09)"
        },
        ...
    ]
}

Comma separated value (CSV) based coordinate conversions

In data analysis work it is often more convenient to convert CSV formatted lists of coordinates than to build JSON formatted objects containing the coordinates.

The CSV format is a simple comma separated list of coordinates. It may include a header record specifying the order of the coordinates. For example:

east,north,up
173.218789,-41.89021,157.81
172.54831,-40.769019,23.28

If the CSV does have a header with coordinate orders it can only contain values "east", "north", "up", "geocentricX", "geocentricY", and "geocentricZ".

Note that for CSV conversions which include a height ordinate the height ordinate must be the third one. It will not accept an order such as "up/north/east".

This is converted to a different coordinate system using an API call such as:

curl --no-progress-meter -d @input_coords.csv https://www.geodesy.linz.govt.nz/api/conversions/v1/convert-csv?crs=LINZ:NZGD2000/NZVD2016&useCsvHeaders=Y&toCrs='ITRF2014'

The convert-csv URL can include the following parameters:

The output coordinate CSV file is will be formatted in the same way as the input file. If a coordinate cannot be converted then the output ordinates will be blank, and they will be followed by an error message describing why they have not been converted.

If the conversion is incorrectly defined, for example if it uses an invalid CRS definition such as NZGD2001, then the call will return an error status code (rather than the normal 200 OK status code from a web request). The call will also return a JSON formatted error text in the same way as the OpenAPI conversion.