Getting Started
Introduction and Assumptions
Reading this document assumes you are familiar with:
- Retrieving the ID of Company to which the image will be assigned.
- Using the WebSocket, and retrieving your ghostId.
- Using HTTP with the correct headers to POST serialized image data.
All image uploads use POST, and all image views use GET. The domain is the same for all operations, only the URL changes. The URLIs will always follow the following format: https://img.fleetfreedom.com/<operation>?ghostId=ghostId&optional=parameters .
Uploading
There are two functions for uploading images; the normal way and the "selfie" way. The subtle difference between the two methods is that for normal uploads, the companyId must be included as a POST key where the selfie way will always save the image to the session user's company (even if the companyId is POSTed).
Remember
The MIME (Content-Type header) of any image uploaded must be:
- image/jpg or image/jpeg
- image/png
- image/gif
The maximum file size per image is 5 MB.
The maximum total storage per company depends on the details of it's billing rules.
The field names (separate from the file names) are set by you, and are returned in the response so you can correlate image uploads with responses.
URL patterns
https://img.fleetfreedom.com/selfie?ghostId=ghostId
https://img.fleetfreedom.com/upload/companyId?ghostId=ghostId
These paths have changed so that the ghostId is passed in the query string, and the target company for an upload is in the URL instead of the POST body.
Request body
Content-Type: multipart/form-data; boundary=8d36fa118ca5f82
--8d36fa118ca5f82
Content-Disposition: form-data; name="image_1;" filename="Andrew.jpg"
Content-Type: image/jpeg
... contents of Andrew.jpg ...
--8d36fa118ca5f82
Content-Disposition: form-data; name="image_2"; filename="Tarah.png"
Content-Type: image/png
... contents of Tarah.png ...
--8d36fa118ca5f82--Response fields
| Property | Type | Description |
|---|---|---|
| errorCode | ErrorCode | A code describing the error processing this request (if any). |
| message | string | A human readable message describing the error processing this request (if any). |
| accepted | object{string:Picture} | This is a dictionary of Pictures which were successfully uploaded to the company. The key in the object corresponds to the field name used in the upload request. |
| rejected | object{string:ErrorCode} | This is a dictionary of failure messages for the images which did not upload. The key in the object corresponds to the field name used in the upload request. |
Remember
It's important to note that the newly created Pictures give their "src" without the full URL. This is due to the retrieval of those images depending on the application and user session.
So when retrieving, always prepend the application domain and ghostId.
Response body format
{
"errorCode": number,
"message": string,
"accepted": {
string: Picture
},
"rejected": {
string: number
}
}
Example
{
"errorCode": 0,
"message": "Upload complete",
"accepted": {
"image_1": {
"id": 1234,
"company": 42,
"name": "Andrew.jpg",
"notes": "",
"src": "/photo/1234",
"size": {
"width": 1920,
"height": 1080
},
"focals": [],
"v": [1]
}
},
"rejected": {
"image_2": 91
}
}Viewing, Re-sizing, and Cropping
The response contains the actual image file, the same as if you had requested an image file from a web-server directly. Semi-standard HTTP response status codes are used.
These are four ways to retrieve an image:
- In its original size.
- Re-sized and un-cropped with the aspect ratio preserved.
- Re-sized, cropped with a new aspect ratio, and centred.
- Re-sized, cropped with a new aspect ratio, and the centre moved according to the given coordinates.
Original size
The image is returned in its original size. The file may have been re-compressed or re-processed by the server so do not expect a bit-wise identical image.
https://img.fleetfreedom.com/photo/pictureId?ghostId=ghostIdRe-sized
Re-sizing is accomplished by using the "size" parameter in the request's query string and specifying only one number (unsigned integer). This number will restrict the maximum height and width of the returned image without affecting the aspect ratio.
For landscape (wider than taller) images, the width is set as the number and the height is adjusted so the aspect ratio is preserved. For portrait (taller than wider) images, the height is set as the number, and the width is adjusted accordingly.
https://img.fleetfreedom.com/photo/pictureId?ghostId=ghostId&size=maxWidthOrHeightRe-sized and Cropped
Re-sizing is accomplished by using the "size" parameter in the request's query string and specifying two numbers (unsigned integer). These numbers will restrict the maximum height and width of the returned image.
If the image needs to be cropped, to maintain the given aspect ratio, the image is centred on the new canvas.
https://img.fleetfreedom.com/photo/pictureId?ghostId=ghostId&size=maxWidth,maxHeightRe-sized, Cropped, and Moved
Re-sizing is accomplished by using the "size" parameter in the request's query string and specifying four numbers (unsigned integer). These numbers will restrict the maximum height and width of the returned image, and provide a new top/left pixel coordinate to use for drawing.
https://img.fleetfreedom.com/photo/pictureId?ghostId=ghostId&size=left,top,maxWidth,maxHeight