Media File | MyGeotab | Geotab Developers

The media file API provides a persistent storage mechanism for binary media files and meta data. There are two components of a media file:

The MediaFile entity which describes the binary media. This is similar to other generic entity types in the API and follows the generic entity method pattern (Add, Get, Set, Remove, GetFeed).

The binary data of the media file. This the the actual file, for example a jpeg image. The binary files are interacted with using bespoke methods DownloadMediaFile and UploadMediaFile.

Object model

MediaFile

Property	Type	Description
Device	Object	The Device associated with the file.
Driver	Object	The Driver associated with the file.
FromDate	String	The from date.
Id	String	The unique identifier for the specific Entity object in the Geotab system. See Id.
MediaType	String	The MediaType.
MetaData	Object	File metadata in JSON format.
Name	String	The name of this entity which identifies it and is used when displaying this entity.
SolutionId	String	The user-generated unique Id to associate the MediaFile data to a particular solution/integration (example to generate solutionId)
Status	String	The file processing Status.
Tags	Array	The list of tags to provide context to the file.
Thumbnails	Array	The list of files which serve as the thumbnail for this file.
ToDate	String	The to date.
Version	String	The version of the entity.

Name and Solution ID are required.

Solution ID

A SolutionId must be created before the Storage API methods can be used within your solution. This encoded GUID is used to register and identify which solution some data is associated with. SolutionId is a mandatory parameter when calling MediaFile Add, optionally with Get. This allows each solutions' data to be isolated from the data used by other solutions. This allows multiple solutions to each have their own collection of MediaFile objects in the same database without the collections mixing. To generate your own SolutionId, please use following example.

SolutionId and AddInId are interchangeable. If you have an Add-In or integration which uses both AddInData and MediaFile you are encouraged to use a single SolutionId/AddInId.

MediaFileSearch

Property	Type	Description
DeviceSearch	Object	Filter by the DeviceSearch options. Providing a device ID will search for any MediaFiles that are assigned to that Device. Providing the Groups will search for MediaFiles for that have Devices in that group. Available DeviceSearch options are: Id Group
DriverSearch	Object	Search for MediaFile with this UserSearch Id. Available UserSearch options are:. Id
FromDate	String	Search for MediaFile records at this date or after. Includes overlapping dates.
Id	String	Search for an entry based on the specific Id.
SolutionId	String	Search for MediaFile records with this SolutionId.
TagSearch	Object	Search for MediaFile with this TagSearch. Available TagSearch options are:. Id TagIds
ToDate	String	Search for MediaFile records at this date or before. Includes overlapping dates.

Tag

Property	Type	Description
Id	string	GUID backed unique identifier
Version	string	Entity version. Read-only
Name*	string	File name. Must have extension. Max 1024 characters. All lower case. Required. Unique

Supported file types

Type	Extension	Content-Type
Video	mp4	video/mp4
Image	jpeg	image/jpeg
Image	png	image/png
Image	gif	image/gif
Image	webp	image/webp

Security

Credentials

Credentials are required for all MediaFile and Tag related requests.

Security clearances

There are two security clearances applying to media files. By default only administrator clearance will be able to modify files, while clearances derived from view only will be able to view files. SecurityIdentifier: ViewMedia, ManageMedia.

Scope

Scope is evaluated by the scope of the requesting user to the linked entity(s) (Device and/or Driver) of the media file. A media file with no linked entity will be visible to any user in the database regardless of scope (requiring ViewMedia clearance).

API

Method	Notes
Add[MediaFile]	File is added via separate API. Status = NoFile
Set[MediaFile]	Updates MediaFile entity, not file
Remove[MediaFile]	Removes file and MediaFile entity
Get[MediaFile]	Gets only MediaFile entity
GetFeed[MediaFile]	Gets a feed of only media file entity
DownloadMediaFile	Content type determined by file extension. Range headers supported
UploadMediaFile	Media file entity must already be added. Content-Type “multipart/form-data”. Not “application/json”

Add

Adding a media file requires two steps:

First, adding the MediaFile entity using the generic Add method. The result of adding is the unique identifier (Id) of the added MediaFile. When the media file has been added but there is no binary uploaded the MediaFile.Status will be NoFile.

Second, uploading the MediaFile binary using the UploadMediaFile API specifying the MediaFile it relates to by Id in the JSON-RPC request. After a file is uploaded the MediaFile.Status will transition to Processing then Ready.

Processing state is available but currently unused.

Get

Like Add, Get requires two steps:

First, search for MediaFile using MediaFileSearch to provide search arguments.

Second, download the binary using the DownloadMediaFile method providing the Id of the media file.

Limits

Result limit

A maximum of 10,000 MediaFile objects will be returned from Get:MediaFile and/or GetFeed:MediaFile requests.

Rate Limit

Method	Description	Limit	Period	Status
Get	Limit of 350 Get requests per 1m.	350	1m	Active
Set	Limit of 60 Set requests per 1m.	60	1m	Active
Add	Limit of 60 Add requests per 1m.	60	1m	Active
Remove	Limit of 60 Remove requests per 1m.	60	1m	Active
GetCountOf	Limit of 100 GetCountOf requests per 1m.	100	1m	Active
GetFeed	Limit of 60 GetFeed requests per 1m.	60	1m	Active

Size limit

Image files (.png, .jpg, .gif, .webp) are limited to 10MB. Video files (.mp4) are limited to 50MB.

In MyGeotab v6.0 file size limits were increased. Images from 2MB to 10MB and of videos from 10MB to 50MB.