Menu
Home Maritime Domain Awareness Endpoints Shapes

Shapes

This article will detail the input and output of the several endpoints that is able to operations on shapes

Content Overview:

Prerequisite

The base url for the modification of shapes is:

https://demo.ghmaritime.com/api/config/

Additionally, some of the operations requires the user to specify the id of the shape.

However if the id of the shape is unknown, it is possible to construct at GET request via the route /shapes/{name} and then get the id of the shape.

The API will return the entire shape object, which contains the id of the shape.

Define the name of the shape:

name = "<ShapeName>"

Then call the api with a GET request:

GET /shapes/{name}

The API will respond with a JSON object of the shape definitions, which contains the id of the shape:

{ "id": "123" }

Code example:

import requests
import json

name = "<ShapeName>"

URL = f'https://demo.ghmaritime.com/api/config/shapes/{name}'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}
  
response = requests.get(URL, headers=headers, timeout=10)
print(response.text)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

The following is a list of parameters that can be altered in the code:

  • <ShapeName>
    • Name of the shape you want the id of
  • <credentials>
    • Your username and password for authentication as Base64-encoding

Response Sample:

{
  "geometry": {
    "coordinates": [
      [
        [
          14.05834627976409,
          55.1786775171027
        ],
        [
          14.71203280320158,
          55.57505112961118
        ],
        [
          15.56896639695159,
          55.56883977888324
        ],
        [
          15.93700838913909,
          54.97111702573383
        ],
        [
          14.50878573288908,
          54.59415252295574
        ],
        [
          13.77819491257658,
          54.79415962743815
        ],
        [
          14.05834627976409,
          55.1786775171027
        ]
      ]
    ],
    "type": "Polygon"
  },
  "properties": {
    "acl": [
      "GateHouse"
    ],
    "description": "",
    "id": "c0170f78-1913-4af8-8c5d-0857d0bd2162",
    "name": "Bornhollm",
    "owner": "portadmin",
    "user_id": "124bf7c6-0f49-4f90-9117-4fd69e2885bb"
  },
  "type": "Feature"
}

Create Shape

To create a shape, construct a POST request via the endpoint /shapes, with a GeoJSON object as the request body:

Code Example:

import requests
import json

URL = f'https://demo.ghmaritime.com/api/config/shapes'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

payload = {
    "type": "Feature",
    "properties": {
        "name": "<ShapeName>",
    },
    "geometry": {
        "type": "<ShapeType>",
        "coordinates": [
          [
            [7.691873968739653, 57.83075674025332],
            [7.702860296864652, 54.27553453348099],
            [12.877420843739653, 54.224184298544515],
            [12.910379828114651, 57.84245356620403],
            [7.691873968739653, 57.83075674025332]
          ]
        ]
    }
}

response = requests.post(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
  • <credentials>
    • Your username and password for authentication as Base64-encoding
  • <ShapeName>
    • Name of the shape to be created.
  • <ShapeType>
    • The type of shape, i.e. polygon, linestring, circle, point.
  • “coordinates”
    • List of lists, containing points in the latitude and longitude format.
    • To alter this, simply replace the list of points with your own list of points.

Response Sample:

{
  "id": "ff4f8e44-be8b-42dc-9ba8-7e5f6f916509"
}

The response is the id of the created shape.

This indicates that the creation of the shape was a success.

Constraints

When defining the request body, there are certain fields that must be set, depending on the type of the shape.

Circle

When creating a circle, its’ field “type” should be “Point”, and the field “radius” should be specified under the “properties” field.

"properties": {
        "name": "circle1",
        "radius": "100",
    },
    "geometry": {
        "type": "Point",
        "coordinates": [
            10.91924373456776,
            55.73646508111631
        ]
    }
}

Line

No constraints.

Point

When creating a point, only a single pair of latitude and longitude should be specified in the “coordinates” field:

"geometry": {
        "type": "Point",
        "coordinates": [
            10.91924373456776,
            55.73646508111631
        ]
    }
}

Polygon

No constraints.

Delete Shape

A shape can be deleted by constructing a DELETE request and specifying the id of the shape in the URL.

DELETE /shapes/{id}

Code Example:

import requests
import json

id = "<ShapeID>"

URL = "https://demo.ghmaritime.com/api/config/{id}"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.delete(URL, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

The following is a list of parameters that can be altered in the code:

  • <ShapeID>
    • The identifier of the shape.
  • <credentials>
    • Your username and password for authentication as Base64-encoding

Response Sample:

{}

Update Shape

To update an already existing shape, construct a PUT request via the endpoint /shapes/{id}.

This allows the user to update an already existing shape with new values, i.e. GeoJSON, name, owner, etc.

Code Example:

import requests
import json

id = "<ShapeID>"

URL = f'https://demo.ghmaritime.com/api/config/shapes/{id}'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

payload = {
    "type": "Feature",
    "properties": {
        "name": "wkt",
    },
    "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [7.691873968739653, 57.83075674025332],
            [7.702860296864652, 54.27553453348099],
            [12.877420843739653, 54.224184298544515],
            [12.910379828114651, 57.84245356620403],
            [7.691873968739653, 57.83075674025332]
          ]
        ]
    }
}
  
