OrbitSailor Archive

OrbitSailor Archive offers 12+ years of AIS data. This data archive can be accessed via the OrbitSailor Configuration Dashboard or the OrbitSailor API.

Key Features

The OrbitSailor Archive offers the following features. Please note that some features may be restricted or unavailable depending on your agreement:

1. Access to decoded data

• no downsampling mode: retrieve all available messages without downsampling
• downsampling by distance (optional): specify a minimum distance (in meters) between messages from the same vessel
• downsampling by time(optional): specify a minimum time interval (in minutes) between messages from the same vessel

2. Flexible data querying:

• Time range (optional): Define a specific time range to query data
• Individual records (optional): receive decoded messages as separate records
• Combined messages (optional): receive dynamic and static messages combined

INFO

When using an IMO-based list, only static messages will be provided by default. To include both static and dynamic messages, enable the "Combine static and dynamic messages" toggle. This ensures all data is gathered and merged, regardless of the key identifier used for filtering.

3. Sorting data:

Order retrieved data by:

• MMSI first, then timestamp
• MMSI
• timestamp

4. Delivery formats

• JSON
• CSV
• Custom message format

5. Geographical filtering

• upload a GeoJSON file (optional):add your area of interest by uploading a pre-defined GeoJSON file
• define on map (optional): create a custom polygon directly on the map to define your area of interest

6. Vessel-based filtering Retrieve data exclusively for vessels listed in your list of vessels.

Query data in OrbitSailor Archive Configuration Interace

To configure your query in the OrbitSailor Configurtion Interface, you must have a user account and your customer account must have added the OrbitSailor Archive service. If you do not have access to the OrbitSailor Archive, please contact the OrbitSailor team to obtain a license.

Follow these steps to create a new query for data:

1. Log in to the OrbitSailor Configuration Dashboard using an account with admin rights
2. Navigate to OrbitSailor Archive
3. To create a new query, click on ADD NEW button
4. Enter a new name for your query in Friendly Name field
5. Configure the following optional settings according to your requirements:

• Switch on the toggle switch Downsample based on distance and provide a distance in meters
• Switch on the toggle switch Downsample based on time and enter a minimum interval time in minutes

6. Define a time range by providing date and time (UTC) in the sections Time range start and Time range end
7. (optional) Switch on the toggle switch Combine static and dynamic messages to receive dynamic and static data combined
8. Select one of the options in the Order by drop-down list:

• MMSI first, then timestamp
• MMSI
• Timestamp

9. Define a delivery format by selecting one of the options in the Delivery Format drop-down list:

• JSON
• CSV
• Custom (manually type-in your format using the markup introduced in Custom message format)

10. You can also configure an optional setting for your area of interest by switching on the _"Filter by geographical area

• (optional) Upload a GeoJSON file by clicking on No file chosen in the Upload GeoJSON

INFO

Please refer to the GeoJSON information page to learn more about the supported features.

or

• (optional) Draw your own polygon directly on the map to define your area of interest

11. To get data for your vessels only, switch on the toggle Filter by vessel list and select the proper Ownning Group and the list of vessels in Vessel List drop-down menu
12. Verify your settings and click on SUBMIT button
13. Your new query is now presented on the top of the screen

INFO

Your request is processed by the OrbitSailor Archive system. Depending on the settings (i.e. time range, number of vessels, size of the area of interest), querying may take minutes (a few months of data for a few vessels) to many hours (e.g. 1 year or longer, global coverage).

You can check the status of your request by looking at the list and checking the status. The following statuses are available:

• Queued: your request is being processed
• Complete: your request has been processed and the archive file is ready to download
• Error: an error occured, try again or contact with the OrbitSailor team

INFO

The list is not updated automatically, you need to refresh or reload the page to see the current status.

When the results are ready, just click on the query in the list, and click on SHOW button. You will see a button DOWNLOAD RESULT. Once you click on it, the download process begins. Be patient, the result file may be large. The download time depends on your Internet connection and the server speed.

INFO

Query results remain available for retrieval for up to 6 hours after the query is completed.

Query data in OrbitSailor Archive API

More detailed information available in the OrbitSailor Archive API documentaiton.

