openapi: 3.0.0
info:
version: 1.0.0
title: Shift72 Discovery API
description: APIs and integrations for discovering content on your site.
servers:
- url: https://{siteUrl}
variables:
siteUrl:
default: vod.shift72.com
description: Url to your Shift72 site
paths:
/services/discovery/v1/films:
get:
operationId: getV1Films
summary: Get films
description: |
Gets availability information about the published films on the site.
This API currently requires a valid authtoken or API key to use.
security:
- AuthToken: []
- ApiKey: []
responses:
'200':
description: An array of film availability information
content:
application/json:
schema:
type: array
items:
type: object
properties:
slug:
description: The slug of the film
type: string
title:
description: Title of the film
type: string
release_year:
description: Release year of the film, if known. This is provided to help matching.
type: string
nullable: true
director:
description: Director of the film if known. This is provided to help matching.
type: string
nullable: true
available_from:
description: |
The earliest time the film can be watched. A film may be
purchasable before this time (i.e. in presale). If null,
the film is watchable immediately.
type: string
nullable: true
format: date-time
available_to:
description: |
The end time of the film's availability. This is a hard cut
off, and playbacks past this point may error out due to
license expiry.
type: string
nullable: true
format: date-time
country_codes:
description: |
The countries where this film is available to watch.
type: array
items:
type: string
refs:
description: Additional ids from the film metadata
type: object
additionalProperties: true
nullable: true
properties:
letterboxd_id:
type: string
description: |
The Letterboxd LID. This can be set from a film's
Integrations tab in admin. This value may be missing or
an empty string.
classifications:
description: The classifications that for this media
type: array
items:
type: object
properties:
geo_region:
description: |
ISO 3166-1 (alpha 2) or ISO 3166-2 code to represent location, converted to lowercase.
Most of the time, this will be a country code, e.g. "ca", but may be a subdivision, e.g. "ca-qc"
type: string
code:
description: The rating code, e.g. "PG" or "R"
type: string
advisory_text:
description: The type of material the media contains
type: string
example:
- slug: /film/281
title: Citizen Kane
director: Orson Welles
release_year: '1941'
available_from: '2023-08-18T00:00:00.000Z'
available_to: null
country_codes:
- nz
- au
refs:
letterboxd_id: 71O
classifications:
- geo_region: nz
code: PG
advisory_text: Parental guidance recommended
- geo_region: au
code: G
advisory_text: Suitable for general audiences
/services/discovery/v1/ad-manager-mrss-feed:
get:
operationId: getV1AdManagerMrssFeed
summary: MRSS feed for Google Ad Manager
description: |
An Atom XML feed for syncing content into Google Ad Manager to allow
targeted client-side ads based on video content.
This contains information about the published media on your platform, with
keyvalues such as genre, classification, etc. that can be used by
advertisers to target certain content.
This feed is paginated and ordered by most recently updated as required by
the Google Ad Manager platform. The XML contains self and next tags for
pagination.
This may be compatible with other supply side platforms that accept the same
schema.
security: []
parameters:
- name: page
in: query
description: Allows you to page through the content.
required: false
schema:
type: number
- name: size
in: query
description: 'How many items in each page? (default: 100)'
required: false
schema:
type: number
responses:
'200':
description: Paged mRSS feed for the site
content:
text/xml:
example: |
My site
https://vod.shift72.com
/film/281Citizen Kane2024-09-01T22:24:45.876Z
/services/discovery/v1/just-watch:
get:
operationId: getV1JustWatch
summary: JustWatch feed
description: |
Provides information about published media on your platform suitable for
integration with JustWatch.
security: []
responses:
'200':
description: JustWatch feed JSON (https://apis.justwatch.com/docs/static/feed.schema.json)
content:
application/json:
schema:
type: object
example:
streaming_service:
name: Your site
url: https://...
content:
- id: /film/281
object_type: movie
original_title: Citizen Kane
release_year: 1941
offers:
- web_url: https://.../film/citizen-kane/
monetization_type: rent
country_iso: NZ
available_from: '2021-03-03T15:19:19.021Z'
currency: NZD
price: 5
components:
securitySchemes:
AuthToken:
type: apiKey
in: header
name: X-Auth-Token
description: A user auth token or API key.
AdminAuthToken:
type: apiKey
in: header
name: X-Auth-Token
description: A user with the admin role
ApiKey:
type: apiKey
in: header
name: X-Auth-Token
description: An API key. This may need specific permissions, documented in the endpoint