Media API

The media API allows access to individual content items.

URL structure

A call to the media API looks very much like an uri, with some additions:

http(s)://tt.se/[mediaType]/[id][-operation][_suffix][.extension]

mediaType and id are part of the uri and uniquely identifies an item in the database.
The extension indicates what type of media (Jpeg, PDF, XML, TTninjs, etc.) we are interested in.
The suffix further qualifies what kind of variant and usage we want.
Finally, the operation indicates whether the object should be transformed in any way.

Operations

Jpeg images can be transformed on the fly by using an image operator.

Watermarking

The -watermark operator inserts a TT Nyhetsbyrån watermark in the lower left corner of the image. It can be used with any image resolution, but works best with previews.

Example:

https://tt.se/media/image/sdltdb3dffd-watermark_NormalPreview.jpg

watermarked panda

Cropping

To crop an image, use the -crop operator and supply the desired dimensions like this (where NN is a numeric value):

_wNN - width in pixels
_hNN - height in pixels
_xNN - x offset in pixels
_yNN - y offset in pixels

There is no automatic scaling adjustment for different image resolutions; you need to calculate and supply the proper dimensions yourself.

Example:

https://tt.se/media/image/sdltdb3dffd-crop_x300_y200_w350_h250_NormalPreview.jpg

cropped panda

Cropping also works for metadata, but it works a little different than jpeg cropping. You supply the dimensions for cropping the hires image, and in return you get a metadata object where the href property of all renditions has been modified by inserting properly scaled -crop operators.

Example:

https://tt.se/media/image/sdltdb3dffd-crop_x300_y200_w350_h250.json

  "renditions": {
    "r00": {
      "usage": "Hires",
      "variant": "Normal",
      "mimetype": "image/jpeg",
      "href": "https://beta.tt.se/media/image/sdltdb3dffd-crop_w350_h250_x300_y200_NormalHires.jpg",
      "width": 350,
      "height": 250,
      "printsize": 50055000
    },
    "r01": {
      "usage": "Preview",
      "variant": "Normal",
      "mimetype": "image/jpeg",
      "href": "https://beta.tt.se/media/image/sdltdb3dffd-crop_w72_h51_x62_y41_NormalPreview.jpg",
      "width": 72,
      "height": 51
    },
    "r02": {
      "usage": "Preview",
      "variant": "Watermark",
      "mimetype": "image/jpeg",
      "href": "https://beta.tt.se/media/image/sdltdb3dffd-crop_w72_h51_x62_y41_WatermarkPreview.jpg",
      "width": 72,
      "height": 51
    },
    "r03": {
      "usage": "Thumbnail",
      "variant": "Normal",
      "mimetype": "image/jpeg",
      "href": "https://beta.tt.se/media/image/sdltdb3dffd-crop_w18_h13_x15_y10_NormalThumbnail.jpg",
      "width": 18,
      "height": 13
    }
  }

Suffix

The suffix usually takes the form _[variant][usage], where variant and usage indicates what variation and resolution we want. This only applies to images and video.

Example:

_NormalHires
_WatermarkedPreview
_CroppedThumbnail

The suffix may also contain an association id: /[association]_[variant][usage]. This is used to refer to a specific media object that has been associated with a text object.

Example:

This is the URL for the preview rendition of the first image associated with the 190308-maggiobayside-899214 text:

https://tt.se/media/text/190308-maggiobayside-899214/a001_NormalPreview.jpg

Extensions

Extensions roughly translates to MIME types.

Extension	MIME type	Description
`.jpg`	`image/jpeg`	Jpeg image
`.pdf`	`application/pdf`	PDF
`.eps`	`application/postscript`	EPS
`.json`	`application/json`	TTNinjs content
`.xml`	`text/xml`	TTNewsML content
`.zip`	`application/zip`	Zipped bundle
`-cutpaste.txt`	`text/plain`	Cut & paste-friendly text
`-indesign.txt`	`text/plain`	Indesign document

Example:

https://tt.se/media/text/190308-maggiobayside-899214.json - metadata in TTNinjs form.
https://tt.se/media/text/190308-maggiobayside-899214.xml - metadata in TTNewsML form.

Authentication

The media API supports OAuth2 token bearer or API Key authentication. Some calls, like fetching metadata of images or thumbnail/preview representations of images, don't require any authentication, but most other calls do.

API Key

Keys are sent as the query parameter ak.

Example request:

curl "https://tt.se/media/text/190308-maggiobayside-899214/a001_NormalHires.jpg?ak=a0bf8f64-e674-439b-ba07-476d069ebba6"

Accessing Hires media

You currently need a TT subscription agreement to access hires media. Downloading an image or triggering a delivery counts as a purchase.