response = requests.put(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

The following is a list of parameters to be altered in the code:

  • <ShapeID>
    • The identifier of the shape to be updated.
  • <credentials>
    • Your username and password for authentication as Base64-encoding
  • payload
    • The JSON object "payload", can be altered to the desired updates to the shape.

Response Sample:

{
  "id": "f9542c43-3d40-45c1-871b-92a5a3fdeb72"
}

The output-id should correspond to the input-id, since it is the same object that has been modified.

Import Shape

It is also possible to import a shape from different formats. This is done by constructing a PUT request to the /shapes/import endpoint with the request body containing one of the following formats:

Additionally, the name and type should be specified for the shape in the parameters of the request.

GeoJSON

Importing a GeoJSON file is done by reading the file and converting it into a JSON object that can be sent as the request body.

Code Example:

import requests
import json

URL = f'https://demo.ghmaritime.com/api/config/shapes/import'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

params = {
    "name": "<ShapeName>",
    "type": "<ImportFileType>"
}

with open("<path>.geojson", "r") as f:
    data = json.load(f)

response = requests.post(URL, json=data, params=params, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

The following is a list of parameters to alter in the code:

  • <credentials>
    • Your username and password for authentication as Base64-encoding
  • <ShapeName>
    • Name of the shape, once imported.
  • <ImportFileType>
    • File format of the imported shape, here it is "geojson".
  • <path>
    • Path to file to be imported.

Response Sample:

{
  "id": "c90aa57f-9123-4b48-81a2-0fbce59116fd"
}

WKT

To import a Well Known Text (WKT) file, it is important to note that the "Content-Type" field should be set to "text/plain".

Code Example:

import requests
import json

URL = f'https://demo.ghmaritime.com/api/config/shapes/import'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "text/plain",
}

params = {
    "name": "<ShapeName>",
    "type": "<ImportFileType>"
}

with open("<path>.wkt", "r") as f:
    data = f.read().strip()

  
response = requests.post(URL, data=data, params=params, headers=headers, timeout=10)
print(response.text)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

The following is a list of parameters to alter in the code:

  • <credentials>
    • Your username and password for authentication as Base64-encoding
  • <ShapeName>
    • Name of the shape, once imported.
  • <ImportFileType>
    • File format of the imported shape, here it is "wkt".
  • <path>
    • Path to file to be imported.

Response Sample:

{
  "id": "22ce9dda-0f38-4d6a-8087-3c7d57d06d38"
}

ZIP

When importing a ZIP file, it should be encoded as base64 to import a shape in ZIP format.

It is important to note that the "Content-Type" field is different for zip files, where they should be specified as "application/octet-stream".

The following code demonstrates how to do this:

Code Example:

import requests
import json
import base64

URL = f'https://demo.ghmaritime.com/api/config/shapes/import'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/octet-stream",
}

params = {
    "name": "<ShapeName>",
    "type": "<ImportFileType>"
}

with open("<path>.zip", "rb") as f:
    binary_data = f.read()
    base64_data = base64.b64encode(binary_data).decode("utf-8")

response = requests.post(URL, data=base64_data, params=params, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

The following is a list of parameters to alter in the code:

  • <credentials>
    • Your username and password for authentication as Base64-encoding
  • <ShapeName>
    • Name of the shape, once imported.
  • <ImportFileType>
    • File format of the imported shape, here it is "zip".
  • <path>
    • Path to shape file.

Response Sample:

{
  "id": "2111d2df-5ee9-4ec8-acc8-f1fd1f138699"
}

Export Shape

To export a shape, construct a GET request via the /shapes/export/{id} endpoint with parameters that specify the format of the file.

The 3 possible types of exports is as follows:

The construction of the GET request work similar for each type of export; however, they differ in the “format” field in the parameters.

The response from the API is an object in the chosen format.

  • GeoJSON
    • “format”: “geojson”
  • KML
    • “format”: “kml”
  • WKT
    • “format”: “wkt”

Code Example:

import requests
import json

id = "<ShapeID>"

URL = f'https://demo.ghmaritime.com/api/config/shapes/export/{id}'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

params = {
    "format": "<ExportFormat>"
}
  
response = requests.get(URL, params=params, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

The following is a list of parameters to alter in the code:

  • <ShapeID
    • Object identifier of the vessel
  • <credentials>
    • Your username and password for authentication as Base64-encoding
  • <ExportFormat>
    • Format of exported object, i.e. “geojson”, “kml”, “wkt.
Updated on 17 November, 2025
Vessel Tracking