SSDV - API documentation

URLs
Notes
Packet Format
/api/v0/packets
/api/v0/images
/api/v0/images/:id
/latest.php

URLs

The website supports several URL formats for displaying archived images or images from individual callsigns:

https://ssdv.habhub.org [Latest live images] https://ssdv.habhub.org/CALLSIGN [Latest live images for CALLSIGN only] https://ssdv.habhub.org/CALL1,CALL2 [Latest live images for multiple callsigns] https://ssdv.habhub.org/YYYY-MM-DD [Archived images received on specified date] https://ssdv.habhub.org/CALLSIGN/YYYY-MM-DD https://ssdv.habhub.org/CALL1,CALL2/YYYY-MM-DD

Query string parameters:

Parameter	Description	Default
tz	Display and filter dates in this timezone. (Eg.: tz=Europe/London)	UTC

Notes

Dates

The API only uses UTC time, and returns dates in an ISO-8601 format. When sending a date any of the following formats are valid:

2015-10-22 [Same as 2015-10-22T00:00:00Z] 2015-10-22T15:27:40+00:00 2015-10-22T15:27:40Z

Packet Format

Offset	Name	Size	Description
0	Sync Byte	1	0x55 - May be preceded by one or more sync bytes
1	Packet Type	1	0x66 - Normal mode (224 byte packet + 32 byte FEC) 0x67 - No-FEC mode (256 byte packet)
2	Callsign	4	Base-40 encoded callsign. Up to 6 digits
6	Image ID	1	Normally beginning at 0 and incremented by 1 for each new image
7	Packet ID	2	The packet number, beginning at 0 for each new image (big endian)
9	Width	1	Width of the image in MCU blocks (pixels / 16) 0 = Invalid
10	Height	1	Height of the image in MCU blocks (pixels / 16) 0 = Invalid
11	Flags	1	00qqqexx 00 = Reserved qqq = JPEG quality level (0-7 XOR 4) e = EOI flag (1 = Last Packet) xx = Subsampling Mode (0 = 2×2, 1 = 1×2, 2 = 2×1, 3 = 1×1)
12	MCU offset	1	Offset in bytes to the beginning of the first MCU block in the payload, or 0xFF if none present
13	MCU index	2	The number of the MCU pointed to by the offset above (big endian), or 0xFFFF if none present
15	Payload	205 / 237	Payload data
220 / 252	Checksum	4	32-bit CRC
224	FEC	32	Reed-Solomon forward error correction data. Normal mode only (0x66)

Sizes and offsets are in bytes, with each packet normally 256 bytes in total.

Payload data / Image Format

The image should contain just the scan data from a JPEG image (an “Abbreviated image” in JPEG terminology), with none of the markers or headers that normally make up a JPEG image. The image must conform to the following rules:

Y′CbCr colour format
Width and height must be a multiple of 16 (up to a resolution of 4080 x 4080)
The quantisation and huffman tables are fixed
Baseline DCT only
Total scan data must not exceed 13434880 bytes (~12.8 MB) in length (205 payload bytes per packet, 65536 packets max)
The first MCU of each packet is byte aligned
The first DC values for each component in the first MCU of a packet are relative to 0
The scan data does not use byte stuffing (0xFF bytes do not need to be followed by 0x00)
The total number of MCU blocks must not exceed 65535

Error Correction

Each normal packet ends with 32 bytes of Reed-Solomon (255,223) codes, calculated from the 223 bytes beginning with the packet type (offset 1) to the end of the payload data. These codes allow the receiver to correct up to 16 byte errors in a received packet (including the Reed-Solomon codes themselves).

/api/v0/packets

POST

Submit one or many SSDV packets to the live page. The server will return with the ID of the image the packets where assigned to, or an error on failure.

POST Body (Single Packet)

{ "type": "packet", "packet": "packet data", [The SSDV packet, encoded as per below] "encoding": "base64", [Use "base64" or "hex"] "received": "2015-10-21T15:41:36Z", [Time the packet was received] "receiver": "MI0VIM", [Receivers callsign] "fixes": 2 [Optional, number of bytes corrected by the FEC] }

Response

Returns the ID of the image the packet was assigned to.

POST Body (Multiple Packets)

{ "type": "packets", "packets": [ { "type": "packet", "packet": "packet data", [The SSDV packet, up to 256 bytes encoded as per below] "encoding": "base64", [Use "base64" or "hex"] "received": "2015-10-21T15:41:36Z", [Time the packet was received] "receiver": "MI0VIM", [Receivers callsign] "fixes": 2 [Optional, number of bytes corrected by the FEC] }, ... ] }

Response

Returns the ID of each image the submitted packets where assigned to.

/api/v0/images

GET

Fetch information for images.

Parameter	Description	Default
callsign	Return images with this callsign
id	Returns images with this image ID
from	Return images created on or after this time (Eg.: 2015-10-23T00:00:00Z)
until	Return images created up to but not including this time
last_id	Return images updated since this packet ID
include_packets	Include details on each packet received	false
missing_packets	Include a list of known missing packets	false
sort	Set the order of the results (asc / desc)	asc
limit	Limit the number of images returned

Response

Returns an array of images matched by the parameters. See below for an example of the JSON returned.

/api/v0/images/:id

Option	Description
:id	The ID of the image being queried

GET

Fetch information for an individual image.

Parameter	Description	Default
include_packets	Include details on each packet received	false
missing_packets	Include a list of known missing packets	false

Response

{ "type": "image", "id": 5164, [The unique identifier for this image] "callsign": "EAGLE", [The callsign of the image sender] "image_id": 2, [The image ID set by the sender] "width": 512, [Width of the image in pixels] "height": 288, [Height of the image in pixels] "subsampling": "2x2", [JPEG subsampling mode used] "packet_type": "normal", [SSDV packet type, "normal", or "nofec"] "packet_length": 256, [SSDV packet length in bytes, normally 256] "packets_received": 2, [Number of packets received] "packets_missing": 2, [Number of packets known to be missing] "last_packet": 3, [The highest packet ID received] "received_eoi": true, [True if a packet has the EOI flag set] "created": "2015-10-21T15:41:36Z", [Time the first packet was submitted] "updated": "2015-10-21T15:43:53Z", [Time the last packet was submitted] "received_by": [ "MI0VIM", "Bob", "Lunar_Lander" ], [List of receivers who uploaded data for this image] "image_href": "http://ssdv.sanslogic.co.uk/images/20151021-154136-EAGLE-2.jpeg?u=2", [A link to the decoded JPEG image] "data_href": "http://ssdv.sanslogic.co.uk/images/20151021-154136-EAGLE-2.bin?u=2", [A link to the received SSDV data] "packets": [ [An optional array containing details on each packet received] { "packet_id": 0, [Packet number] "eoi": false, [True if the EOI flag was set in this packet] "received_by": [ "MI0VIM", "Bob", "Lunar_Lander" ] [List of receivers who uploaded this packet] }, { "packet_id": 3, "eoi": true, "received_by": [ "MI0VIM", "Bob" ] } ], "missing_packets": [ 1, 2 ] [An optional array listing the ID of each packet known to be missing] }

/latest.php

GET

Parameter	Description	Default
callsign	Return images with this callsign

Response

Returns a 302 redirect to the latest image for the specified callsign, or a 404 error if no matching image was found.