Triggering a delivery

You can use the media API to trigger deliveries programatically in the same way a user would do it on the TT site.

First you need to determine your subscription agreement ID. There are two ways to do this:

Call the GET /user/v1/agreement endpoint in the [Content API]. Use this option if you are using OAuth2 authentication.
Lookup your available agreements with the search API. Use this option of you are using application key authentication.

You also need to configure a delivery channel in the Mina Sidor -> Leveranskanaler page on the TT site. Note the Channel ID, which has the form user:<username>:<channel name>.

To trigger a delivery you make a GET request for the object uri with the following parameters.

agr - the subscription agreement ID.
channel - the channel ID. The channel determines both formats and delivery method.
ak - application key, if you are using application key authentication.

Example:

https://tt.se/media/text/190308-maggiobayside-899214?agr=40768&channel=user:panda:ftp8&ak=443bfbb6-cbc7-482c-b143-6dee6dc4ae8e

Zipped packages

When downloading a zip, we use a download channel to select the contents of the .zip

GET https://tt.se/media/text/151006-senap-162464.zip?channel=user:ttit:skrivbord  # channel deides zip contents

Media API examples

Text

GET https://tt.se/media/text/151006-senap-162464               # redirect to kundwebb
GET https://tt.se/media/text/151006-senap-162464.json          # ttninjs
GET https://tt.se/media/text/151006-senap-162464.xml           # ttnewsml
GET https://tt.se/media/text/151006-senap-162464.zip           # article and images packaged up

GET https://tt.se/media/text/151006-senap-162464-cutpaste.txt  # cut-paste txt variant
GET https://tt.se/media/text/151006-senap-162464-indesign.txt  # indesign document

GET https://tt.se/media/text/151006-senap-162464/a000_NormalPreview.jpg    # association a000 normal preview
GET https://tt.se/media/text/151006-senap-162464/a000_NormalThumbnail.jpg  # association a000 normal thumb
GET https://tt.se/media/text/151006-senap-162464/a000_CroppedThumbnail.jpg # association a000 cropped thumb
Image

Image

GET https://tt.se/media/image/sdltaa20b4b                            # redirect to kundwebb
GET https://tt.se/media/image/sdltaa20b4b.json                       # ttninjs
GET https://tt.se/media/image/sdltaa20b4b.xml                        # ttnewsml
GET https://tt.se/media/image/sdltaa20b4b.zip                        # image and metadata packaged up
GET https://tt.se/media/image/sdltaa20b4b.jpg                        # hires jpg
GET https://tt.se/media/image/sdltaa20b4b_NormalHires.jpg            # hires jpg
GET https://tt.se/media/image/sdltaa20b4b_NormalPreview.jpg          # normal preview jpg
GET https://tt.se/media/image/sdltaa20b4b_NormalThumbnail.jpg        # normal thumb jpg

Graphics

GET https://tt.se/media/graphic/gf177556                             # redirect to kundwebb
GET https://tt.se/media/graphic/gf177556.json                        # ttninjs
GET https://tt.se/media/graphic/gf177556.xml                         # ttnewsml
GET https://tt.se/media/graphic/gf177556.zip                         # graphic and metadata packaged up
GET https://tt.se/media/graphic/gf177556.pdf                         # hires color pdf
GET https://tt.se/media/graphic/gf177556_BlackAndWhiteHires.pdf      # hires b/w pdf
GET https://tt.se/media/graphic/gf177556.eps                         # hires color eps (if available)
GET https://tt.se/media/graphic/gf177556_BlackAndWhite.eps           # hires b/w eps (if available)
GET https://tt.se/media/graphic/gf177556_NormalPreview.jpg           # normal preview jpg
GET https://tt.se/media/graphic/gf177556_NormalThumbnail.jpg         # normal thumb jpg
GET https://tt.se/media/graphic/gf177556_CroppedThumbnail.jpg        # cropped thumb jpg

Video

GET https://tt.se/media/video/sdltaa1f67a                            # redirect to kundwebb
GET https://tt.se/media/video/sdltaa1f67a.json                       # ttninjs
GET https://tt.se/media/video/sdltaa1f67a.xml                        # ttnewsml
GET https://tt.se/media/video/sdltaa1f67a_NormalThumbnail.jpg        # normal thumb jpg
GET https://tt.se/media/video/sdltaa1f67a_NormalPreview.mp4          # normal preview mp4

media-api

Media API

URL structure

Operations

Watermarking

Example:

Cropping

Example:

Example:

Suffix

Example:

Example:

Extensions

Example:

Authentication

API Key

Accessing Hires media

Triggering a delivery

Example:

Zipped packages

Media API examples

Text

Image

Graphics

Video