Click or drag to resize
POST /photos
Print this page

This topic contains the following sections:

Description

Use this service to add a photo attachment and associated metadata to those available for retrieval.

Note Note

Photo support is specific to adding images to Mobile forms, not driver profiles. You can manage driver profile photos from the Fleet platform.

Remarks

Because a photo includes both JSON (metadata) and binary (the image file) components, the upload is a two-step process:

  1. Submit a POST /photos request to upload the JSON metadata for the photo.
  2. Upload the photo by submtting a PUT request to upload the image file to the URL location for photo storage.

Request

The following example shows the request to submit the JSON metadata for a photo. You must supply a name, but the other fields are optional.

JSON
Copy
POST /photos
 {
   "name":"AustinAirport",
   "captureTime": "2017-01-02-03T04-05-06Z"
 }

You have the option to include an id in the request:

  • If an id is not specified, then the service creates a new photo that matches the description.

  • If an id is specified, then the service interprets it as a create or update request. If no photo exists with the specified id, then a photo is created. Otherwise, the existing photo is updated.

The request body is a JSON array with a Photo object. The JSON metadata has the following parameters. Read-only fields are populated automatically after the photo is posted:

Member Type Purpose
id string The GUID of the photo.
name string (Telogis key) The name of the image file, which must be unique. If the file extension is not specified, browser clients derive it from the content type.
path string (optional) User-specified path on the file system for photo files.
captureTime string The ISO 8601 timestamp for when the photo was taken.
captureAddress Address The location where the photo was taken.
Member Type Purpose
street string The street number and name of the address.
city string The city in which the address is located.
region string The region in which the address is located (e.g., state or province).
postalCode string The postal code or zip code of the address.
lat double (required for POST) The latitude of the address in decimal degrees.
lon double (required for POST) The longitude of the address in decimal degrees.
bearingFromStreet double? The side of the road on which the address is located, indicated as an angle in decimal degrees (0 is north, 90 is east).
suburb string The suburb in which the address is located.
fullImageUrl Uri (read-only) The URL to the photo image file.
sizeInBytes int? (read-only) The size of the image file, in bytes.
pixelHeight int? (read-only) For aspect ratio as x:y, the photo's height (y) in pixels.
pixelWidth int? (read-only) For aspect ratio as x:y, the photo's width (x) in pixels.
contentType string (read-only) The MIME Content-Type (file format) that was uploaded. Typical values: 'image/jpeg', 'image/png'.

Response

On success, the response body returns a NewPhoto object that includes the id for the photo and the URL location for posting the associated photo attachment:

JSON
Copy
[{
"id": "abcdefa01234567abcdefa0123456789",
"putUrl": "/attachments/abcdefa01234567abcdefa0123456789"
}]
Tip Tip

Because connection problems could prevent you from getting back the response (which has the new photo's ID), the service supports reposting of the photo and form, which TDE acknowledges with an alreadyExists flag. The service detects any repeated "create" posts by use of an existing name and returns the associated ID and URL.

Upload attachment - PUT /attachments

After you post the JSON metadata, use the PUT /attachments operation to upload the image source file. Include the putURL returned in the POST /photos response in the URI, and the file to upload in the request body.

Copy
PUT {baseURL}/attachments/b2675eaf-0f79-43d2-84a8-5d17bd9a01ba?auth=e93424547f88400cbe3b0d86304a0e0d
If the request fails, an Error Response is generated.