# Snapshot API
Customers can use our Snapshot API to retrieve Snapshot submissions from their vessels.
# Authentication
All API requests must be made using https and are secured using a bearer token. Your bearer token can be retrieved using our identity API and providing your client ID and client secret. For more information regarding retrieving a token contact the StratumFive Dev Team
Authentication token
The rest of this documentation assumes you already have a token.
To authenticate with the Snapshot API all requests must include an "Authorization" header with is content set to: Bearer <your authentication token>
An example cURL request with authentication headers set:
curl --location --request GET 'https://snapshot-api.stratumfive.com/api/podium/submissions/68731414-34d3-4333-9cf0-9c0375ef23rd' \
--header 'Authorization: Bearer <your authenication token>'
# Endpoints
# List Submissions
Returns a paginated list of submissions summaries in reverse chronological order. The summary contains the top level information about the submission, but not the actual content. To get submission content you will need to use the get submission endpoint.
# Resource URL
https://snapshot-api.stratumfive.com/api/podium/submissions
# Resource Information
| Info | Value |
|---|---|
| Method | GET |
| Response formats | JSON |
| Requires authentication? | Yes |
| Rate limited? | Yes |
| Requests / minute | 60 |
# Parameters
| Name | Required | Description | Default | Example |
|---|---|---|---|---|
| page | optional | The page of submissions to request | 1 | 123 |
| imo | optional | Filter by vessel IMO | 999999 | |
| shipName | optional | Filter by vessel name | HMS Snapshot |
# Example Request
GET https://snapshot-api.stratumfive.com/api/podium/submissions?page=20
# Example Response
{
"pagination": {
"totalPages": 1139,
"currentPage": 1,
"totalItems": 11390
},
"data": [
{
"id": "22364676-ce1a-4860-8e6e-d9d45c92f4dc",
"date": "2020-01-22T13:33:42.346Z", // The date the report was received
"reportDate": "2020-01-22T11:00:00.000Z", // The date set in the report
"status": "complete",
"title": "Position Report",
"type": "position-combined",
"vessel": {
"id": 248,
"name": "OCEAN SNAPSHOT",
"imo": "1111111",
"metadataId": null
},
"position": {
"lat": "51.666667",
"lon": "2.266667"
}
},
{
"id": "9dbbe96b-c435-4fab-87fa-a3945361cec9",
"date": "2020-01-22T13:29:51.836Z",
"reportDate": "2020-01-21T18:12:00.000Z",
"status": "complete",
"title": "Arrival Report",
"type": "arrival",
"vessel": {
"id": 87,
"name": "Princess Wave",
"imo": "9999999",
"metadataId": null
},
"position": {
"lat": "-29.796667",
"lon": "31.245000"
}
},
...
]
}
# Get Submission
The get submission endpoint allows you to retrieve a single submission and all of its content.
# Resource URL
https://snapshot-api.stratumfive.com/api/podium/submissions/<submission-id>
# Resource Information
| Info | Value |
|---|---|
| Method | GET |
| Response formats | JSON |
| Requires authentication? | Yes |
| Rate limited? | Yes |
| Requests / minute | 60 |
# Parameters
| Name | Required | Description | Default | Example |
|---|---|---|---|---|
| submission-id | required | The UUID of the submission you wish to retrieve | 9dbbe96b-c435-4fab-87fa-a3945361cec9 | |
| version | optional | The verison of the submission to retrieve | latest | 2 |
# Example Request
GET https://snapshot-api.stratumfive.com/api/podium/submissions/9dbbe96b-c435-4fab-87fa-a3945361cec9?version=2
# Example Response
{
"id": "68731414-34d3-4333-9cf0-9c0375ef22ff",
"date": "2019-09-30T18:48:25.757Z",
"reportDate": "2019-09-30T15:00:00.000Z",
"title": "Position Report",
"status": "complete",
"content": [
{
"title": "Voyage",
"type": "group",
"fields": [
{
"title": "Vessel Name",
"value": "HMS Snapshot",
"type": "text",
"id": "812f384a-d7f7-4540-be3a-cac4066a2938",
"global": {
"id": "385cbbff-283c-4f7f-98a2-09b44ef8a5e8",
"name": "vesselName",
"label": "Vessel Name"
}
},
// ...
]
},
// ..
],
"globalValues": [
{
"fieldId": "812f384a-d7f7-4540-be3a-cac4066a2938",
"globalId": "385cbbff-283c-4f7f-98a2-09b44ef8a5e8",
"value": "Navig8 Victoria",
"sharedGlobalName": "vesselName",
"sharedGlobalLabel": "Vessel Name"
},
{
"fieldId": "506bf4d5-08f3-4a04-b4e4-108e91e6da21",
"globalId": "ddefec26-5c30-4c7f-a083-b6f7afcf7ecf",
"value": "9690614",
"sharedGlobalName": "vesselIMO",
"sharedGlobalLabel": "Vessel IMO"
},
// ...
],
"versions": [
{
"version": 1,
"date": "2019-09-30T18:48:01.870Z",
"status": "pending",
"content": {
"812f384a-d7f7-4540-be3a-cac4066a2938": "HMS Snapshot",
// ...
}
}
],
"vessel": {
"id": 245,
"date": "2019-06-18T07:57:11.110Z",
"updated": "2019-06-18T07:57:11.110Z",
"name": "HMS Snapshot",
"imo": "9999999",
"metadataId": null,
"config": {
"veslinkCode": "ABCD"
},
"fleetId": 3
},
"position": {
"lat": "-34.476667",
"lon": "-51.733333"
}
}
# Field types
The dynamic nature of Snapshot forms means that the content of a submission can vary between the type of form submitted.
Submission content consists of groups containing a set of fields. The structure of a field depends on the specific field type.
# Basic
Basic field types all follow the same format:
{
"title": "Vessel Name",
"value": "HMS Snapshot", // The value entered in the form
"type": "text",
"id": "812f384a-d7f7-4540-be3a-cac4066a2938",
"global": { // The global object is optional
"id": "385cbbff-283c-4f7f-98a2-09b44ef8a5e8",
"name": "vesselName",
"label": "Vessel Name"
}
},
Currently the following types of field will exist in this format:
- text
- multiline
- number
- datetime-gmt
- select
- lat-dms
- long-dms
# Programatically finding fields
When searching for a basic field programmatically we recommend using the global object to search for the field. Either the global ID or the global name should be used.
It is unsafe to use the field ID or the field title when searching as it likely that these could change between form versions. The global name and ID will always stay the same between form versions and are used to add semantic meaning to fields.
# Consumption
The consumption field is used to record how much fuel of a certain type has been consumed, where it has been consumed, and why it has been consumed. It uses a different structure allowing the storage of this data:
{
"id": "6c1326b0-5d4e-4698-bee8-2f57ec522761",
"title": "Consumption",
"type": "consumption",
"fuels": [
{
"name": "LFO",
"consumers": [
{
"title": "Main",
"consumed": 123
},
{
"title": "Aux",
"consumed": 10
},
{
"title": "Boiler",
"consumed": 0
}
],
"usage": [
{
"title": "Propulsion",
"consumed": 123
},
{
"title": "Accomodation",
"consumed": 10
},
{
"title": "Load/Discharge",
"consumed": 0
},
{
"title": "IGS",
"consumed": 0
},
{
"title": "Cargo Heating",
"consumed": 0
},
{
"title": "Tank Cleaning",
"consumed": 0
},
{
"title": "Adj.",
"consumed": 0
}
],
"totalConsumption": 133,
"ROB": 1234
},
// ...
]
},
# Bunker tanks
The bunker tanks field is used to record the current ROB of fuel in the vessel's fuel tanks. It all records the type of fuel currently in the tanks, and when it was supplied. This field also has its own structure:
{
"id": "c4912faf-e15a-4be8-9d4a-65fd8a9abec9",
"title": "Tanks",
"type": "storage-and-content",
"bunkers": [
{
"title": "No.1 HFO Storage (P)",
"fuel": "IFO",
"rob": "169.04",
"observedVolume": "183.50",
"fill": 71.124,
"supplyDate": "2019-09-19"
},
{
"title": "No.2 HFO Storage (P)",
"fuel": "IFO",
"rob": "0.24",
"observedVolume": "0.26",
"fill": 0.103,
"supplyDate": "2019-09-19"
},
// ...
]
}