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:
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:
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:
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.
When defining the request body, there are certain constraints that a shape must fulfill, depending on the chosen type.
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.
No constraints
When creating a point, only a single coordinate of latitude and longitude needs to be specified in the GeoJSON object.
No constraints.
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:
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:
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.
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.
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.
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.
The following image details the process of choosing a data format and calling the API accordingly:
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: