Teleport Api
Integrate Teleport into your solution using embedding and APIs

Overview

  • Using the Teleport APIs you can create, manage, view and broadcast Teleport feeds.
  • These are simple REST based apis that return JSON and are easily consumed from any website or app.
  • Get your APIKEY from the Account Dashboard -> Api section. It can be either the primary or secondary key.
  • Get your ACCESSKEY from the Feed Dashboard -> Embed & Link -> Public image links section. It gives view only access to the feed.

Player embedding

  • The embed code is as follows:
    <iframe width="WIDTH" height="HEIGHT" src="https://api.teleport.io/api/v2/player?feedid=FEEDID&frametime=FRAMETIME&playmode=PLAYMODE&playmodespossible=PLAYMODESPOSSIBLE&framesizingmode=FRAMESIZINGMODE&showsplashbadge=SHOWSPLASHBADGE&showoverlaybadge=SHOWOVERLAYBADGE&overlayopacity=OVERLAYOPACITY&backgroundcolor=BACKGROUNDCOLOR&videoplayspeed=VIDEOPLAYSPEED&imageplayspeed=IMAGEPLAYSPEED&playframeskipinterval=PLAYFRAMESKIPINTERVAL&playframecount=PLAYFRAMECOUNT&accesskey=ACCESSKEYcustomArgs#" frameborder="0" allow="fullscreen" allowfullscreen></iframe>
  • Also you can embed the player without black with auto sizing using the script method
  • You can embed multiple players on a single page by using multiple iframe embed codes.
  • FEED is the feed is found in the feed profile url or on this page api dashboard page.
  • PLAYMODE is one of [liveimage, liveimageloop, livetimelapse, historyimage].
  • WIDTH,HEIGHT are pixel values. Use 100% for width to fill available horizontal space.
  • PLAYMODESPOSSIBLE is a comma separated list of the above.
  • FRAMESIZINGMODE one of [auto, uniformtofill, uniform].
  • FRAMETIME is the timestamp must refer to an existing frame, it the frame does not exist the most recent or live frame will be shown. Format must be 2024-01-14T21:07:17Z, this is the UTC 8601 format. Get this value from the player share section, while viewing the frame of interest.
  • IMAGEPLAYSPEED controls how fast images change in live loop and history image play modes. Value one of formats can be ?.??sec, ?.??fps or ?.??x.
  • PLAYFRAMESKIPINTERVAL controls the time interval between each played frame in live loop and history image play modes. Value one of [sec, min, 5min, 15min, hour, day, month]. Custom value not accepted at this time. Email us if this is a requirement.
  • PLAYFRAMECOUNT controls how many frames to play. Applies to live loop play mode only at this time. Value between 1 and 1000.
  • VIDEOPLAYSPEED controls how fast time-lapse video is paid, formats can be ?.??sec, ?.??fps or ?.??x, value is a original video rate multiplier.
  • APIKEY embed the player with an api key, giving it access to all feeds on the given account, including non-public feeds. WARNING: do not use this on public websites!
  • ACCESSKEY embed the player with a share key, giving it access to the feeds using this share key, including non-public feeds.
  • More coming soon! Please contact us for any help.

Example of an embedded feed player with custom options, uniform sizing and live loop as default play mode

Demo code

V2 Player Embedding

Demo code

V2 player has minimal UI and started life supporting non-interactive scenarios such as digital sign/lobby TV with a custom playlist. UI will be added and it will replace the v1 player shortly.

Access a live feed image

  • https://www.teleport.io/api/v2/frame-get?feedid=FEEDID&sizecode=SIZECODE&apikey=APIKEY&accesskey=ACCESSKEY
  • Returns actual jpg image data of the specified image size.
  • SIZECODE is one of [x480, x768, x1080, x2160, x4320] image sizes
  • The image size is guaranteed to be at most the specified size. It may be smaller if the feed does not have the specified size.
  • Guaranteed to return an image if one exists regardless of SIZECODE.
  • Http method: GET

Demo code

Access a recorded feed image

  • https://www.teleport.io/api/v2/frame-get?feedid=FEEDID&frametime=FRAMETIME&sizecode=SIZECODE&timematch=TIMEMATCH&apikey=APIKEY&accesskey=ACCESSKEY
  • Returns the jpg image data of the specified image size, recorded at the requested time. If the time must be accurate to the second, otherwise a 404 error is returned.
  • FRAMETIME is in UTC format i.e. 2024-09-21T01:25:47Z
  • SIZECODE is one of [x480, x768, x1080, x2160, x4320] image sizes
  • TIMEMATCH is one of [closest-future, closest-past, closest-any, exact], it defaults to exact, which means if not specified and the image does not exist for the given frame time, no image is returned.
  • The image size is guaranteed to be at most the specified size. It may be smaller if the feed does not have the specified size.
  • Guaranteed to return an image if one exists regardless of SIZECODE.
  • If the image does not exist add the optional &sizecode=c to query for the closest existing image to the provided timestamp, without this you will get a 404 return.
  • Http method: GET

Demo code

Access recorded time-lapse video

  • https://www.teleport.io/api/v2/video-get?feedid=FEEDID&videoquery=VIDEOQUERY&videotype=VIDEOTYPE&videopartnumber=VIDEOPARTNUMBER&sizecode=SIZECODE&querydata=QUERYDATA&apikey=APIKEY&accesskey=ACCESSKEY
  • Returns the mp4 video data for video/video part that satisfies the query by video name and video type. The queryData parameter if set, returns JSON query result data instead of video content.
  • VIDEOQUERY the full or partial name of the video profile to match, for example 'all-time' or 'recent'. To be more specific a | separated list of query strings in the order of videoProfile | videoName or videoSpeed. For example "all-time|108,000x" or for example "recent|Last 30 days"
  • VIDEOTYPE one of [live, complete], returns the complete final video if exists or the live video.
  • SIZECODE is one of [x480, x768, x1080, x2160, x4320] video sizes, attempts to match video with specific size, if it exists as part of the video profile and has been generated.
  • QUERYDATA set to true to return JSON data with basic video info such as duration and number of parts.
  • https://www.teleport.io/api/v2/video-get?feedid=FEEDID&videoResourceId=VIDEORESOURCEID&videoId=VIDEOID&videoPartId=VIDEOPARTID&rt=VIDEOTIMESTAMP&apikey=APIKEY&accesskey=ACCESSKEY
  • Returns the mp4 video data for the specific video/video part. The ids are part of the queryData=true query. Videos are naturally chunked into multiple parts to prevent having to deal with 20-50GB files.
  • RT Video timestamp ensures you retrieve the latest version of the live video, get this value from the query data result using the querydata=true parameter.
  • Http method: GET

Demo code

Get feed information

  • https://www.teleport.io/api/v2/feed-get?feedid=FEEDID&apikey=APIKEY&accesskey=ACCESSKEY
  • Returns feed properties, such as name, description, etc.
  • Http method: GET

Demo code

Query recorded frames

  • http://www.teleport.io/api/v2/frame-query?feedid=FEEDID&starttime=STARTTIME&endtime=ENDTIME&interval=INTERVAL&apikey=APIKEY&accesskey=ACCESSKEY
  • Returns an array of timestamps, for use in a frame-get or frame-delete method.
  • STARTTIME is in UTC format i.e. 2024-09-21T01:25:47Z
  • ENDTIME is in UTC format i.e. 2024-09-21T01:25:47Z
  • INTERVAL is how many seconds between each frame, use this to reduce the set of returned values. i.e. 3600 to return frames 1 hour apart.
  • Http method: GET

Demo code

Delete recorded frames

  • http://www.teleport.io/api/v2/frame-delete?feedid=FEEDID&frametime=FRAMETIME&apikey=APIKEY
  • Permanently deletes the specified frame.
  • Use the frame-query API to get frame timestamps.
  • FRAMETIME the exact frame timestamp to delete, it is in UTC format i.e. 2024-09-21T01:25:47Z
  • APIKEY is required to delete on all feeds. ACCESSKEY is ignored by this method.
  • Http method: DELETE