The sample code in Python is provided in the end of this page.

Accessing archive data via the OrbitSailor Archive API requires to follow a three-step process:

1. Obtain the bearer token:

• Request URL (POST method): https://api.orbitsailor.com/api/Users/login

{
  "username": "string",
  "password": "string",
  "issueRefreshToken": true
}

In return, you'll get:

{
  "token": "YOUR TOKEN",
  "expiration": "EXPIRATION DATE&TIME",
  "userId": "YOUR UNIQUE USER ID",
  "roles": [
    "MinimumAccessUser",
    "Admin",
    "User"
  ]
}

The "token" is required to make requests.

2. Submit the query to perform an API call to initiate the query:

• Request URL (POST method): https://api.orbitsailor.com/api/ArchiveApi/submit

{
  "downsample": {
    "minTimeBetweenMessagesMinutes": 0,
    "minDistanceBetweenMessagesMeters": 0
  },
  "timeRangeStart": "2025-02-24T12:06:44.997Z",
  "timeRangeEnd": "2025-02-24T12:06:44.997Z",
  "friendlyName": "string",
  "areaGeoJson": "string",
  "customFormatTemplate": "string",
  "deliveryFormat": "Json",
  "combineStaticAndDynamic": true,
  "mmsiSet": [
    0
  ],
  "imoSet": [
    0
  ],
  "orderBy": "Mmsi",
  "vesselListId": 0
}

3. Retrieve the result:

• Request URL: https://api.orbitsailor.com/api/ArchiveApi/{queryId}/result

INFO

The result API call can be retried as many times as desired until the server returns a 410 - Gone response. Additionally, the result download can be resumed.

INFO

Query results remain available for retrieval for up to 6 hours after the query is completed.

Sample query code in Python

import urllib.request
import json

api_base = "https://api.orbitsailor.com"

username = "YOUR_USERNAME_HERE"
password = "YOUR_PASSWORD_HERE"

headers = {"Content-Type": "application/json"}


def login():
    url = api_base + "/api/Users/login"
    body = json.dumps(
        {"username": username, "password": password, "issueRefreshToken": False}
    ).encode("utf-8")

    req = urllib.request.Request(url, data=body, headers=headers, method="POST")
    with urllib.request.urlopen(req) as response:
        token = json.load(response)["token"]
        headers["Authorization"] = "Bearer " + token


login()
print("logged in")

query_params = {
    "downsample": {
        # put None for no downsampling by time
        "minTimeBetweenMessagesMinutes": 60,
        # put None for no downsampling by distance
        "minDistanceBetweenMessagesMeters": 500,
    },
    "timeRangeStart": "2025-03-01T10:50:45.741Z",
    "timeRangeEnd": "2025-03-03T10:50:45.741Z",
    # a name for you to identify the query, optional
    "friendlyName": "Demo query",
    # optionally, you can put an area in geojson format here
    "areaGeoJson": None,
    "deliveryFormat": "CSV",
    "combineStaticAndDynamic": True,
    # this is the Canopee vessel. You can put
    "mmsiSet": [228438700],
    "imoSet": [9924120],
    "orderBy": "MmsiThenTimestampSat",
}

print("submitting query...")
req = urllib.request.Request(
    api_base + "/api/ArchiveApi/submit",
    data=json.dumps(query_params).encode("utf-8"),
    headers=headers,
    method="POST",
)
with urllib.request.urlopen(req) as response:
    response = json.load(response)
    print(response)
    query_id = response["queryId"]
    if response["status"] == "Error":
        raise Exception("failed to submit: " + response["errorMessage"])

print("fetching result...")
# because the result call may hang until the request is complete, we need to guard against timeouts
# for very large queries
while True:
    url = api_base + f"/api/ArchiveApi/{query_id}/result"
    req = urllib.request.Request(
        url,
        data=None,
        headers=headers,
        method="GET",
    )
    try:
        with urllib.request.urlopen(req) as response:
            # this is for demo purposes only, and buffers the entire request body in memory.
            # you should use some kind of streaming API for your result fetching call.
            print(response.read().decode("utf-8"))
            break
    except urllib.error.HTTPError as err:
        print(err)
        if err.code == 401:
            login()