Shape Operations

As part of its core capabilities, the Maritime Domain Awareness API stores geometric shapes, allowing users to define areas of interest for monitoring, analysis, or alert generation. The geometric shapes can be used alongside other services to easily understand the area in which that service will operate.

There are several operations that can be performed via the API to alter the definitions of individual shapes; the main operations will be covered in this article.

Content Overview:

Prerequisite

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.

Visualization of getting the id of the shape:

Create Shape

Creating a shape is done by constructing a POST request via the route /shapes, that requires a GeoJSON object as the request body.

The GeoJSON object is defined by coordinates that define the points of the shape and a type which defines the type of the shape.

The coordinates are defined as an array of arrays that contain Longitude and Latitude values.

The API supports the following types:

  • Cirlcle
  • Line
  • Point
  • Polygon

When the API request is successful, the API will send a response as a JSON object with the id of the newly created shape.

The image below depicts the process of defining a GeoJSON object and then calling the API with a POST request, to create a shape in the API.

Constraints

When defining the request body, there are certain constraints that a shape must fulfill, depending on the chosen type.

Circle

When creating a circle, the type is described as a point; however, the radius of the circle must be specified in the GeoJSON object as well.

Line

No constraints

Point

When creating a point, only a single coordinate of latitude and longitude needs to be specified in the GeoJSON object.

Polygon

No constraints.

Delete Shape

A shape is deleted by issuing a DELETE request to /shapes/{id}, where {id} represents the shape’s unique identifier.

The ID of the shape should not be confused with its name, as they serve different purposes within the system.

This means that the ID of the shape is required to actually delete the shape; however, if it is unsure what the id of the shape is, then it is possible to construct a GET request to /shapes/{id}, where {id} in this context is the actual name of the shape.

The DELETE request will return an empty JSON object, if the deletion was a success.

Visualization of deleting a shape:

Update Shape

It is possible to update a shape with a new name, GeoJSON, etc., without deleting the shape and creating a new. This is done by constructing a PUT request to /shapes/{id}, where {id} represents the shape’s unique identifier.

The ID of the shape should not be confused with its name, as they serve different purposes within the system.

This means that the ID of the shape is required to actually delete the shape; however, if it is unsure what the id of the shape is, then it is possible to construct a GET request to /shapes/{id}, where {id} in this context is the actual name of the shape.

The PUT request will return a JSON object containing the id of the updated shape, if the update was a success.

Visualization of updating a shape when the id is known beforehand:

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

The format of GeoJSON as the request body follows that of a JSON object.
In the JSON object, the type of the shape should be specified and the coordinates that describes the shape itself. This means that the format is as follows:

{"type": "{shape}", "coordinates": [[[lat, lon], ...]... [[lat, lon], ...]]}

Ensure that the

Additionally, the header should specify the content-type as "application/json", when using the GeoJSON format.

WKT

The format when specifying the shape using WKT (Well Known Text), is in the form:

"{Shape} ((lat, lon), ...)"

The Shape variable specifies the type of the shape, and the list of latitude and longitude pairs describe the points of the shape.

Additionally, the header should specify the content-type as "text/plain", when using the WKT format.

ZIP

It is also possible to provide a zip file as the request body.

In this case, the header must specify the content-type as "application/octet-stream" and the zip file must be base64-encoded before being included in the request payload.

This is necessary since the server expects the data as base64-encoding and will decode it internally before processing the data.

Visual Representation of the Process

The following image details the process of choosing a data format and calling the API accordingly:

Export Shape

A shape is exported as JSON format by issuing a GET request to the endpoint /shapes/export/{id}; here the id variable is the unique identifier of the exported shape.

When exporting a shape, if the id is known, the header only needs to specify the Authorization of the user, the API only needs the id of the shape for processing.

The API will send a response in JSON format with the shape described in GeoJSON format.

Visualization of exporting a shape from the MDA API:

Updated on 10 July, 2025