Demo code

Upload an image to a feed

  • http://www.teleport.io/api/v2/frame-set?feedid=FEEDID&frametime=FRAMETIME&broadcastkey=BROADCASTKEY&apikey=APIKEY
  • Permanently deletes the selected frames.
  • FRAMETIME is time the frame was recorded, in UTC format i.e. 2024-09-21T01:25:47Z. If not present the current UTC time is used.
  • A broadcast key or an api key is required to upload frames.
  • The body of the request must contain the image data in binary representation. PNG or JPEG are supported.
  • The content must be less than 10MB.
  • Http method: POST

Demo code, upload from file

Demo code, upload from webcam (chrome, firefox, opera, android only)

Import historical, or broadcast live images to Teleport

  • Easily broadcast PNG or JPG images using a PowerShell script.
  • The script can also be used to upload live images for example from a local folder into which another app places images.
  • The script uses the public APIs above, so you can easily modify it to fit custom needs.
  • Download the Teleport PowerShell broadcast script

Export recorded data

How to use the Teleport PowerShell export script:

  • The script isn't signed so you may get warnings from Windows as you should only download and run scripts you know about. Right click on the downloaded file, goto Properties and Unblock it.
  • To run the script, get into PowerShell, one way is to hit Windows + R and type powershell and click 'OK'.
  • On prompt type $PSVersionTable.PSVersion to get the Powershell version, if Major isn't 4 or greater you need to upgarde. Install Powershell 7.1 from here.
  • Next enable execution policy on your computer, to do this you must run PowerShell as Administrator. Right click on the PowerShell icon in the task bar and click Run as administrator. Type Set-ExecutionPolicy Unrestricted. Once you're done exporting type Set-ExecutionPolicty Restricted to bring it back for best practice.
  • Now in the PowerShell window go to the folder where the script is downloaded using cd C:\Users\UserName\Downloads command.
  • And finally type .\teleport-export.ps1 to run the script. Here you will be asked to enter all parameters and begin the export. For each command type !? to get help.
  • To run directly from command you use : .\teleport-export.ps1 -feedId 'feedid' -startTime 20240601T000000 -endTime 20240901T000000 -interval 20000 -sizeCodes ('x480', 'x768', 'x1080', 'x2160', 'x4320') -key 'apikey or accesskey' -exportFolder 'C:\TeleportExport\'
  • The interval argument is the time between exported frames in seconds. i.e. a value of 0 exports all frames, 60 export frames 60 sec apart.
  • To export only the largest available images (skipping scaled down copies) use just the 'x4320' sizeCode argument or leave it empty.
  • To load the script into Powershell, run . .\teleport-export.ps1 (note the extra . and space before the main command)
  • Once you do this, type Teleport-Export to run the export function directly, or get-help Teleport-Export -detailed to get help.

Download the export script using command line on Linux, MacOS or Windows

  • Install Powershell for Linux or Mac OS, Windows comes with it installed.
  • Start a Powershell terminal window and execute this command to download the Teleport export script: 
    
    # on Linux or OSX
    wget -q https://blob.teleport.io/apps/powershell/teleport-export.ps1 -O teleport-export.ps1

    # on Windows this is done using
    Invoke-WebRequest -Uri https://blob.teleport.io/apps/powershell/teleport-export.ps1 -OutFile teleport-export.ps1
  • Give it execute permission, not required on Windows: 
    
    chmod +x teleport-export.ps1
  • And run it: 
    
    ./teleport-export.sh

Here is an example command, which will export the 4K, and 1080p images between the given dates, interval 0 downloads all images. 

    .\Teleport-Export -feedId yourFeedId -sizeCodes 'x2160', 'x1080' -key yourApiKey -startTime 2021-01-22T00:00:00Z -endTime 2023-01-22T00:00:00Z -interval 0 -exportFolder "C:\TeleportExport\"