OrbitSailor Archive

The OrbitSailor Archive provides access to more than 13 years of AIS data. The archive can be accessed through the OrbitSailor Configuration Dashboard or via 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 position updates from the same vessel
• downsampling by time(optional): specify a minimum time interval (in minutes) between messages from the same vessel

INFO

The OrbitSailor Archive reduces static data by deduplicating results. As a result, the number of messages (combined or separated) may differ from the actual number of raw NMEA messages.

2. Flexible data querying:

• Time range (optional): define a specific time range for the query
• Individual records (optional): receive decoded messages as separate records
• Combined messages (optional): receive dynamic and static messages combined into a single record

INFO

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

3. Data sorting:

Retrieved data can be ordered by:

• MMSI first, then timestamp
• MMSI
• timestamp

4. Delivery formats

• JSON
• CSV
• Custom message format

5. Geographical filtering

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

6. Vessel-based filtering

Retrieve data exclusively for vessels listed in your list of vessels.

Query data in the OrbitSailor Archive Configuration Interace

To configure a query in the OrbitSailor Configurtion Interface, you must have a user account and your customer account must include 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:

1. Log in to the OrbitSailor Configuration Dashboard using an account with admin rights
2. Navigate to OrbitSailor Archive
3. Click ADD NEW to create a new query
4. Enter a new name in the Friendly Name field
5. (optional) Configure the following optional downsampling settings as needed:

• Enable Downsample based on distance and provide a distance in meters
• Enable Downsample based on time and specify a minimum interval time in minutes

6. Define a time range by specifying date and time (UTC) for Time range start and Time range end

7. (Optional) Enable Combine static and dynamic messages to receive combined

8. Select a sorting option from the Order by drop-down list:

• MMSI first, then timestamp
• MMSI
• Timestamp

9. Select a delivery format from the Delivery Format drop-down list:

• JSON
• CSV
• Custom (manually define the format using the markup described in Custom message format)

10. (Optional) Enable Filter by geographical area and chose on of the following:

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

TIP

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

or

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

11. (Optional) Enable Filter by vessel list, then select the appropriate Ownning Group and Vessel List
12. Review your settings and click SUBMIT
13. The new query appears at the top of the list

INFO

Your request is processed by the OrbitSailor Archive system. Depending on the selected time range, number of vessels, and geographic scope, processing may take from a few minutes to several hours.

You can monitor the status of your request in the query list. The following statuses are available:

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

TIP

The query list does not update automatically. Refresh or reload the page to see the current status.

When the status is Complete, click on the query in the list and then click SHOW. A DOWNLOAD RESULT button will appear. Click it to start downloading the result file. Be aware that result file may be large. Download time depends on your Internet connection and server performance.

INFO

Query results remain available for download for up to 6 hours after processing is completed.

Query data in the OrbitSailor Archive API

More detailed information is available in the OrbitSailor Archive API documentaiton.

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

Accessing archive data via the OrbitSailor Archive API requires to follow a two-step process and require a properly authenticated API used as a bearer token. For more information on how to obtain the API key, please see here.

1. 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
}

2. 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"

orbitsailor_apikey = "osak_**********"

headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer " + orbitsailor_apikey
}

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 any mmsi or IMO you like here.
    "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 process the response body in a streaming manner for your production usecases.
            print(response.read().decode("utf-8"))
            break
    except urllib.error.HTTPError as err:
        print(err)